This is documentation for the next version of Grafana Beyla documentation. For the latest stable release, go to the latest version.

Documentation Beyla Configure Metrics histograms

Configure Beyla Prometheus and OpenTelemetry metrics histograms

You can configure Beyla Prometheus and OpenTelemetry metrics histograms. You can also choose to use native histograms and exponential histograms.

Override histogram buckets

You can override histogram bucket boundaries for the OpenTelemetry and Prometheus metrics exporters with otel_metrics_export.buckets and prometheus_export.buckets.

YAML section: otel_metrics_export.buckets

For example:

YAML Copy

otel_metrics_export:
  buckets:
    duration_histogram: [0, 1, 2]

Set the bucket boundaries for metrics related to request duration. Specifically:

• http.server.request.duration (OTEL) / http_server_request_duration_seconds (Prometheus)
• http.client.request.duration (OTEL) / http_client_request_duration_seconds (Prometheus)
• rpc.server.call.duration (OTEL) / rpc_server_call_duration_seconds (Prometheus)
• rpc.client.call.duration (OTEL) / rpc_client_call_duration_seconds (Prometheus)

If you leave the value unset, Beyla uses the default bucket boundaries from the OpenTelemetry semantic conventions:

Copy

0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10

YAML section: prometheus_export.buckets

YAML Copy

prometheus_export:
  buckets:
    request_size_histogram: [0, 10, 20, 22]
    response_size_histogram: [0, 10, 20, 22]

Set the bucket boundaries for metrics related to request and response sizes:

• http.server.request.body.size (OTEL) / http_server_request_body_size_bytes (Prometheus)
• http.client.request.body.size (OTEL) / http_client_request_body_size_bytes (Prometheus)
• http.server.response.body.size (OTEL) / http_server_response_body_size_bytes (Prometheus)
• http.client.response.body.size (OTEL) / http_client_response_body_size_bytes (Prometheus)

If you leave the value unset, Beyla uses these default bucket boundaries:

Copy

0, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192

These default values are UNSTABLE and may change if Prometheus or OpenTelemetry semantic conventions recommend different bucket boundaries.

TCP round-trip time buckets

The stat_tcp_rtt_histogram property sets the explicit bucket boundaries for beyla.stat.tcp.rtt (beyla_stat_tcp_rtt_seconds in Prometheus). Values are durations expressed in seconds.

Set the property as otel_metrics_export.buckets.stat_tcp_rtt_histogram or prometheus_export.buckets.stat_tcp_rtt_histogram.

If you leave the value unset, Beyla uses these boundaries:

Copy

0.0005, 0.001, 0.002, 0.005, 0.010, 0.025, 0.050, 0.100, 0.250, 0.500, 1.0

For example, to set the boundaries for the OpenTelemetry exporter:

YAML Copy

otel_metrics_export:
  buckets:
    stat_tcp_rtt_histogram: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1]

Runtime garbage collection buckets

Configure JVM and V8 GC duration boundaries under otel_metrics_export.buckets or prometheus_export.buckets. Values are seconds.

For example:

YAML Copy

otel_metrics_export:
  buckets:
    jvm_gc_duration_histogram: [0.01, 0.1, 0.5, 1, 5]
    v8js_gc_duration_histogram: [0.005, 0.01, 0.05, 0.1, 0.5, 1]
prometheus_export:
  port: 9090
  buckets:
    jvm_gc_duration_histogram: [0.01, 0.1, 0.5, 1, 5]
    v8js_gc_duration_histogram: [0.005, 0.01, 0.05, 0.1, 0.5, 1]

The exporters use their own bucket configuration. These runtime histograms retain explicit boundaries when otel_metrics_export.histogram_aggregation selects exponential histograms.

Use native histograms and exponential histograms

Histogram resolution controls the balance between detail, memory use, and export payload size.

OpenTelemetry exponential histograms

Set otel_metrics_export.histogram_aggregation to base2_exponential_bucket_histogram, or set OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION to that value. Configure resolution under otel_metrics_export.exponential_histogram:

For example:

YAML Copy

otel_metrics_export:
  histogram_aggregation: base2_exponential_bucket_histogram
  exponential_histogram:
    max_scale: 12
    max_size: 80

These settings apply to histograms configured through OpenTelemetry views, including HTTP, RPC, database, messaging, GenAI, service graph, and TCP round-trip time histograms. Exponential aggregation replaces their explicit bucket boundaries. Runtime GC histograms retain their explicit boundaries.

Prometheus native histograms

Configure native histograms under prometheus_export.native_histogram. A compatible Prometheus server can scrape native histograms alongside classic histograms. Enable native histogram scraping with --enable-feature=native-histograms on Prometheus versions before 3.8.0, or scrape_native_histograms on Prometheus 3.8.0 or later. Refer to the Prometheus native histogram specification for server configuration.

For example:

YAML Copy

prometheus_export:
  port: 9090
  native_histogram:
    bucket_factor: 1.2
    max_bucket_number: 80
    min_reset_duration: 30m

These controls tune the native histograms created by the application and TCP statistics exporters. They leave the classic boundaries under prometheus_export.buckets unchanged.

Generative AI histogram buckets

Both exporters accept the following fields under their buckets section:

For example:

YAML Copy

otel_metrics_export:
  buckets:
    gen_ai_client_operation_duration_histogram: [0.1, 0.5, 1, 5, 10, 30, 60]
    gen_ai_client_token_usage_histogram: [16, 64, 256, 1024, 4096, 16384]
prometheus_export:
  port: 9090
  buckets:
    gen_ai_client_operation_duration_histogram: [0.1, 0.5, 1, 5, 10, 30, 60]
    gen_ai_client_token_usage_histogram: [16, 64, 256, 1024, 4096, 16384]

These metrics require the relevant GenAI instrumentation. OpenTelemetry exponential aggregation replaces the explicit GenAI boundaries.