[chore] [mdatagen] Add docs for the new re-aggregation capability

Author: dmitryax

cmd/mdatagen/README.md

@@ -98,6 +98,94 @@ The `config` section is based on [JSON Schema standard](https://json-schema.org/
 - **Reusable definitions**: Define common schemas in `$defs` and reference them with `$ref`
 - **Schema composition**: Use `allOf` for complex configurations
 
+### Metrics Builder Configuration
+
+For receivers, scrapers, and other components that emit metrics, `mdatagen` can generate metrics builder
+configuration from `metadata.yaml`.
+
+```yaml
+type: myreceiver
+status:
+  class: receiver
+  stability:
+    beta: [metrics]
+
+resource_attributes:
+  transport:
+    description: Transport used by the request.
+    type: string
+    enabled: true
+
+attributes:
+  status_code:
+    description: Response status code.
+    type: int
+    requirement_level: opt_in
+
+metrics:
+  http.server.request.count:
+    enabled: true
+    description: Number of received requests.
+    unit: "{request}"
+    sum:
+      value_type: int
+      monotonic: true
+      aggregation_temporality: cumulative
+    attributes: [status_code]
+```
+
+This lets users:
+
+- enable or disable individual metrics
+- enable or disable resource attributes
+- use `metrics_include` and `metrics_exclude` on resource attributes to only emit metrics with matching resource attribute values
+
+### Metric Reaggregation Configuration
+
+Set `reaggregation_enabled: true` to let users reduce metric cardinality by dropping selected metric
+attributes and aggregating the resulting datapoints.
+
+```yaml
+reaggregation_enabled: true
+
+attributes:
+  transport:
+    description: Transport used by the request.
+    type: string
+    requirement_level: recommended
+  status_code:
+    description: Response status code.
+    type: int
+    requirement_level: opt_in
+```
+
+This adds two per-metric settings for metrics that declare attributes:
+
+- `attributes`: the subset of metric attributes to keep in the emitted metric stream
+- `aggregation_strategy`: how collapsed datapoints are merged, using `sum`, `avg`, `min`, or `max`
+
+Defaults:
+
+- sum metrics use `sum`; gauge metrics use `avg`
+- `required` attributes are always kept
+- `recommended` and `conditionally_required` attributes are kept by default, but users can remove them
+- `opt_in` attributes are omitted by default, so that dimension is aggregated unless the user adds it
+
+Example user configuration:
+
+```yaml
+receivers:
+  myreceiver:
+    metrics:
+      http.server.request.count:
+        enabled: true
+        aggregation_strategy: sum
+        attributes: [transport]
+```
+
+In this example, datapoints that only differ by `status_code` are aggregated together, while
+`transport` remains part of the output identity.
+
 ### Feature Gates Documentation
 
 The metadata generator supports automatic documentation generation for feature gates used by components. Feature gates are documented by adding a `feature_gates` section to your `metadata.yaml`:

cmd/mdatagen/metadata-schema.yaml

@@ -19,6 +19,11 @@ scope_name: string
 # Optional: The name of the package that mdatagen generates. If not set, the name "metadata" will be used.
 generated_package_name: string
 
+# Optional: Enables per-metric reaggregation config generation for metrics with attributes.
+# When enabled, generated metrics config includes `aggregation_strategy` and `attributes`
+# fields that let users reduce metric cardinality by choosing which dimensions are kept.
+reaggregation_enabled: bool
+
 # Required for components (Optional for subcomponents): A high-level view of the development status and use of this component
 status:
   # Required: The class of the component (For example receiver)