What are the troubleshooting guides in Azure Database for PostgreSQL flexible server?

Diagnosing a performance problem on PostgreSQL normally means correlating four things by hand: platform metrics, session snapshots, query statistics, and server logs. Each lives somewhere different, uses a different time axis, and needs its own query language.

The troubleshooting guides do that correlation for you. Each guide targets one class of problem, pulls the relevant telemetry into a single view, and lays it out as a diagnostic path: confirm the symptom, find the cause, apply a fix. They're built into your server in the Azure portal, so there's nothing to deploy and no cost beyond the Log Analytics ingestion you already pay for.

What a guide gives you that a metric chart doesn't

A CPU metric tells you CPU is at 95%. It can't tell you why. The guides are built to close that gap:

They attribute. Charts link a resource spike back to the specific query ID, process ID, wait event, or server parameter responsible.
They interpret. Each chart is paired with the thresholds that matter (what's healthy, what warrants investigation, what's critical), so you don't need to know from memory that 1 billion transaction IDs is the number to worry about.
They recommend. Tabs end with actions scoped to what that tab found, split into immediate mitigations and durable fixes.
They warn. Banners flag both missing telemetry and detected problems, so an empty chart doesn't get misread as a clean bill of health.

Choose a guide

Start from the symptom you can observe, usually from a metric alert or the server Overview page.

Your symptom	Open this guide	It answers
CPU is high or spiking	Troubleshoot high CPU utilization	Is this more workload, a few expensive queries, a connection storm, lock contention, or chatty logging?
Memory is high, or you see out-of-memory errors	Troubleshoot high memory utilization	Are memory parameters oversized, are queries touching too much data, or are there simply too many connections?
IOPS or disk bandwidth is saturated	Troubleshoot high IOPS utilization	Which queries drive the I/O, are checkpoints firing too often, and would more provisioned IOPS help?
Storage spikes, or temporary file usage is high	Troubleshoot high temporary file utilization	Which queries spill to disk, and is `work_mem` sized wrong?
Bloat is growing, or query plans are degrading	Monitor autovacuum	Is autovacuum keeping up, and how close am I to transaction ID wraparound?
Vacuum runs, but dead tuples aren't removed	Troubleshoot autovacuum blockers and wraparound risk	What's pinning the `xmin` horizon: a long transaction, an orphaned prepared transaction, or a replication slot?

Investigations rarely stay in one guide. The guides cross-link where causes commonly chain:

flowchart TD
    A[Performance problem] --> B{Primary symptom?}
    B -->|High CPU| CPU[High CPU]
    B -->|High memory or OOM| MEM[High memory]
    B -->|High IOPS| IOPS[High IOPS]
    B -->|Storage or temp file spike| TMP[High temporary files]
    B -->|Bloat or slow plans| AVM[Autovacuum monitoring]
    CPU -->|Bloat suspected| AVM
    IOPS -->|Bloat suspected| AVM
    TMP -->|Memory pressure suspected| MEM
    AVM -->|Vacuum runs, bloat persists| AVB[Autovacuum blockers]

If you can't tell which symptom is primary (CPU, memory, and IOPS often rise together), start with the resource that's closest to its limit, and treat the others as consequences until the data says otherwise.

Guide components at a glance

Every guide breaks into tabs. The order isn't cosmetic: it encodes the diagnostic path, moving from the metric that defines the symptom, out to the workload that might explain it, then down to the specific sessions, queries, waits, or settings responsible.

Guide	Tabs, in diagnostic order
Troubleshoot high CPU utilization	CPU � Workload � Transactions � Long running transactions � Queries � User connections � Locking and blocking � Waits � Logs � Insights
Troubleshoot high memory utilization	Memory � Workload � Sessions � Queries � User connections � Memory parameters
Troubleshoot high IOPS utilization	Overview � Workload � Sessions � Queries � Waits � Checkpoints � Storage
Troubleshoot high temporary file utilization	Storage � Temporary files � Workload � Queries
Monitor autovacuum	Bloat � Tuples � Vacuum and analyze � Autovacuum activity � Autovacuum per table � Enhanced metrics � Vacuum throttling overview � Insights � Configuration
Troubleshoot autovacuum blockers and wraparound risk	Emergency autovacuum and wraparound � Autovacuum blockers

Several building blocks repeat across guides, and mean the same thing everywhere:

Resource utilization: the metric that defines the problem. Use it to confirm the symptom and pin down the time window before drilling in.
Workload: read tuple activity versus write tuple activity. This is the fastest way to separate "the server is doing more legitimate work" from "the server is doing the same work less efficiently."
Sessions and Long running transactions: sampled pg_stat_activity snapshots that surface the process IDs holding resources, distinguishing connection age from transaction age.
Queries: top offenders from Query Store, ranked by whichever dimension matters for that guide, such as total duration, data touched, I/O time, or temporary bytes.
Waits: what execution is actually blocked on, attributed back to the queries doing the waiting.

What the guides need before they show anything

Guides render from telemetry you opt into. A guide with no data source enabled looks the same as a healthy server: empty. Enable the sources first.

All guides need server logs flowing to a Log Analytics workspace. Individual guides also need Query Store, enhanced metrics, or specific server parameters. For the per-guide matrix and enablement steps, see Use the troubleshooting guides. For what each source actually contains, see Telemetry reference for the troubleshooting guides.

Limitations

Minimum time window is one hour. Selecting a shorter range falls back to a one-hour capture ending at your chosen end time. The guides aren't built for second-by-second incident response.
Sampling means brief events can be missed. Session and wait data are sampled, not continuously recorded. A spike shorter than the sampling interval might leave no trace.
Autovacuum guides filter and cap. Only tables above a tuple threshold are analyzed, and only a bounded number of databases per server. Totals won't match a direct query against the database.
Query text and usernames are withheld by default for privacy. The portal shows numeric identifiers. See Retrieve the text of a query.
Query Store isn't recommended on the Burstable tier, where its overhead can itself degrade performance.
Read replicas are supported, but behave differently from a primary. Guides detect a replica and adjust. Write workload charts aren't available, and autovacuum statistics reflect the primary's activity, so run the autovacuum guides against the primary.

Last updated on 2026-09-29