How to monitor

All Neon services are designed to be observable from a typical cloud-native stack: structured logs, Prometheus metrics, and OpenTelemetry traces. This section enumerates what's emitted and where.

Pages

• Logging — log format, where logs go, useful queries.
• Metrics — Prometheus surfaces, key SLIs.
• Tracing — OTLP setup, span conventions.

At a glance

• Logs. JSON-formatted, written to stderr. Use LOGFMT=text for human-readable. The formatter is in libs/tracing-utils/.
• Metrics. Prometheus exposition over GET /metrics. The metrics client is libs/metrics/.
• Traces. OpenTelemetry. Set OTEL_EXPORTER_OTLP_ENDPOINT to enable. The crate is libs/tracing-utils/ plus tracing-opentelemetry.

The proxy binary is one exception: it has additional consumption-metrics emission (proxy/src/usage_metrics.rs) feeding billing pipelines. See Proxy.

Common SLOs to watch

For the pageserver:

• pageserver_smgr_query_seconds_bucket — GetPage@LSN latency.
• pageserver_layer_count — total layer files. Spikes signal stalled compaction.
• pageserver_remote_*_latency_seconds_bucket — remote storage I/O latency.
• pageserver_walredo_* — WAL-redo subprocess health.

For the safekeeper:

• safekeeper_flush_lsn per timeline — disk durability.
• safekeeper_commit_lsn per timeline — quorum-confirmed durability.
• safekeeper_active_segments — active timeline count.

For the proxy:

• proxy_connection_* — connection rate and outcome.
• proxy_io_* — proxied byte counts.
• proxy_compute_connection_seconds_bucket — time to acquire a compute connection.

For the storage controller:

• storcon_reconciles_total and _seconds — reconciler activity.
• storcon_pageservers_alive — fleet liveness.

Log conventions across services

• Every per-request log line includes tenant_id, timeline_id, and a request_id that's propagated from the caller. The pageserver also adds key and lsn for GetPage@LSN requests.
• Top-level errors are emitted with the error chain expanded (anyhow backtraces).
• Background tasks emit info on transitions ("compaction starting", "compaction complete in X").

When something is on fire

• The pageserver /debug_endpoints API dumps internal state for one tenant.
• pagectl (offline) can inspect on-disk layer files.
• storcon-cli can query the controller's view of the fleet.
• Setting RUST_LOG=debug on a single service for a short window often surfaces the problem when metrics don't.

For per-component troubleshooting see Debugging.