Telemetry

PgCache collects anonymous telemetry to help us understand how the software is being used. Telemetry is enabled by default and can be disabled at any time.

What We Collect

A small JSON payload is sent once at startup and then every 24 hours:

{
  "id": "a1b2c3d4-random-uuid",
  "version": "0.4.8",
  "pg_version": "16.2",
  "os": "linux",
  "arch": "x86_64",
  "deployment": "docker",
  "event": "heartbeat",
  "metrics": {
    "cached_queries": 12,
    "cache_hit_rate_pct": 72,
    "queries_served_24h": 15000,
    "uptime_hours": 168
  }
}

Field	Description
`id`	Random UUID generated at startup. Not persisted — each restart generates a new ID.
`version`	PgCache version number
`pg_version`	PostgreSQL version of the origin database
`os` / `arch`	Operating system and CPU architecture
`deployment`	`docker` or `bare-metal`
`event`	`startup` (first ping) or `heartbeat` (every 24h)
`cached_queries`	Number of queries currently cached
`cache_hit_rate_pct`	Cache hit rate as a percentage (0-100)
`queries_served_24h`	Approximate queries served since last heartbeat
`uptime_hours`	Hours since PgCache started

What We Never Collect

SQL query text or query plans
Table names, column names, or schema information
Database credentials or connection strings
IP addresses (not stored by the telemetry endpoint)
Hostnames or environment variables
Row data or query results

Why We Collect It

Understand how many active PgCache instances exist
Know which PostgreSQL versions to prioritize for compatibility
See whether users are getting value from the cache (hit rates)
Guide development priorities based on real usage patterns

How to Disable

Any of the following methods will disable telemetry:

Environment variable (recommended for Docker):

PGCACHE_TELEMETRY=off

TOML configuration file:

telemetry = false

CLI argument:

pgcache --telemetry_off ...

When telemetry is disabled, no network requests are made and no data is sent.

Technical Details

Telemetry runs on a dedicated background thread and never affects proxy performance
All network requests use a 10-second timeout and failures are silently ignored
The instance ID is generated in memory at startup and not persisted to disk
Data is sent via HTTPS POST to telemetry.pgcache.com