postgres/src/include/executor/instrument_node.h

/*-------------------------------------------------------------------------
 *
 * instrument_node.h
 *	  Definitions for node-specific support for parallel query instrumentation
 *
 * These structs purposely contain no pointers because they are copied
 * across processes during parallel query execution.  Each worker copies its
 * individual information into the container struct at executor shutdown time,
 * to allow the leader to display the information in EXPLAIN ANALYZE.
 *
 * Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/executor/instrument_node.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef INSTRUMENT_NODE_H
#define INSTRUMENT_NODE_H

/*
 * Offset added to plan_node_id to create a second TOC key for per-worker scan
 * instrumentation. Instrumentation and parallel-awareness are independent, so
 * separate DSM chunks let each be allocated and initialized only when needed.
 * In the future, if nodes need more DSM allocations, we would need a more
 * robust system.
 */
#define PARALLEL_KEY_SCAN_INSTRUMENT_OFFSET	UINT64CONST(0xD000000000000000)

/* ---------------------
 *	Instrumentation information for aggregate function execution
 * ---------------------
 */
typedef struct AggregateInstrumentation
{
	Size		hash_mem_peak;	/* peak hash table memory usage */
	uint64		hash_disk_used; /* kB of disk space used */
	int			hash_batches_used;	/* batches used during entire execution */
} AggregateInstrumentation;

/*
 * Shared memory container for per-worker aggregate information
 */
typedef struct SharedAggInfo
{
	int			num_workers;
	AggregateInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
} SharedAggInfo;


/* ---------------------
 *	Instrumentation information about read streams and I/O
 * ---------------------
 */
typedef struct IOStats
{
	/* number of buffers returned to consumer (for averaging distance) */
	uint64		prefetch_count;

	/* sum of pinned_buffers sampled at each buffer return */
	uint64		distance_sum;

	/* maximum actual pinned_buffers observed during the scan */
	int16		distance_max;

	/* maximum possible look-ahead distance (max_pinned_buffers) */
	int16		distance_capacity;

	/* number of waits for a read (for the I/O) */
	uint64		wait_count;

	/* I/O stats */
	uint64		io_count;		/* number of I/Os */
	uint64		io_nblocks;		/* sum of blocks for all I/Os */
	uint64		io_in_progress; /* sum of in-progress I/Os */
} IOStats;

typedef struct TableScanInstrumentation
{
	IOStats		io;
} TableScanInstrumentation;

/* merge IO statistics from 'src' into 'dst' */
static inline void
AccumulateIOStats(IOStats *dst, IOStats *src)
{
	dst->prefetch_count += src->prefetch_count;
	dst->distance_sum += src->distance_sum;
	if (src->distance_max > dst->distance_max)
		dst->distance_max = src->distance_max;
	if (src->distance_capacity > dst->distance_capacity)
		dst->distance_capacity = src->distance_capacity;
	dst->wait_count += src->wait_count;
	dst->io_count += src->io_count;
	dst->io_nblocks += src->io_nblocks;
	dst->io_in_progress += src->io_in_progress;
}


/* ---------------------
 *	Instrumentation information for indexscans (amgettuple and amgetbitmap)
 * ---------------------
 */
typedef struct IndexScanInstrumentation
{
	/* Index search count (incremented with pgstat_count_index_scan call) */
	uint64		nsearches;
} IndexScanInstrumentation;

/*
 * Shared memory container for per-worker information
 */
typedef struct SharedIndexScanInstrumentation
{
	int			num_workers;
	IndexScanInstrumentation winstrument[FLEXIBLE_ARRAY_MEMBER];
} SharedIndexScanInstrumentation;


/* ---------------------
 *	Instrumentation information for bitmap heap scans
 *
 *		exact_pages		   total number of exact pages retrieved
 *		lossy_pages		   total number of lossy pages retrieved
 * ---------------------
 */
typedef struct BitmapHeapScanInstrumentation
{
	uint64		exact_pages;
	uint64		lossy_pages;
	TableScanInstrumentation stats;
} BitmapHeapScanInstrumentation;

/*
 * Shared memory container for per-worker information
 */
typedef struct SharedBitmapHeapInstrumentation
{
	int			num_workers;
	BitmapHeapScanInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
} SharedBitmapHeapInstrumentation;


/* ---------------------
 *	Instrumentation information for Memoize
 * ---------------------
 */
typedef struct MemoizeInstrumentation
{
	uint64		cache_hits;		/* number of rescans where we've found the
								 * scan parameters values to be cached */
	uint64		cache_misses;	/* number of rescans where we've not found the
								 * scan parameters values to be cached */
	uint64		cache_evictions;	/* number of cache entries removed due to
									 * the need to free memory */
	uint64		cache_overflows;	/* number of times we've had to bypass the
									 * cache when filling it due to not being
									 * able to free enough space to store the
									 * current scan's tuples */
	uint64		mem_peak;		/* peak memory usage in bytes */
} MemoizeInstrumentation;

/*
 * Shared memory container for per-worker memoize information
 */
typedef struct SharedMemoizeInfo
{
	int			num_workers;
	MemoizeInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
} SharedMemoizeInfo;


/* ---------------------
 *	Instrumentation information for Sorts.
 * ---------------------
 */

typedef enum
{
	SORT_SPACE_TYPE_DISK,
	SORT_SPACE_TYPE_MEMORY,
} TuplesortSpaceType;

/*
 * The parallel-sort infrastructure relies on having a zero TuplesortMethod
 * to indicate that a worker never did anything, so we assign zero to
 * SORT_TYPE_STILL_IN_PROGRESS.  The other values of this enum can be
 * OR'ed together to represent a situation where different workers used
 * different methods, so we need a separate bit for each one.  Keep the
 * NUM_TUPLESORTMETHODS constant in sync with the number of bits!
 */
typedef enum
{
	SORT_TYPE_STILL_IN_PROGRESS = 0,
	SORT_TYPE_TOP_N_HEAPSORT = 1 << 0,
	SORT_TYPE_QUICKSORT = 1 << 1,
	SORT_TYPE_EXTERNAL_SORT = 1 << 2,
	SORT_TYPE_EXTERNAL_MERGE = 1 << 3,
} TuplesortMethod;
#define NUM_TUPLESORTMETHODS 4

typedef struct TuplesortInstrumentation
{
	TuplesortMethod sortMethod; /* sort algorithm used */
	TuplesortSpaceType spaceType;	/* type of space spaceUsed represents */
	int64		spaceUsed;		/* space consumption, in kB */
} TuplesortInstrumentation;

/*
 * Shared memory container for per-worker sort information
 */
typedef struct SharedSortInfo
{
	int			num_workers;
	TuplesortInstrumentation sinstrument[FLEXIBLE_ARRAY_MEMBER];
} SharedSortInfo;


/* ---------------------
 *   Instrumentation information for nodeHash.c
 * ---------------------
 */
typedef struct HashInstrumentation
{
	int			nbuckets;		/* number of buckets at end of execution */
	int			nbuckets_original;	/* planned number of buckets */
	int			nbatch;			/* number of batches at end of execution */
	int			nbatch_original;	/* planned number of batches */
	Size		space_peak;		/* peak memory usage in bytes */
} HashInstrumentation;

/*
 * Shared memory container for per-worker information
 */
typedef struct SharedHashInfo
{
	int			num_workers;
	HashInstrumentation hinstrument[FLEXIBLE_ARRAY_MEMBER];
} SharedHashInfo;


/* ---------------------
 *   Instrumentation information for IncrementalSort
 * ---------------------
 */
typedef struct IncrementalSortGroupInfo
{
	int64		groupCount;
	int64		maxDiskSpaceUsed;
	int64		totalDiskSpaceUsed;
	int64		maxMemorySpaceUsed;
	int64		totalMemorySpaceUsed;
	uint32		sortMethods;	/* bitmask of TuplesortMethod */
} IncrementalSortGroupInfo;

typedef struct IncrementalSortInfo
{
	IncrementalSortGroupInfo fullsortGroupInfo;
	IncrementalSortGroupInfo prefixsortGroupInfo;
} IncrementalSortInfo;

/* Shared memory container for per-worker incremental sort information */
typedef struct SharedIncrementalSortInfo
{
	int			num_workers;
	IncrementalSortInfo sinfo[FLEXIBLE_ARRAY_MEMBER];
} SharedIncrementalSortInfo;

#endif							/* INSTRUMENT_NODE_H */