Metrics

Metrics are Arion's aggregate counters, gauges and histograms — connections, requests, response classes, upstream timings. Use them for dashboards and alerting; use access logs when you need individual requests.

Before you begin

Metrics are a build feature. Compile with --features metrics for collection and OpenTelemetry export, and --features metrics,prometheus to also serve a Prometheus scrape endpoint.

Enable it

The Prometheus endpoint rides on the admin interface; enabling admin is all it takes:

envoy_bootstrap:
  admin:
    address:
      socket_address: { address: 127.0.0.1, port_value: 9901 }

Metrics are then scrapeable at http://127.0.0.1:9901/stats/prometheus, with a plain-text view at /stats.

What you get

Families follow Envoy's naming, prefixed by their group and partitioned by attributes: listeners_* and http_* labelled by listener (connections, requests, response classes 1xx–5xx, bytes), tls_* (handshakes), tcp_* for the TCP proxy, cluster_* labelled by cluster (upstream connections, requests, retries, timeouts, upstream_rq_time), server_* (uptime, memory, concurrency), and filter_* for rate-limit filter verdicts. The complete table with types and attributes is in the metrics list.

Variations

Push over OpenTelemetry

Independently of Prometheus, Arion can push metrics to an OTLP gRPC collector using Envoy's OpenTelemetry stats sink. Both can run at once.

envoy_bootstrap:
  stats_flush_interval: 10s
  stats_sinks:
    - name: envoy.stat_sinks.metrics_service
      typed_config:
        "@type": type.googleapis.com/envoy.extensions.stat_sinks.open_telemetry.v3.SinkConfig
        prefix: arion
        grpc_service:
          google_grpc:
            target_uri: "http://127.0.0.1:4317"
            stat_prefix: arion

stats_flush_interval sets the export period and prefix is prepended to exported metric names.

Partition by user

The metrics top-level section can partition user-level metrics (invocations, throttles, latency, response classes, bytes and more) by a caller identity taken from a request header or from the TLS SNI:

metrics:
  user_key:
    source: !HeaderName x-user-id
    attribute_name: "user"

With source: Sni the SNI value is used instead. The key is extracted once per request and reused through the whole lifecycle.

Rename metrics

Any built-in metric can be renamed for your conventions — the key is the default name, the value the exported name:

metrics:
  rename:
    uptime: "server_uptime_seconds"
    downstream_cx_active: "active_connections"

The same section also supports custom_metrics, which turn request or response headers into counters, histograms or gauges at six lifecycle hooks.

Verify

curl -s http://127.0.0.1:9901/stats/prometheus | head

Expected output includes lines such as:

# TYPE listeners_downstream_cx_total counter
listeners_downstream_cx_total{listener="listener_http"} 3

Counters can be zeroed for testing with curl -X POST http://127.0.0.1:9901/reset_counters.

Limits

The only push sink is the OpenTelemetry one; other Envoy stats sinks are rejected at load.
The OTLP sink needs a google_grpc target with target_uri; delta reporting and tag-extraction options of the Envoy sink are not supported.
A binary built without metrics collects nothing and has no /stats endpoints; without prometheus, /stats/prometheus is absent.
Not every Envoy statistic exists — the metrics list is the authoritative inventory.

Reference and guides