Monitoring

PgCache exposes Prometheus-compatible metrics via an HTTP endpoint, giving you visibility into query performance, cache behavior, CDC replication health, and connection state.

Enabling Metrics

The PgCache Docker image enables metrics on port 9090 by default. The listen address is set via the [metrics] section (or --metrics_socket) — see the Configuration reference. Publish the port to access them:

docker run -d -p 5432:5432 -p 9090:9090 pgcache/pgcache \
  --upstream postgres://user:password@db:5432/myapp

Security: the metrics endpoint is unauthenticated and exposes operational detail about your traffic. Restrict the metrics port to trusted/internal networks (a private subnet, security group, or firewall rule) — do not publish it to the public internet.

To use a different port, set the METRICS_PORT environment variable:

docker run -d -p 5432:5432 -p 8080:8080 \
  -e METRICS_PORT=8080 \
  -e UPSTREAM_URL=postgres://user:password@db:5432/myapp \
  pgcache/pgcache

When running pgcache outside Docker, add a [metrics] section to your TOML configuration:

[metrics]
socket = "0.0.0.0:9090"

Or use the CLI argument:

pgcache --config pgcache.toml --metrics_socket 0.0.0.0:9090

The HTTP server exposes several endpoints:

Histograms report p50, p95, and p99 quantiles.

Prometheus Scrape Configuration

scrape_configs:
  - job_name: pgcache
    static_configs:
      - targets: ['pgcache-host:9090']

Available Metrics

Query Counters

Track how queries flow through PgCache.

Latency Histograms

All latency metrics are in seconds and report p50, p95, and p99 quantiles.

Per-Stage Timing

Detailed breakdown of where time is spent within PgCache:

Connection Metrics

CDC / Replication Metrics

Monitor the health and throughput of the CDC replication stream.

CDC Connection Resilience

If the replication connection drops, pgcache automatically switches to forwarding all queries to the origin database while attempting to reconnect. The /readyz endpoint continues to return 200 during this period since the proxy is still serving queries (via origin). Once reconnected and the replication slot LSN is verified, cache dispatch resumes automatically.

Monitor pgcache.cdc.lag_bytes and pgcache.cdc.lag_seconds for replication health. A sudden spike in origin latency (pgcache.origin.latency_seconds) alongside cache hit ratio dropping to zero may indicate the CDC connection is temporarily down and queries are being forwarded.

Cache State Metrics

Disk Pressure

pgcache bounds its cache-volume footprint by measuring live filesystem usage (via statvfs) against an effective disk limit — either an explicit disk_limit or one auto-derived from the volume’s free space (see Configuration). When used space crosses the limit, an escalating reclaim ladder purges dead-generation rows, then sweeps dirty materialized views, then drops the fewest-query source table.

Memory Pressure

pgcache bounds its total memory footprint: as whole-system used memory (pgcache plus the cache Postgres it manages) approaches the registration budget (80% of detected RAM by default, or memory_limit — see Configuration), registration of new distinct queries is throttled and those queries are forwarded to origin instead of cached. Already-cached queries keep serving.

In-Process Result Memo

The in-process result memo is an in-memory tier that serves the hottest queries inline, skipping the cache-database round-trip. Its byte budget is set by memo_cache_size (default 64 MiB; 0 disables) — see the Configuration reference.

Serve Pool

The cache-database serve pool executes cache hits. These metrics surface pool saturation and response-integrity guards.

Materialized View Builds

Registration Gate

New-query registration is paced to the cache writer’s measured drain rate. These gauges expose the adaptive pacer’s internal state.

Writer Queue Depths

CDC Handler Metrics

Writer Instrumentation

Population Pipeline

Request Coalescing

When multiple concurrent requests arrive for a query that is currently populating, they share a single backend execution instead of each triggering a parallel population.

Protocol Metrics

Key PromQL Queries

Cache Hit Ratio

rate(pgcache_queries_cache_hit_total[5m])
/
(rate(pgcache_queries_cache_hit_total[5m]) + rate(pgcache_queries_cache_miss_total[5m]))

Query Latency (p95)

pgcache_query_latency_seconds{quantile="0.95"}

CDC Replication Lag

pgcache_cdc_lag_seconds

Cache Disk Utilization

pgcache_cache_disk_used_bytes / pgcache_cache_disk_limit_bytes

Status Endpoint

The GET /status endpoint returns a JSON object with real-time cache, CDC, and per-query information. Status data is gathered on demand from the cache writer via message passing (2-second timeout). If the cache thread is unresponsive, the endpoint returns 503.

Response Structure

{
  "fault_injection": false,
  "cache": {
    "size_bytes": 10485760,
    "size_limit_bytes": 1073741824,
    "generation": 42,
    "tables_tracked": 5,
    "policy": "clock",
    "queries_registered": 12,
    "uptime_ms": 3600000,
    "cache_hits": 15230,
    "cache_misses": 487
  },
  "cdc": {
    "tables": ["public.users", "public.orders"],
    "last_applied_lsn": 12345600
  },
  "queries": [
    {
      "fingerprint": 9876543210,
      "sql_preview": "SELECT * FROM users WHERE ...",
      "tables": ["public.users"],
      "state": "cached",
      "mv_state": "Ready",
      "cached_bytes": 2048,
      "max_limit": null,
      "pinned": false,
      "hit_count": 1523,
      "miss_count": 12,
      "idle_duration_ms": 245,
      "registered_duration_ms": 3580000,
      "cached_duration_ms": 3500000,
      "invalidation_count": 3,
      "readmission_count": 2,
      "eviction_count": 1,
      "subsumption_count": 45,
      "population_count": 4,
      "last_population_duration_ms": 120,
      "total_bytes_served": 4915200,
      "population_row_count": 500,
      "cache_hit_latency": {
        "count": 1523,
        "mean_us": 245.3,
        "p50_us": 210,
        "p95_us": 480,
        "p99_us": 920,
        "min_us": 85,
        "max_us": 3200
      }
    }
  ]
}

The root-level fault_injection flag reports whether the binary was built with the fault-injection feature (always false in release builds). The cache.size_bytes and cache.size_limit_bytes fields report cache-volume used bytes and the effective disk limit respectively (the same figures as the pgcache.cache.disk_used_bytes / pgcache.cache.disk_limit_bytes gauges).

Cache Status Fields

Per-Query Metrics

Each entry in the queries array includes operational metrics:

Health Checks

Use /healthz and /readyz as Kubernetes or load balancer health probes:

# Kubernetes example
livenessProbe:
  httpGet:
    path: /healthz
    port: 9090
readinessProbe:
  httpGet:
    path: /readyz
    port: 9090

Log Configuration

In addition to metrics, PgCache supports configurable logging via the log_level setting. This uses tracing’s EnvFilter syntax:

# Show info and above for all modules
log_level = "info"

# Debug logging for the cache subsystem, info for everything else
log_level = "pgcache_lib::cache=debug,info"

# Trace-level logging (very verbose)
log_level = "trace"

You can also set the RUST_LOG environment variable for one-off debugging sessions.