waitEventProfile

read-onlyany connectionsweeps replication groupsweeps group

Synopsis

waitEventProfile([group_by], [include_idle], [limit], [query_id])

Description

Return what this instance has spent its time waiting on, from pg_wait_sampling's accumulated profile: one entry per wait event (or per query_id and wait event with group_by="query"), with its sample count, its percent of the samples counted (the idle ones below are not), and estimated_ms. currentActivity is a single sample of what is waiting now; this is the answer to what the server has been waiting on -- IO/DataFileRead dominating and LWLock/WALWrite dominating are opposite stories that look identical in a throughput figure. samples are collector ticks, every profile_period_ms per backend, so estimated_ms is backend-time summed over all backends rather than wall-clock time, and the counts accumulate from the last reset or server start: this server never resets them, so a window is the difference between two readings.

Activity samples -- background processes idling in their main loops -- are excluded unless include_idle is true and counted in excluded_idle_samples. Client/ClientRead is kept, and it includes idle connections waiting for their next statement, so on a pooled server it measures connections times time as much as anything. An entry whose event_type and event are null is a backend sampled while not waiting at all -- running, which usually means on CPU -- and on a busy server it is often the largest entry. query_id is null for samples with no statement, and every query_id is 0 (so null) when pg_wait_sampling.profile_queries is off.

Requires pg_wait_sampling in shared_preload_libraries, and says so as an error when it is installed without it; preloaded is null only when neither shared_preload_libraries nor the extension's own settings could tell.

Parameters

group_by optionalstring: "event" (default) sums every backend and statement per wait event; "query" keeps query_id, to join to statementStats
include_idle optionalboolean: keep the Activity samples of background processes idling in their main loops. Defaults to false
limit optionalinteger: how many entries to return, most-sampled first. Defaults to 30, at most 500
query_id optionalstring: only samples taken while this statement ran, as a decimal string from statementStats

Also accepts connection, replication_group, group, role, described once under arguments every tool takes.

Output

Accumulated wait-event samples from pg_wait_sampling. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
events	array \| null
group_by	string \| null
settings	object \| null
total_samples	number \| null

Scope

This reading is instance-wide -- every database on the same postmaster returns it identically, so asking each of them in turn repeats one answer. The counters here are each server's own, so members of a replication group legitimately disagree and the answer is their sum, not the primary's copy.

Example mocked data

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "waitEventProfile",
    "arguments": {
      "limit": 5
    }
  }
}

Result

{
  "group_by": "event",
  "total_samples": 184220,
  "excluded_idle_samples": 2210934,
  "events": [
    {
      "event_type": "IO",
      "event": "DataFileRead",
      "samples": 71802,
      "percent": 38.98,
      "estimated_ms": 718020
    },
    {
      "event_type": null,
      "event": null,
      "samples": 52310,
      "percent": 28.4,
      "estimated_ms": 523100
    },
    {
      "event_type": "LWLock",
      "event": "WALWrite",
      "samples": 30114,
      "percent": 16.35,
      "estimated_ms": 301140
    },
    {
      "event_type": "Client",
      "event": "ClientRead",
      "samples": 18402,
      "percent": 9.99,
      "estimated_ms": 184020
    },
    {
      "event_type": "Lock",
      "event": "transactionid",
      "samples": 6120,
      "percent": 3.32,
      "estimated_ms": 61200
    }
  ],
  "settings": {
    "profile_period_ms": 10,
    "profile_queries": "top",
    "profile_pid": "on"
  },
  "preloaded": true,
  "extension_version": "1.1"
}

Invented values on a fictional shop database, shaped by and checked against this tool's output schema. Real output is returned as structuredContent to clients that negotiate MCP 2025-06-18 or later.