Allow custom attributes to be added to standard metrics like OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS

[thiagohora]

Is your feature request related to a problem? Please describe.

I need all server-side HTTP metrics (for example, http.server.request.duration) to include certain request headers (like X-Tenant-Id or X-Env) as metric attributes.
Currently, these headers can only be captured as span attributes using OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS, but they are not propagated to the corresponding metrics produced by the agent.
Without these attributes, it’s impossible to filter or group request metrics per tenant, environment, or user domain.

---

Describe the solution you'd like

Introduce an environment variable or configuration option similar to
OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS,
for example:

OTEL_INSTRUMENTATION_HTTP_SERVER_METRICS_CAPTURE_HEADERS=x-tenant-id,x-skd-version

This setting would copy the captured request header values into the metric attributes of the automatically generated HTTP server metrics (e.g., http.server.request.duration, http.server.active_requests, etc.).
The implementation should sanitize and lower-case header names and handle cardinality limits safely.

---

Describe alternatives you've considered

• Deriving metrics from spans using the Collector spanmetrics connector.
  This works but adds deployment complexity and duplicate metric names.
• Emitting a custom http.server.request.duration metric in application code, which duplicates logic already handled by the agent.

---

Additional context

Having these headers as attributes on built-in HTTP metrics would allow consistent per-tenant, per-version, or per-xxx filtering in metric backends like Prometheus, Grafana Cloud, or Datadog, without extra Collector configuration.

---

Tip[/+]

[+]_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[trask]

hi @thiagohora!

I believe the headers configured with OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS are already passed to the metrics, but they're filtered out by default attribute advice. You can use metric views to override this filtering and include the custom headers.

Example generated by Copilot, please forgive any mistakes

Step 1: Configure header capture (as you're already doing):

export OTEL_INSTRUMENTATION_HTTP_SERVER_CAPTURE_REQUEST_HEADERS=x-tenant-id,x-env

Step 2: Create a metric view file (metric-views.yaml):

- selector:
    instrument_name: http.server.request.duration
  view:
    attribute_keys:
      - http.route
      - http.request.method
      - http.response.status_code
      - error.type
      - network.protocol.name
      - network.protocol.version
      - url.scheme
      - http.request.header.x-tenant-id
      - http.request.header.x-env

Step 3: Configure the agent to use declarative configuration:

export OTEL_EXPERIMENTAL_CONFIG_FILE=/path/to/otel-config.yaml

And include the metric view in your otel-config.yaml:

file_format: "0.3"

meter_provider:
  views:
    - selector:
        instrument_name: http.server.request.duration
      view:
        attribute_keys:
          - http.route
          - http.request.method
          - http.response.status_code
          - error.type
          - network.protocol.name
          - network.protocol.version
          - url.scheme
          - http.request.header.x-tenant-id
          - http.request.header.x-env

Alternatively, you can use the legacy environment variable:

export OTEL_EXPERIMENTAL_METRICS_VIEW_CONFIG=/path/to/metric-views.yaml

Note: Header names are lowercased and prefixed with http.request.header.. For example, X-Tenant-Id becomes http.request.header.x-tenant-id.

References

• Declarative Configuration
• Metric Views Configuration

[thiagohora]

Hi @trask ,

I'm trying with this, but it doesn't work.

otel-config.xml

file_format: "1.0"

meter_provider:
  views:
    - selector:
        instrument_name: http.server.request.duration
      stream:
        attribute_keys:
          included:
            - http.route
            - http.request.method
            - http.response.status_code
            - error.type
            - network.protocol.name
            - network.protocol.version
            - url.scheme
            - http.request.header.x-tenant-id
            - http.request.header.x-env

otel-collector-config.xml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  prometheusremotewrite:
    endpoint: "http://prometheus-native-hist:9090/api/v1/write"
    resource_to_telemetry_conversion:
      enabled: true

  debug:
    verbosity: detailed

processors:
  # Drop-in replacement for "views": trim metric attributes on the collector side
  transform/views_like:
    metric_statements:
      - context: datapoint
        statements:
          # Keep only these attributes for the target metric; drop the rest
          - keep_keys(attributes, [
              "http.route",
              "http.request.method",
              "http.response.status_code",
              "error.type",
              "network.protocol.name",
              "network.protocol.version",
              "url.scheme",
              "http.request.header.x-tenant-id",
              "http.request.header.x-env"
            ]) where metric.name == "http.server.request.duration"
  batch:
    send_batch_size: 100
    timeout: 10s

  memory_limiter:
    check_interval: 1s
    limit_mib: 512

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]

    metrics:
      receivers: [otlp]
      processors: [memory_limiter, transform/views_like, batch]
      exporters: [prometheusremotewrite, debug]

    logs:
      receivers: [otlp]
      processors: [memory_limiter, batch]
      exporters: [debug]

[trask]

ah, here's a working example: https://github.com/trask/issue-15106

I forgot about the whole "migrate to declarative config" part

[thiagohora]

Hi @trask,

Can I do something like this? I mean via declarative config.

       View workspaceView = View.builder()
                .setDescription("Metric view that includes workspace context attributes")
                .setAttributeFilter(value -> true)
                .build(); 

       Arrays.stream(InstrumentType.values()).forEach(instrumentType -> {
            builder.registerView(
                    InstrumentSelector.builder()
                            .setType(instrumentType)
                            .build(),
                    workspaceView
            );
        });
      
    return builder;

I want to apply this filter to keep all attributes (the two I added plus the default ones), not just for one particular metric like http.server.request.duration but for all metrics.