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 */
|
