---
title: "Metrics"
url: "/docs/observe/metrics/"
kind: "feature"
summary: "Envoy-style statistics for listeners, clusters and HTTP traffic, scraped by Prometheus or pushed over OpenTelemetry."
---

> Arion site index: [/llms.txt](/llms.txt)

# Metrics

Envoy-style statistics for listeners, clusters and HTTP traffic, scraped by Prometheus or pushed over OpenTelemetry.

Metrics are Arion's aggregate counters, gauges and histograms — connections, requests, response classes, upstream timings. Use them for dashboards and alerting; use [access logs](@/docs/observe/access-logs.md) 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](@/docs/observe/admin-interface.md); enabling `admin` is all it takes:

```yaml,name=arion.yaml,arion=fragment
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](@/reference/observability/metrics-list.md).

## 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.

```yaml,name=arion.yaml,arion=fragment
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:

```yaml,name=arion.yaml,arion=fragment
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:

```yaml,name=arion.yaml,arion=fragment
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

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

Expected output includes lines such as:

```text
# 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](@/reference/observability/metrics-list.md) is the authoritative inventory.