PostgreSQL Source Code  git master
instrument.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * instrument.h
4  * definitions for run-time statistics collection
5  *
6  *
7  * Copyright (c) 2001-2024, PostgreSQL Global Development Group
8  *
9  * src/include/executor/instrument.h
10  *
11  *-------------------------------------------------------------------------
12  */
13 #ifndef INSTRUMENT_H
14 #define INSTRUMENT_H
15 
16 #include "portability/instr_time.h"
17 
18 
19 /*
20  * BufferUsage and WalUsage counters keep being incremented infinitely,
21  * i.e., must never be reset to zero, so that we can calculate how much
22  * the counters are incremented in an arbitrary period.
23  */
24 typedef struct BufferUsage
25 {
26  int64 shared_blks_hit; /* # of shared buffer hits */
27  int64 shared_blks_read; /* # of shared disk blocks read */
28  int64 shared_blks_dirtied; /* # of shared blocks dirtied */
29  int64 shared_blks_written; /* # of shared disk blocks written */
30  int64 local_blks_hit; /* # of local buffer hits */
31  int64 local_blks_read; /* # of local disk blocks read */
32  int64 local_blks_dirtied; /* # of local blocks dirtied */
33  int64 local_blks_written; /* # of local disk blocks written */
34  int64 temp_blks_read; /* # of temp blocks read */
35  int64 temp_blks_written; /* # of temp blocks written */
36  instr_time shared_blk_read_time; /* time spent reading shared blocks */
37  instr_time shared_blk_write_time; /* time spent writing shared blocks */
38  instr_time local_blk_read_time; /* time spent reading local blocks */
39  instr_time local_blk_write_time; /* time spent writing local blocks */
40  instr_time temp_blk_read_time; /* time spent reading temp blocks */
41  instr_time temp_blk_write_time; /* time spent writing temp blocks */
43 
44 /*
45  * WalUsage tracks only WAL activity like WAL records generation that
46  * can be measured per query and is displayed by EXPLAIN command,
47  * pg_stat_statements extension, etc. It does not track other WAL activity
48  * like WAL writes that it's not worth measuring per query. That's tracked
49  * by WAL global statistics counters in WalStats, instead.
50  */
51 typedef struct WalUsage
52 {
53  int64 wal_records; /* # of WAL records produced */
54  int64 wal_fpi; /* # of WAL full page images produced */
55  uint64 wal_bytes; /* size of WAL records produced */
57 
58 /* Flag bits included in InstrAlloc's instrument_options bitmask */
59 typedef enum InstrumentOption
60 {
61  INSTRUMENT_TIMER = 1 << 0, /* needs timer (and row counts) */
62  INSTRUMENT_BUFFERS = 1 << 1, /* needs buffer usage */
63  INSTRUMENT_ROWS = 1 << 2, /* needs row count */
64  INSTRUMENT_WAL = 1 << 3, /* needs WAL usage */
67 
68 typedef struct Instrumentation
69 {
70  /* Parameters set at node creation: */
71  bool need_timer; /* true if we need timer data */
72  bool need_bufusage; /* true if we need buffer usage data */
73  bool need_walusage; /* true if we need WAL usage data */
74  bool async_mode; /* true if node is in async mode */
75  /* Info about current plan cycle: */
76  bool running; /* true if we've completed first tuple */
77  instr_time starttime; /* start time of current iteration of node */
78  instr_time counter; /* accumulated runtime for this node */
79  double firsttuple; /* time for first tuple of this cycle */
80  double tuplecount; /* # of tuples emitted so far this cycle */
81  BufferUsage bufusage_start; /* buffer usage at start */
82  WalUsage walusage_start; /* WAL usage at start */
83  /* Accumulated statistics across all completed cycles: */
84  double startup; /* total startup time (in seconds) */
85  double total; /* total time (in seconds) */
86  double ntuples; /* total tuples produced */
87  double ntuples2; /* secondary node-specific tuple counter */
88  double nloops; /* # of run cycles for this node */
89  double nfiltered1; /* # of tuples removed by scanqual or joinqual */
90  double nfiltered2; /* # of tuples removed by "other" quals */
91  BufferUsage bufusage; /* total buffer usage */
92  WalUsage walusage; /* total WAL usage */
94 
95 typedef struct WorkerInstrumentation
96 {
97  int num_workers; /* # of structures that follow */
100 
103 
104 extern Instrumentation *InstrAlloc(int n, int instrument_options,
105  bool async_mode);
106 extern void InstrInit(Instrumentation *instr, int instrument_options);
107 extern void InstrStartNode(Instrumentation *instr);
108 extern void InstrStopNode(Instrumentation *instr, double nTuples);
109 extern void InstrUpdateTupleCount(Instrumentation *instr, double nTuples);
110 extern void InstrEndLoop(Instrumentation *instr);
111 extern void InstrAggNode(Instrumentation *dst, Instrumentation *add);
112 extern void InstrStartParallelQuery(void);
113 extern void InstrEndParallelQuery(BufferUsage *bufusage, WalUsage *walusage);
114 extern void InstrAccumParallelQuery(BufferUsage *bufusage, WalUsage *walusage);
115 extern void BufferUsageAccumDiff(BufferUsage *dst,
116  const BufferUsage *add, const BufferUsage *sub);
117 extern void WalUsageAccumDiff(WalUsage *dst, const WalUsage *add,
118  const WalUsage *sub);
119 
120 #endif /* INSTRUMENT_H */
#define PGDLLIMPORT
Definition: c.h:1303
#define PG_INT32_MAX
Definition: c.h:576
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:385
void InstrUpdateTupleCount(Instrumentation *instr, double nTuples)
Definition: instrument.c:132
void InstrAccumParallelQuery(BufferUsage *bufusage, WalUsage *walusage)
Definition: instrument.c:218
void InstrEndLoop(Instrumentation *instr)
Definition: instrument.c:140
void InstrAggNode(Instrumentation *dst, Instrumentation *add)
Definition: instrument.c:169
PGDLLIMPORT WalUsage pgWalUsage
Definition: instrument.c:22
struct WorkerInstrumentation WorkerInstrumentation
void InstrEndParallelQuery(BufferUsage *bufusage, WalUsage *walusage)
Definition: instrument.c:208
Instrumentation * InstrAlloc(int n, int instrument_options, bool async_mode)
Definition: instrument.c:31
struct Instrumentation Instrumentation
InstrumentOption
Definition: instrument.h:60
@ INSTRUMENT_ALL
Definition: instrument.h:65
@ INSTRUMENT_TIMER
Definition: instrument.h:61
@ INSTRUMENT_BUFFERS
Definition: instrument.h:62
@ INSTRUMENT_WAL
Definition: instrument.h:64
@ INSTRUMENT_ROWS
Definition: instrument.h:63
void WalUsageAccumDiff(WalUsage *dst, const WalUsage *add, const WalUsage *sub)
Definition: instrument.c:286
void InstrStartParallelQuery(void)
Definition: instrument.c:200
PGDLLIMPORT BufferUsage pgBufferUsage
Definition: instrument.c:20
struct WalUsage WalUsage
struct BufferUsage BufferUsage
void InstrInit(Instrumentation *instr, int instrument_options)
Definition: instrument.c:58
void BufferUsageAccumDiff(BufferUsage *dst, const BufferUsage *add, const BufferUsage *sub)
Definition: instrument.c:248
void InstrStartNode(Instrumentation *instr)
Definition: instrument.c:68
void InstrStopNode(Instrumentation *instr, double nTuples)
Definition: instrument.c:84
instr_time local_blk_read_time
Definition: instrument.h:38
int64 shared_blks_dirtied
Definition: instrument.h:28
int64 local_blks_hit
Definition: instrument.h:30
instr_time temp_blk_write_time
Definition: instrument.h:41
instr_time shared_blk_read_time
Definition: instrument.h:36
instr_time shared_blk_write_time
Definition: instrument.h:37
int64 local_blks_written
Definition: instrument.h:33
instr_time temp_blk_read_time
Definition: instrument.h:40
instr_time local_blk_write_time
Definition: instrument.h:39
int64 temp_blks_read
Definition: instrument.h:34
int64 shared_blks_read
Definition: instrument.h:27
int64 shared_blks_written
Definition: instrument.h:29
int64 temp_blks_written
Definition: instrument.h:35
int64 local_blks_read
Definition: instrument.h:31
int64 local_blks_dirtied
Definition: instrument.h:32
int64 shared_blks_hit
Definition: instrument.h:26
double nfiltered2
Definition: instrument.h:90
BufferUsage bufusage_start
Definition: instrument.h:81
double nfiltered1
Definition: instrument.h:89
double startup
Definition: instrument.h:84
WalUsage walusage
Definition: instrument.h:92
bool need_bufusage
Definition: instrument.h:72
double ntuples
Definition: instrument.h:86
BufferUsage bufusage
Definition: instrument.h:91
bool need_walusage
Definition: instrument.h:73
instr_time starttime
Definition: instrument.h:77
instr_time counter
Definition: instrument.h:78
WalUsage walusage_start
Definition: instrument.h:82
double firsttuple
Definition: instrument.h:79
double ntuples2
Definition: instrument.h:87
double tuplecount
Definition: instrument.h:80
uint64 wal_bytes
Definition: instrument.h:55
int64 wal_fpi
Definition: instrument.h:54
int64 wal_records
Definition: instrument.h:53
Instrumentation instrument[FLEXIBLE_ARRAY_MEMBER]
Definition: instrument.h:98