Metrics

Octopus exposes gateway metrics in Prometheus text format. The endpoint is served directly on the gateway listen port, so a Prometheus scrape, a ServiceMonitor, or a prometheus.io/scrape pod annotation can reach it without a sidecar or a second port.

The endpoint01

The metrics handler answers on two fixed paths on the gateway listener:

curl http://localhost:8080/metrics
# alias:
curl http://localhost:8080/__metrics

The response is served with Content-Type: text/plain; version=0.0.4 — the Prometheus exposition format.

Warning

The path is fixed to /metrics (and its /__metrics alias). The observability.metrics.endpoint field is part of the config schema but does not currently re-route the metrics handler, so scrape /metrics on the listen port. observability.metrics.enabled does gate the endpoint: when set to false, /metrics returns 404.

Metrics emitted02

The Prometheus exporter writes the following series. These are the names and types declared in the exporter's header and emitted in its body.

Metric	Type	Labels	Meaning
`octopus_requests_total`	counter	none	Total HTTP requests handled by the gateway.
`octopus_active_connections`	gauge	none	Current number of active connections.
`octopus_requests_duration_seconds`	histogram	none	Request duration. Emitted as `_sum`, `_count`, and `_bucket{le=...}` series.

A typical scrape looks like:

# HELP octopus_requests_total Total number of HTTP requests
# TYPE octopus_requests_total counter
octopus_requests_total {} 1024
# HELP octopus_active_connections Current number of active connections
# TYPE octopus_active_connections gauge
octopus_active_connections {} 7
# HELP octopus_requests_duration_seconds HTTP request duration in seconds
# TYPE octopus_requests_duration_seconds histogram
octopus_requests_duration_seconds_sum {} 12.288000
octopus_requests_duration_seconds_count {} 1024
octopus_requests_duration_seconds_bucket{le="0.005"} 0
octopus_requests_duration_seconds_bucket{le="0.01"} 1024
...
octopus_requests_duration_seconds_bucket{le="+Inf"} 1024

Note

Histogram fidelity. The duration histogram is derived from the running average latency rather than from per-request bucket counts. The buckets use the standard Prometheus boundaries (0.005 … 10.0 seconds), but the bucket distribution is an approximation, not an exact per-request tally. Use it for trends, not for precise percentile alerting.

Per-route metrics

The exporter declares HELP/TYPE headers for per-route series (octopus_route_requests_total, octopus_route_errors_total, octopus_route_latency_seconds), but the current exporter does not emit the per-route data lines — it writes only a comment with the route count. Rich per-route data (request count, error count, p50/p95/p99 latency, error rate) is collected internally and is available through the Admin API (for example GET /admin/api/routes and GET /admin/api/analytics), not yet through /metrics.

Fallback output

If the gateway is running without a metrics collector wired in, the endpoint falls back to a two-metric body: octopus_requests_total (from a request counter) and octopus_routes_total (the number of configured routes). In a normal octopus serve deployment the full collector is wired, so you will see the table above.

Scraping with Prometheus03

Point Prometheus at the gateway

# prometheus.yml
scrape_configs:
  - job_name: octopus-gateway
    metrics_path: /metrics
    static_configs:
      - targets: ['octopus-gateway:8080']

Verify the scrape

curl -s http://octopus-gateway:8080/metrics | grep octopus_requests_total

Kubernetes ServiceMonitor04

In Kubernetes the metrics endpoint sits on the same container port as gateway traffic. The Helm chart documents how to expose it to the Prometheus Operator via a ServiceMonitor, and how to set scrape annotations. See Kubernetes → Helm chart for the chart values that control metrics scraping.