Telemetry reference for the troubleshooting guides

The troubleshooting guides don't collect telemetry themselves. They read telemetry you enable separately, then join it. If you know what sits behind each source, you can more easily predict which charts go blank when you don't enable something, and you can better judge how much to trust a number.

Diagnostic log categories

Configure these categories in Diagnostic settings on your server and route them to a Log Analytics workspace. The portal shows these names.

Category What it captures Underlying source Notes
PostgreSQL Server Logs Errors, warnings, connection and disconnection messages, lock waits, autovacuum completion records, checkpoint records. The PostgreSQL server log Contents depend entirely on your log_* parameters. If log_lock_waits is off, no lock data reaches the guides regardless of this category being enabled.
Sessions data Point-in-time snapshots of every backend: PID, state, wait event, and the timestamps used to derive connection, transaction, and query duration. pg_stat_activity Sampled, not continuous. Activity shorter than the sampling interval can be invisible. Requires metrics.collector_database_activity.
Query Store Runtime Per-query statistics aggregated into time buckets: calls, mean and total duration, rows, shared blocks hit and read, temporary blocks, and I/O timings. Query Store Keyed by query ID, never by text. Gated by pg_qs.query_capture_mode.
Query Store Wait Statistics Sampled wait events attributed back to the query ID that was waiting. pgms_wait_sampling This data makes it possible to answer "which query caused this wait". Gated by pgms_wait_sampling.query_capture_mode.
Autovacuum and schema statistics Per-table live and dead tuple counts, insert/update/delete activity, and last vacuum and analyze timestamps. pg_stat_user_tables Every bloat calculation in the guides derives from this.
Remaining transactions Per-database transaction ID age and how many transactions remain before wraparound protection engages. Database XID age Drives the wraparound warnings in both autovacuum guides.
Query Store SQL text The SQL text itself, so query IDs can be resolved without connecting to the database. Query Store Off by default for privacy. Gated by pg_qs.emit_query_text.
AllMetrics Platform metrics: CPU, memory, storage, IOPS, and the enhanced metrics. Azure Monitor Not PostgreSQL data. This data is the platform's own view of the host.

Server parameters the guides depend on

Some tabs need a parameter set before they have anything to show, independent of diagnostic settings.

Parameter Needed by Effect if unset Restart
pg_qs.query_capture_mode Every Queries tab No query attribution anywhere. Set to TOP or ALL. No
log_line_prefix CPU Queries, native logging view only Log-based query charts stay empty. Not needed when you use Query Store, which is the primary source on both primaries and replicas. Must match the expected format exactly. No
log_min_duration_statement CPU Queries, native logging view only No statement duration data from logs. Not needed when you use Query Store. Don't use 0. No
pgms_wait_sampling.query_capture_mode Waits tabs Wait events aren't sampled, so no wait analysis. Set to ALL. No
metrics.collector_database_activity Sessions, Workload, enhanced metrics No session snapshots and no per-database activity. No
track_io_timing IOPS Queries tab blk_read_time and blk_write_time stay zero, so queries can't be ranked by I/O. No
log_autovacuum_min_duration Autovacuum per table No per-table autovacuum records. Must be non-negative. No
log_lock_waits CPU Locking and blocking Lock waits are never logged. Logs a message when a wait exceeds deadlock_timeout. No
pg_qs.emit_query_text Resolving query text from telemetry instead of the database Query text can't be read from Log Analytics. Only needed for the fallback path, since Query Store resolves text directly on both primaries and replicas. No
pgbouncer.enabled, metrics.pgbouncer_diagnostics PgBouncer metrics No pooler visibility. Not available on Burstable. No

How retention differs by source

This difference can cause confusion when you look for the SQL text behind a query ID you saw yesterday.

  • Telemetry in Log Analytics is retained per your workspace retention settings, typically much longer.
  • Query Store data inside the database is retained per pg_qs.retention_period_in_days.

The consequence: the guides can show you a query ID whose text is already gone from azure_sys. When historical text matters, enable pg_qs.emit_query_text and route the query text category to Log Analytics so the text is retained alongside the statistics.

Read the numbers accurately

Characteristic Why it matters
Session and wait data are sampled A query that runs for 200 ms between samples leaves no trace. Absence of evidence in a Sessions tab isn't evidence of absence.
Query Store data is bucketed Statistics are aggregated into time buckets. A mean within a bucket hides variance, so check min and max before concluding a query is consistently fast.
Autovacuum guides filter Only tables above a live and dead tuple threshold appear, so counts don't reconcile with a direct pg_stat_user_tables query.
Autovacuum guides cap databases analyzed Servers past the cap have databases silently excluded, in creation (OID) order. The guide warns when this happens.
Data usage can exceed physical memory A page pinned repeatedly during execution is counted each time, so a query's reported data usage can legitimately exceed shared_buffers or total RAM.
Parameter values shown are server-level Per-table storage parameters, ALTER ROLE ... SET, and per-session SET aren't reflected. The guide can show a healthy default while a specific table or role runs something else entirely.

Related content

  • Last updated on