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
188 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 Material
178 : : * ---------------------
179 : : */
180 : : typedef struct MaterialInstrumentation
181 : : {
182 : : int64 maxSpaceUsed; /* peak memory/disk usage in bytes, or 0 if no
183 : : * tuplestore was created */
184 : : bool usedDisk; /* did the tuplestore spill to disk? */
185 : : } MaterialInstrumentation;
186 : :
187 : : /*
188 : : * Shared memory container for per-worker material information
189 : : */
190 : : typedef struct SharedMaterialInfo
191 : : {
192 : : int num_workers;
193 : : MaterialInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
194 : : } SharedMaterialInfo;
195 : :
196 : :
197 : : /* ---------------------
198 : : * Instrumentation information for Sorts.
199 : : * ---------------------
200 : : */
201 : :
202 : : typedef enum
203 : : {
204 : : SORT_SPACE_TYPE_DISK,
205 : : SORT_SPACE_TYPE_MEMORY,
206 : : } TuplesortSpaceType;
207 : :
208 : : /*
209 : : * The parallel-sort infrastructure relies on having a zero TuplesortMethod
210 : : * to indicate that a worker never did anything, so we assign zero to
211 : : * SORT_TYPE_STILL_IN_PROGRESS. The other values of this enum can be
212 : : * OR'ed together to represent a situation where different workers used
213 : : * different methods, so we need a separate bit for each one. Keep the
214 : : * NUM_TUPLESORTMETHODS constant in sync with the number of bits!
215 : : */
216 : : typedef enum
217 : : {
218 : : SORT_TYPE_STILL_IN_PROGRESS = 0,
219 : : SORT_TYPE_TOP_N_HEAPSORT = 1 << 0,
220 : : SORT_TYPE_QUICKSORT = 1 << 1,
221 : : SORT_TYPE_EXTERNAL_SORT = 1 << 2,
222 : : SORT_TYPE_EXTERNAL_MERGE = 1 << 3,
223 : : } TuplesortMethod;
224 : : #define NUM_TUPLESORTMETHODS 4
225 : :
226 : : typedef struct TuplesortInstrumentation
227 : : {
228 : : TuplesortMethod sortMethod; /* sort algorithm used */
229 : : TuplesortSpaceType spaceType; /* type of space spaceUsed represents */
230 : : int64 spaceUsed; /* space consumption, in kB */
231 : : } TuplesortInstrumentation;
232 : :
233 : : /*
234 : : * Shared memory container for per-worker sort information
235 : : */
236 : : typedef struct SharedSortInfo
237 : : {
238 : : int num_workers;
239 : : TuplesortInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
240 : : } SharedSortInfo;
241 : :
242 : :
243 : : /* ---------------------
244 : : * Instrumentation information for nodeHash.c
245 : : * ---------------------
246 : : */
247 : : typedef struct HashInstrumentation
248 : : {
249 : : int nbuckets; /* number of buckets at end of execution */
250 : : int nbuckets_original; /* planned number of buckets */
251 : : int nbatch; /* number of batches at end of execution */
252 : : int nbatch_original; /* planned number of batches */
253 : : Size space_peak; /* peak memory usage in bytes */
254 : : } HashInstrumentation;
255 : :
256 : : /*
257 : : * Shared memory container for per-worker information
258 : : */
259 : : typedef struct SharedHashInfo
260 : : {
261 : : int num_workers;
262 : : HashInstrumentation hinstrument[FLEXIBLE_ARRAY_MEMBER];
263 : : } SharedHashInfo;
264 : :
265 : :
266 : : /* ---------------------
267 : : * Instrumentation information for IncrementalSort
268 : : * ---------------------
269 : : */
270 : : typedef struct IncrementalSortGroupInfo
271 : : {
272 : : int64 groupCount;
273 : : int64 maxDiskSpaceUsed;
274 : : int64 totalDiskSpaceUsed;
275 : : int64 maxMemorySpaceUsed;
276 : : int64 totalMemorySpaceUsed;
277 : : uint32 sortMethods; /* bitmask of TuplesortMethod */
278 : : } IncrementalSortGroupInfo;
279 : :
280 : : typedef struct IncrementalSortInfo
281 : : {
282 : : IncrementalSortGroupInfo fullsortGroupInfo;
283 : : IncrementalSortGroupInfo prefixsortGroupInfo;
284 : : } IncrementalSortInfo;
285 : :
286 : : /* Shared memory container for per-worker incremental sort information */
287 : : typedef struct SharedIncrementalSortInfo
288 : : {
289 : : int num_workers;
290 : : IncrementalSortInfo sinfo[FLEXIBLE_ARRAY_MEMBER];
291 : : } SharedIncrementalSortInfo;
292 : :
293 : :
294 : : /* ---------------------
295 : : * Instrumentation information for sequential scans
296 : : * ---------------------
297 : : */
298 : : typedef struct SeqScanInstrumentation
299 : : {
300 : : TableScanInstrumentation stats;
301 : : } SeqScanInstrumentation;
302 : :
303 : : /*
304 : : * Shared memory container for per-worker information
305 : : */
306 : : typedef struct SharedSeqScanInstrumentation
307 : : {
308 : : int num_workers;
309 : : SeqScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
310 : : } SharedSeqScanInstrumentation;
311 : :
312 : :
313 : : /*
314 : : * Instrumentation information for TID range scans
315 : : */
316 : : typedef struct TidRangeScanInstrumentation
317 : : {
318 : : TableScanInstrumentation stats;
319 : : } TidRangeScanInstrumentation;
320 : :
321 : : /*
322 : : * Shared memory container for per-worker information
323 : : */
324 : : typedef struct SharedTidRangeScanInstrumentation
325 : : {
326 : : int num_workers;
327 : : TidRangeScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
328 : : } SharedTidRangeScanInstrumentation;
329 : :
330 : : #endif /* INSTRUMENT_NODE_H */
|
