Branch data 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
85 : 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 indexscans (amgettuple and amgetbitmap)
102 : : * ---------------------
103 : : */
104 : : typedef struct IndexScanInstrumentation
105 : : {
106 : : /* Index search count (incremented with pgstat_count_index_scan call) */
107 : : uint64 nsearches;
108 : : } IndexScanInstrumentation;
109 : :
110 : : /*
111 : : * Shared memory container for per-worker information
112 : : */
113 : : typedef struct SharedIndexScanInstrumentation
114 : : {
115 : : int num_workers;
116 : : IndexScanInstrumentation winstrument[FLEXIBLE_ARRAY_MEMBER];
117 : : } SharedIndexScanInstrumentation;
118 : :
119 : :
120 : : /* ---------------------
121 : : * Instrumentation information for bitmap heap scans
122 : : *
123 : : * exact_pages total number of exact pages retrieved
124 : : * lossy_pages total number of lossy pages retrieved
125 : : * ---------------------
126 : : */
127 : : typedef struct BitmapHeapScanInstrumentation
128 : : {
129 : : uint64 exact_pages;
130 : : uint64 lossy_pages;
131 : : TableScanInstrumentation stats;
132 : : } BitmapHeapScanInstrumentation;
133 : :
134 : : /*
135 : : * Shared memory container for per-worker information
136 : : */
137 : : typedef struct SharedBitmapHeapInstrumentation
138 : : {
139 : : int num_workers;
140 : : BitmapHeapScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
141 : : } SharedBitmapHeapInstrumentation;
142 : :
143 : :
144 : : /* ---------------------
145 : : * Instrumentation information for Memoize
146 : : * ---------------------
147 : : */
148 : : typedef struct MemoizeInstrumentation
149 : : {
150 : : uint64 cache_hits; /* number of rescans where we've found the
151 : : * scan parameters values to be cached */
152 : : uint64 cache_misses; /* number of rescans where we've not found the
153 : : * scan parameters values to be cached */
154 : : uint64 cache_evictions; /* number of cache entries removed due to
155 : : * the need to free memory */
156 : : uint64 cache_overflows; /* number of times we've had to bypass the
157 : : * cache when filling it due to not being
158 : : * able to free enough space to store the
159 : : * current scan's tuples */
160 : : uint64 mem_peak; /* peak memory usage in bytes */
161 : : } MemoizeInstrumentation;
162 : :
163 : : /*
164 : : * Shared memory container for per-worker memoize information
165 : : */
166 : : typedef struct SharedMemoizeInfo
167 : : {
168 : : int num_workers;
169 : : MemoizeInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
170 : : } SharedMemoizeInfo;
171 : :
172 : :
173 : : /* ---------------------
174 : : * Instrumentation information for Sorts.
175 : : * ---------------------
176 : : */
177 : :
178 : : typedef enum
179 : : {
180 : : SORT_SPACE_TYPE_DISK,
181 : : SORT_SPACE_TYPE_MEMORY,
182 : : } TuplesortSpaceType;
183 : :
184 : : /*
185 : : * The parallel-sort infrastructure relies on having a zero TuplesortMethod
186 : : * to indicate that a worker never did anything, so we assign zero to
187 : : * SORT_TYPE_STILL_IN_PROGRESS. The other values of this enum can be
188 : : * OR'ed together to represent a situation where different workers used
189 : : * different methods, so we need a separate bit for each one. Keep the
190 : : * NUM_TUPLESORTMETHODS constant in sync with the number of bits!
191 : : */
192 : : typedef enum
193 : : {
194 : : SORT_TYPE_STILL_IN_PROGRESS = 0,
195 : : SORT_TYPE_TOP_N_HEAPSORT = 1 << 0,
196 : : SORT_TYPE_QUICKSORT = 1 << 1,
197 : : SORT_TYPE_EXTERNAL_SORT = 1 << 2,
198 : : SORT_TYPE_EXTERNAL_MERGE = 1 << 3,
199 : : } TuplesortMethod;
200 : : #define NUM_TUPLESORTMETHODS 4
201 : :
202 : : typedef struct TuplesortInstrumentation
203 : : {
204 : : TuplesortMethod sortMethod; /* sort algorithm used */
205 : : TuplesortSpaceType spaceType; /* type of space spaceUsed represents */
206 : : int64 spaceUsed; /* space consumption, in kB */
207 : : } TuplesortInstrumentation;
208 : :
209 : : /*
210 : : * Shared memory container for per-worker sort information
211 : : */
212 : : typedef struct SharedSortInfo
213 : : {
214 : : int num_workers;
215 : : TuplesortInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
216 : : } SharedSortInfo;
217 : :
218 : :
219 : : /* ---------------------
220 : : * Instrumentation information for nodeHash.c
221 : : * ---------------------
222 : : */
223 : : typedef struct HashInstrumentation
224 : : {
225 : : int nbuckets; /* number of buckets at end of execution */
226 : : int nbuckets_original; /* planned number of buckets */
227 : : int nbatch; /* number of batches at end of execution */
228 : : int nbatch_original; /* planned number of batches */
229 : : Size space_peak; /* peak memory usage in bytes */
230 : : } HashInstrumentation;
231 : :
232 : : /*
233 : : * Shared memory container for per-worker information
234 : : */
235 : : typedef struct SharedHashInfo
236 : : {
237 : : int num_workers;
238 : : HashInstrumentation hinstrument[FLEXIBLE_ARRAY_MEMBER];
239 : : } SharedHashInfo;
240 : :
241 : :
242 : : /* ---------------------
243 : : * Instrumentation information for IncrementalSort
244 : : * ---------------------
245 : : */
246 : : typedef struct IncrementalSortGroupInfo
247 : : {
248 : : int64 groupCount;
249 : : int64 maxDiskSpaceUsed;
250 : : int64 totalDiskSpaceUsed;
251 : : int64 maxMemorySpaceUsed;
252 : : int64 totalMemorySpaceUsed;
253 : : uint32 sortMethods; /* bitmask of TuplesortMethod */
254 : : } IncrementalSortGroupInfo;
255 : :
256 : : typedef struct IncrementalSortInfo
257 : : {
258 : : IncrementalSortGroupInfo fullsortGroupInfo;
259 : : IncrementalSortGroupInfo prefixsortGroupInfo;
260 : : } IncrementalSortInfo;
261 : :
262 : : /* Shared memory container for per-worker incremental sort information */
263 : : typedef struct SharedIncrementalSortInfo
264 : : {
265 : : int num_workers;
266 : : IncrementalSortInfo sinfo[FLEXIBLE_ARRAY_MEMBER];
267 : : } SharedIncrementalSortInfo;
268 : :
269 : :
270 : : /* ---------------------
271 : : * Instrumentation information for sequential scans
272 : : * ---------------------
273 : : */
274 : : typedef struct SeqScanInstrumentation
275 : : {
276 : : TableScanInstrumentation stats;
277 : : } SeqScanInstrumentation;
278 : :
279 : : /*
280 : : * Shared memory container for per-worker information
281 : : */
282 : : typedef struct SharedSeqScanInstrumentation
283 : : {
284 : : int num_workers;
285 : : SeqScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
286 : : } SharedSeqScanInstrumentation;
287 : :
288 : :
289 : : /*
290 : : * Instrumentation information for TID range scans
291 : : */
292 : : typedef struct TidRangeScanInstrumentation
293 : : {
294 : : TableScanInstrumentation stats;
295 : : } TidRangeScanInstrumentation;
296 : :
297 : : /*
298 : : * Shared memory container for per-worker information
299 : : */
300 : : typedef struct SharedTidRangeScanInstrumentation
301 : : {
302 : : int num_workers;
303 : : TidRangeScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
304 : : } SharedTidRangeScanInstrumentation;
305 : :
306 : : #endif /* INSTRUMENT_NODE_H */
|
