statementKernelStats

read-onlyany connectionsweeps replication groupsweeps group

Synopsis

statementKernelStats([limit], [order_by], [query_id])

Description

Return what the operating system measured each tracked statement costing, from pg_stat_kcache: CPU time split into user and system, bytes actually read from and written to storage, page faults, and context switches, separately for planning and execution, per query_id. What the counters mean depends on the server's platform, named in 'platform': cpu_time_s (user + system) is the kernel's own total, checked on Linux and FreeBSD; on Linux the user/system split and the byte counts are as measured, and elsewhere those four are null with the reason under 'unavailable' -- FreeBSD splits CPU time by sampling, so a short statement reads as all user time, and does not charge buffered writes to the process at all.

PostgreSQL's own counters cannot see this: a shared_blks_read in statementStats is a request to the kernel, answered from its page cache or from the device, and only exec.reads_bytes says which -- compare it with shared_blks_read times block_size, both returned here. A high nivcsws (involuntary context switches) is CPU contention; majflts is memory pressure reaching disk. Counters are cumulative from stats_since or the last reset. query_id joins to statementStats and explainQuery; for a role without pg_read_all_stats, pg_stat_statements hides the queryid of other roles' statements, so their calls, total_exec_ms and shared_blks_read are null while the kernel counters stay complete.

Requires pg_stat_kcache in shared_preload_libraries after pg_stat_statements, at version 2.2 or later.

Parameters

limit optionalinteger: how many statements to return. Defaults to 20, at most 500
order_by optionalstring: ranking: exec_cpu_time (default, user plus system), plan_cpu_time, exec_reads, exec_writes, exec_majflts, or exec_nivcsws
query_id optionalstring: only this statement, as a decimal string from statementStats. One entry per user, database and nesting level, so it can match more than one row

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

Output

Per-statement CPU and storage I/O from pg_stat_kcache. An absent extension or a missing grant is reported as {error, hint} instead.

Field	Type
block_size	integer \| null
order_by	string \| null
platform	string \| null
statements	array \| null
unavailable	object \| 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": "statementKernelStats",
    "arguments": {
      "limit": 1,
      "order_by": "exec_reads"
    }
  }
}

Result

{
  "statements": [
    {
      "query_id": "3301928477102934411",
      "top": true,
      "user": "app_rw",
      "database": "shop",
      "calls": 4410233,
      "total_exec_ms": 3120982.7,
      "shared_blks_read": 440112,
      "exec": {
        "user_time_s": 1840.2,
        "system_time_s": 402.7,
        "reads_bytes": 412090368,
        "writes_bytes": 0,
        "minflts": 1220931,
        "majflts": 12,
        "nvcsws": 901223,
        "nivcsws": 44102
      },
      "plan": {
        "user_time_s": 88.1,
        "system_time_s": 4.2,
        "reads_bytes": 0,
        "writes_bytes": 0,
        "minflts": 20331,
        "majflts": 0,
        "nvcsws": 0,
        "nivcsws": 310
      },
      "stats_since": "2026-08-01T00:00:00Z"
    }
  ],
  "order_by": "exec_reads",
  "block_size": 8192,
  "preloaded": true,
  "extension_version": "2.3.2"
}

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.