Observability

Pingora ships three observability surfaces: structured logs, Prometheus metrics, and optional Sentry error reporting. There's also an optional tracing facility for the cache and proxy paths.

Logging

Pingora uses the log crate. Configure level and filter via RUST_LOG:

RUST_LOG=info ./pingora-server -c conf.yaml
RUST_LOG=pingora_proxy=debug,pingora_cache=trace ./pingora-server -c conf.yaml

Log destinations:

• STDERR by default
• A file when error_log: is set in YAML config
• When daemonized, STDERR is reattached to the error log file

The user guide page is docs/user_guide/error_log.md. Conventions:

• trace! — per-request internals (proxy phase entry, cache state transitions)
• debug! — normal flow markers
• info! — server lifecycle (bootstrap, graceful upgrade, shutdown phase changes)
• warn! — unexpected but recoverable
• error! — alert-worthy

The Apr 2026 commit 9a4eee3 ("Reinit sentry after daemonize") fixed a case where Sentry stopped reporting after daemonize swapped STDERR.

Prometheus metrics

The pingora-prometheus crate (split out of pingora-core in Apr 2026) provides a Service that exposes /metrics:

let prom_service = pingora_prometheus::prometheus_http_service("prometheus_metrics", "0.0.0.0:9090");
server.add_service(prom_service);

Custom metrics use the prometheus crate's macros against the global registry:

use prometheus::{register_counter, Counter};

static REQ_COUNT: Lazy<Counter> = Lazy::new(|| {
    register_counter!("requests_total", "Total request count").unwrap()
});

// inside ProxyHttp::request_filter
REQ_COUNT.inc();

docs/user_guide/prom.md walks through the recipe.

Built-in metrics

Pingora-core emits a handful of metrics covering connection counts, request bytes, response bytes, and upstream connection pool stats. The unexpected_data counter on the connection pool (Mar 2026) is exposed this way. The discovery and build durations on LoadBalancer::update (Mar 2026) are also exposed.

Sentry

Optional via the sentry cargo feature. Configure your DSN in the YAML config:

sentry:
  dsn: 'https://...@sentry.example.com/1'

Pingora ties into Sentry's panic and tracing integrations. Crashes, errors with ErrorSource::Internal, and panics are reported. The pingora-error::Error type is mapped to a Sentry event with the ErrorType::as_str label and the optional context.

Cache and proxy tracing (trace feature)

The trace cargo feature on pingora enables fine-grained tracing spans in the cache and proxy state machines. Implemented via pingora-cache/src/trace.rs (CacheTraceCTX) and matching hooks in pingora-proxy. Useful for debugging unexpected cache phase transitions; not free, so off by default.

Body-bytes tracking

The 0.7.0 release added body-bytes counters tracked across H1 and H2. These appear on the Session object and are surfaced through proxy metrics. Useful for distinguishing "request received headers but no body" from "client closed mid-body."

Where to look in code

Concern	File
Log call sites	Spread; grep for error!, warn! first
Prometheus service	pingora-prometheus/src/lib.rs
Sentry init	pingora-core/src/server/mod.rs (gated by sentry feature)
Cache tracing	pingora-cache/src/trace.rs
Body-bytes counters	pingora-core/src/protocols/http/ and pingora-proxy/src/proxy_*.rs

See also

• pingora-prometheus
• docs/user_guide/error_log.md
• docs/user_guide/prom.md
• docs/user_guide/panic.md