From f78f8f4bc05851659418b0dd0a7e2095bbabcba2 Mon Sep 17 00:00:00 2001 From: Bryan Green Date: Fri, 30 Oct 2026 16:23:17 -0500 Subject: [PATCH v1 3/3] Document the ETW probe backend Add a section describing the ETW backend for the static probes on Windows: the -Detw build option, the "PostgreSQL.Server" provider and its name-derived GUID, the keyword and level scheme, and how to capture events with the standard Windows tools. Also update "Defining New Probes" for probes_etw.txt, and note that with ETW the probe arguments are evaluated only when the event is enabled. --- doc/src/sgml/installation.sgml | 22 ++++ doc/src/sgml/monitoring.sgml | 234 +++++++++++++++++++++++++++++++++ 2 files changed, 256 insertions(+) diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index e4159522e18..13308af238a 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -3229,6 +3229,28 @@ ninja install + + + + + + ETW + + On Windows, enabling this compiles + PostgreSQL with support for emitting its + probes as Event Tracing for Windows (ETW) events. It requires + <TraceLoggingProvider.h> from a recent + Windows SDK, so it is available when + building with Visual Studio but not with + MinGW; with auto, builds + that lack the header keep the empty probe macros. This option has no + effect on other platforms, and is mutually exclusive with + . See for + more information. + + + + diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 31ff4a9d99f..86a1218209d 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -8537,6 +8537,14 @@ FROM pg_stat_get_backend_idset() AS backendid; the macros in src/include/utils/probes.h. + + On Windows, where these probes cannot be traced + with DTrace, the same probe points can instead be emitted as + Event + Tracing for Windows (ETW) events and consumed with the standard + Windows performance tools. See . + + Compiling for Dynamic Tracing @@ -8547,6 +8555,23 @@ FROM pg_stat_get_backend_idset() AS backendid; specify to configure. See for further information. + + + On Windows, the Meson + option (see ) + makes the probes available as ETW events instead (see + ). It defaults to + auto, so it is enabled whenever the build environment + supports it. This requires the + Windows SDK header + <TraceLoggingProvider.h>, in a version recent + enough to provide the TraceLogging macros the probes use, so it is + available when building with Visual Studio; no + additional libraries are needed. MinGW does not provide + this header, so ETW support is not available in + MinGW builds, which keep the empty probe + macros. ETW and DTrace support are mutually exclusive. + @@ -9128,6 +9153,17 @@ Total time (ns) 2312105013 + + + Add a matching line for each new probe to + src/backend/utils/probes_etw.txt, giving its ETW + keyword and level and the type and name of each argument (see + ). The build checks that the two + files agree on every platform, not only on + Windows. + + + Include pg_trace.h if it is not already present in the @@ -9173,6 +9209,16 @@ probe transaction__start(LocalTransactionId); + + + Add the probe to src/backend/utils/probes_etw.txt, + with its ETW keyword and level and the type and name of its argument: + +transaction__start TRANSACTION INFO LocalTransactionId lxid + + + + At compile time, transaction__start is converted to a macro @@ -9239,8 +9285,196 @@ if (TRACE_POSTGRESQL_TRANSACTION_START_ENABLED()) Each trace macro has a corresponding ENABLED macro. + + + + With ETW (see ), the arguments are + evaluated only when a trace session has enabled the event, so the + arguments to a trace macro must not have side effects. + + + + + + + + + + Event Tracing for Windows (ETW) + + + ETW + + + Event Tracing for Windows + + + + When PostgreSQL is built on + Windows with ETW support (see + ), the same probe points listed in + are emitted as + TraceLogging + events through a single ETW provider. They can be captured and analyzed + with the standard Windows tools, including + Windows Performance Recorder + (wpr), + Windows Performance Analyzer + (WPA), + PerfView, logman, + tracerpt, and xperf. No manifest + registration or additional consumer binary is required: the events are + self-describing, so consumers display each field by name. + + + + The provider is identified as follows. The name and + GUID are a stable contract that capture profiles depend + on, and never change: + + + Provider name: PostgreSQL.Server + + + Provider GUID: + ea7811de-e757-5488-7ad6-2b057cced37d + + The GUID is derived from the provider name using the + standard ETW name hash, so tools that accept a provider name in place of a + GUID (for example + *PostgreSQL.Server in + PerfView) compute the same value. + + + + Every event carries the same name as the corresponding DTrace probe (with + underscores in place of hyphens, for example + transaction_start), and its arguments appear as named + fields using the parameter descriptions from + (for example + lxid, blocknum, or + tranche). + + + + String fields, such as query text and lightweight lock tranche names, are + marked as UTF-8 in the event, but their contents are passed through in the + server encoding without conversion, so non-ASCII characters are displayed + correctly only when the server encoding is UTF8. To + keep events within the size limit that ETW imposes, string fields longer + than 32kB are truncated. ETW also discards any event larger than the trace + session's buffer size, so sessions that record query text should use + buffers of at least 64kB (for example -bs 64 with + logman). + + + + + The query probes include the full text of each statement. Any user who + can start a trace session on the server machine, which includes members + of the Performance Log Users group, can record these + events, so treat the trace files accordingly. + + + + + Each event is tagged with one keyword and a + level, so a consumer can enable just the subsystems + and verbosity it needs by filtering on the tuple + (provider, level, keyword). The keywords are a 64-bit + bitmask; the bits currently in use are shown in + . Bits 48 to 63 are reserved by + Windows, and the other unused bits are reserved + for future keywords. + + + + ETW Probe Keywords + + + + + + + Keyword + Bit + Probes + + + + + PG_KW_QUERY + 0x01 + Query parse, rewrite, plan, execute, and statement status + + + PG_KW_TRANSACTION + 0x02 + Transaction start, commit, and abort + + + PG_KW_LOCK + 0x04 + Lightweight locks, heavyweight locks, and deadlock detection + + + PG_KW_BUFFER + 0x08 + Buffer reads, flushes, extends, and checkpoint buffer writing + + + PG_KW_STORAGE + 0x10 + Storage manager (md) block reads and writes + + + PG_KW_WAL + 0x20 + WAL insert, segment switch, and buffer write + + + PG_KW_CHECKPOINT + 0x40 + Checkpoint progress, including the CLOG, SUBTRANS, MultiXact, and + two-phase phases + + + PG_KW_SORT + 0x80 + Sort start and completion + + + +
+ + Levels follow the Windows convention, where a + higher number is more verbose. Low-volume, high-interest probes + (transaction, query, checkpoint, heavyweight lock wait, deadlock, and WAL + segment switch) are emitted at WINEVENT_LEVEL_INFO (4), + so they are captured by a default session. High-volume probes (lightweight locks, buffer and + storage I/O, sort, and WAL record insertion) are emitted at + WINEVENT_LEVEL_VERBOSE (5), so they are excluded unless a + session explicitly asks for verbose events. + + + + The following example uses logman to capture all + PostgreSQL events (every keyword, up to the + verbose level) into an event trace log, then decodes it with + tracerpt: + +logman create trace pg_etw -p "{ea7811de-e757-5488-7ad6-2b057cced37d}" 0xffffffffffffffff 0x5 -bs 64 -o pg_etw.etl -ets +... run the workload ... +logman stop pg_etw -ets +tracerpt pg_etw.etl -o pg_etw.xml -of XML + + To capture a single subsystem, supply just its keyword bit in place of + 0xffffffffffffffff; for example, 0x2 + captures only transaction events. Because every server process registers + the provider at startup, events from all of them appear in the same + session. -- 2.51.0