Age Owner Branch data TLA Line data Source code
1 : : /*-------------------------------------------------------------------------
2 : : *
3 : : * instrument_node.h
4 : : * Definitions for node-specific support for parallel query instrumentation
5 : : *
6 : : * These structs purposely contain no pointers because they are copied
7 : : * across processes during parallel query execution. Each worker copies its
8 : : * individual information into the container struct at executor shutdown time,
9 : : * to allow the leader to display the information in EXPLAIN ANALYZE.
10 : : *
11 : : * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
12 : : * Portions Copyright (c) 1994, Regents of the University of California
13 : : *
14 : : * src/include/executor/instrument_node.h
15 : : *
16 : : *-------------------------------------------------------------------------
17 : : */
18 : : #ifndef INSTRUMENT_NODE_H
19 : : #define INSTRUMENT_NODE_H
20 : :
21 : : /*
22 : : * Offset added to plan_node_id to create a second TOC key for per-worker scan
23 : : * instrumentation. Instrumentation and parallel-awareness are independent, so
24 : : * separate DSM chunks let each be allocated and initialized only when needed.
25 : : * In the future, if nodes need more DSM allocations, we would need a more
26 : : * robust system.
27 : : */
28 : : #define PARALLEL_KEY_SCAN_INSTRUMENT_OFFSET UINT64CONST(0xD000000000000000)
29 : :
30 : : /* ---------------------
31 : : * Instrumentation information for aggregate function execution
32 : : * ---------------------
33 : : */
34 : : typedef struct AggregateInstrumentation
35 : : {
36 : : Size hash_mem_peak; /* peak hash table memory usage */
37 : : uint64 hash_disk_used; /* kB of disk space used */
38 : : int hash_batches_used; /* batches used during entire execution */
39 : : } AggregateInstrumentation;
40 : :
41 : : /*
42 : : * Shared memory container for per-worker aggregate information
43 : : */
44 : : typedef struct SharedAggInfo
45 : : {
46 : : int num_workers;
47 : : AggregateInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
48 : : } SharedAggInfo;
49 : :
50 : :
51 : : /* ---------------------
52 : : * Instrumentation information about read streams and I/O
53 : : * ---------------------
54 : : */
55 : : typedef struct IOStats
56 : : {
57 : : /* number of buffers returned to consumer (for averaging distance) */
58 : : uint64 prefetch_count;
59 : :
60 : : /* sum of pinned_buffers sampled at each buffer return */
61 : : uint64 distance_sum;
62 : :
63 : : /* maximum actual pinned_buffers observed during the scan */
64 : : int16 distance_max;
65 : :
66 : : /* maximum possible look-ahead distance (max_pinned_buffers) */
67 : : int16 distance_capacity;
68 : :
69 : : /* number of waits for a read (for the I/O) */
70 : : uint64 wait_count;
71 : :
72 : : /* I/O stats */
73 : : uint64 io_count; /* number of I/Os */
74 : : uint64 io_nblocks; /* sum of blocks for all I/Os */
75 : : uint64 io_in_progress; /* sum of in-progress I/Os */
76 : : } IOStats;
77 : :
78 : : typedef struct TableScanInstrumentation
79 : : {
80 : : IOStats io;
81 : : } TableScanInstrumentation;
82 : :
83 : : /* merge IO statistics from 'src' into 'dst' */
84 : : static inline void
166 tomas.vondra@postgre 85 :UBC 0 : AccumulateIOStats(IOStats *dst, IOStats *src)
86 : : {
87 : 0 : dst->prefetch_count += src->prefetch_count;
88 : 0 : dst->distance_sum += src->distance_sum;
89 [ # # ]: 0 : if (src->distance_max > dst->distance_max)
90 : 0 : dst->distance_max = src->distance_max;
91 [ # # ]: 0 : if (src->distance_capacity > dst->distance_capacity)
92 : 0 : dst->distance_capacity = src->distance_capacity;
93 : 0 : dst->wait_count += src->wait_count;
94 : 0 : dst->io_count += src->io_count;
95 : 0 : dst->io_nblocks += src->io_nblocks;
96 : 0 : dst->io_in_progress += src->io_in_progress;
97 : 0 : }
98 : :
99 : :
100 : : /* ---------------------
101 : : * Instrumentation information for index scans (used by all AM interfaces)
102 : : * ---------------------
103 : : */
104 : : typedef struct IndexScanInstrumentation
105 : : {
106 : : /* Index search count (incremented with pgstat_count_index_scan call) */
107 : : uint64 nsearches;
108 : :
109 : : /* Table tuples fetched count (incremented during index-only scans) */
110 : : uint64 ntabletuplefetches;
111 : : } IndexScanInstrumentation;
112 : :
113 : : /*
114 : : * Shared memory container for per-worker information
115 : : */
116 : : typedef struct SharedIndexScanInstrumentation
117 : : {
118 : : int num_workers;
119 : : IndexScanInstrumentation winstrument[FLEXIBLE_ARRAY_MEMBER];
120 : : } SharedIndexScanInstrumentation;
121 : :
122 : :
123 : : /* ---------------------
124 : : * Instrumentation information for bitmap heap scans
125 : : *
126 : : * exact_pages total number of exact pages retrieved
127 : : * lossy_pages total number of lossy pages retrieved
128 : : * ---------------------
129 : : */
130 : : typedef struct BitmapHeapScanInstrumentation
131 : : {
132 : : uint64 exact_pages;
133 : : uint64 lossy_pages;
134 : : TableScanInstrumentation stats;
135 : : } BitmapHeapScanInstrumentation;
136 : :
137 : : /*
138 : : * Shared memory container for per-worker information
139 : : */
140 : : typedef struct SharedBitmapHeapInstrumentation
141 : : {
142 : : int num_workers;
143 : : BitmapHeapScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
144 : : } SharedBitmapHeapInstrumentation;
145 : :
146 : :
147 : : /* ---------------------
148 : : * Instrumentation information for Memoize
149 : : * ---------------------
150 : : */
151 : : typedef struct MemoizeInstrumentation
152 : : {
153 : : uint64 cache_hits; /* number of rescans where we've found the
154 : : * scan parameters values to be cached */
155 : : uint64 cache_misses; /* number of rescans where we've not found the
156 : : * scan parameters values to be cached */
157 : : uint64 cache_evictions; /* number of cache entries removed due to
158 : : * the need to free memory */
159 : : uint64 cache_overflows; /* number of times we've had to bypass the
160 : : * cache when filling it due to not being
161 : : * able to free enough space to store the
162 : : * current scan's tuples */
163 : : uint64 mem_peak; /* peak memory usage in bytes */
164 : : } MemoizeInstrumentation;
165 : :
166 : : /*
167 : : * Shared memory container for per-worker memoize information
168 : : */
169 : : typedef struct SharedMemoizeInfo
170 : : {
171 : : int num_workers;
172 : : MemoizeInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
173 : : } SharedMemoizeInfo;
174 : :
175 : :
176 : : /* ---------------------
177 : : * Instrumentation information for Sorts.
178 : : * ---------------------
179 : : */
180 : :
181 : : typedef enum
182 : : {
183 : : SORT_SPACE_TYPE_DISK,
184 : : SORT_SPACE_TYPE_MEMORY,
185 : : } TuplesortSpaceType;
186 : :
187 : : /*
188 : : * The parallel-sort infrastructure relies on having a zero TuplesortMethod
189 : : * to indicate that a worker never did anything, so we assign zero to
190 : : * SORT_TYPE_STILL_IN_PROGRESS. The other values of this enum can be
191 : : * OR'ed together to represent a situation where different workers used
192 : : * different methods, so we need a separate bit for each one. Keep the
193 : : * NUM_TUPLESORTMETHODS constant in sync with the number of bits!
194 : : */
195 : : typedef enum
196 : : {
197 : : SORT_TYPE_STILL_IN_PROGRESS = 0,
198 : : SORT_TYPE_TOP_N_HEAPSORT = 1 << 0,
199 : : SORT_TYPE_QUICKSORT = 1 << 1,
200 : : SORT_TYPE_EXTERNAL_SORT = 1 << 2,
201 : : SORT_TYPE_EXTERNAL_MERGE = 1 << 3,
202 : : } TuplesortMethod;
203 : : #define NUM_TUPLESORTMETHODS 4
204 : :
205 : : typedef struct TuplesortInstrumentation
206 : : {
207 : : TuplesortMethod sortMethod; /* sort algorithm used */
208 : : TuplesortSpaceType spaceType; /* type of space spaceUsed represents */
209 : : int64 spaceUsed; /* space consumption, in kB */
210 : : } TuplesortInstrumentation;
211 : :
212 : : /*
213 : : * Shared memory container for per-worker sort information
214 : : */
215 : : typedef struct SharedSortInfo
216 : : {
217 : : int num_workers;
218 : : TuplesortInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
219 : : } SharedSortInfo;
220 : :
221 : :
222 : : /* ---------------------
223 : : * Instrumentation information for nodeHash.c
224 : : * ---------------------
225 : : */
226 : : typedef struct HashInstrumentation
227 : : {
228 : : int nbuckets; /* number of buckets at end of execution */
229 : : int nbuckets_original; /* planned number of buckets */
230 : : int nbatch; /* number of batches at end of execution */
231 : : int nbatch_original; /* planned number of batches */
232 : : Size space_peak; /* peak memory usage in bytes */
233 : : } HashInstrumentation;
234 : :
235 : : /*
236 : : * Shared memory container for per-worker information
237 : : */
238 : : typedef struct SharedHashInfo
239 : : {
240 : : int num_workers;
241 : : HashInstrumentation hinstrument[FLEXIBLE_ARRAY_MEMBER];
242 : : } SharedHashInfo;
243 : :
244 : :
245 : : /* ---------------------
246 : : * Instrumentation information for IncrementalSort
247 : : * ---------------------
248 : : */
249 : : typedef struct IncrementalSortGroupInfo
250 : : {
251 : : int64 groupCount;
252 : : int64 maxDiskSpaceUsed;
253 : : int64 totalDiskSpaceUsed;
254 : : int64 maxMemorySpaceUsed;
255 : : int64 totalMemorySpaceUsed;
256 : : uint32 sortMethods; /* bitmask of TuplesortMethod */
257 : : } IncrementalSortGroupInfo;
258 : :
259 : : typedef struct IncrementalSortInfo
260 : : {
261 : : IncrementalSortGroupInfo fullsortGroupInfo;
262 : : IncrementalSortGroupInfo prefixsortGroupInfo;
263 : : } IncrementalSortInfo;
264 : :
265 : : /* Shared memory container for per-worker incremental sort information */
266 : : typedef struct SharedIncrementalSortInfo
267 : : {
268 : : int num_workers;
269 : : IncrementalSortInfo sinfo[FLEXIBLE_ARRAY_MEMBER];
270 : : } SharedIncrementalSortInfo;
271 : :
272 : :
273 : : /* ---------------------
274 : : * Instrumentation information for sequential scans
275 : : * ---------------------
276 : : */
277 : : typedef struct SeqScanInstrumentation
278 : : {
279 : : TableScanInstrumentation stats;
280 : : } SeqScanInstrumentation;
281 : :
282 : : /*
283 : : * Shared memory container for per-worker information
284 : : */
285 : : typedef struct SharedSeqScanInstrumentation
286 : : {
287 : : int num_workers;
288 : : SeqScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
289 : : } SharedSeqScanInstrumentation;
290 : :
291 : :
292 : : /*
293 : : * Instrumentation information for TID range scans
294 : : */
295 : : typedef struct TidRangeScanInstrumentation
296 : : {
297 : : TableScanInstrumentation stats;
298 : : } TidRangeScanInstrumentation;
299 : :
300 : : /*
301 : : * Shared memory container for per-worker information
302 : : */
303 : : typedef struct SharedTidRangeScanInstrumentation
304 : : {
305 : : int num_workers;
306 : : TidRangeScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
307 : : } SharedTidRangeScanInstrumentation;
308 : :
309 : : #endif /* INSTRUMENT_NODE_H */
|
