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-2022, 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 blk_read_time; /* time spent reading blocks */
37  instr_time blk_write_time; /* time spent writing blocks */
38  instr_time temp_blk_read_time; /* time spent reading temp blocks */
39  instr_time temp_blk_write_time; /* time spent writing temp blocks */
41 
42 /*
43  * WalUsage tracks only WAL activity like WAL records generation that
44  * can be measured per query and is displayed by EXPLAIN command,
45  * pg_stat_statements extension, etc. It does not track other WAL activity
46  * like WAL writes that it's not worth measuring per query. That's tracked
47  * by WAL global statistics counters in WalStats, instead.
48  */
49 typedef struct WalUsage
50 {
51  int64 wal_records; /* # of WAL records produced */
52  int64 wal_fpi; /* # of WAL full page images produced */
53  uint64 wal_bytes; /* size of WAL records produced */
55 
56 /* Flag bits included in InstrAlloc's instrument_options bitmask */
57 typedef enum InstrumentOption
58 {
59  INSTRUMENT_TIMER = 1 << 0, /* needs timer (and row counts) */
60  INSTRUMENT_BUFFERS = 1 << 1, /* needs buffer usage */
61  INSTRUMENT_ROWS = 1 << 2, /* needs row count */
62  INSTRUMENT_WAL = 1 << 3, /* needs WAL usage */
65 
66 typedef struct Instrumentation
67 {
68  /* Parameters set at node creation: */
69  bool need_timer; /* true if we need timer data */
70  bool need_bufusage; /* true if we need buffer usage data */
71  bool need_walusage; /* true if we need WAL usage data */
72  bool async_mode; /* true if node is in async mode */
73  /* Info about current plan cycle: */
74  bool running; /* true if we've completed first tuple */
75  instr_time starttime; /* start time of current iteration of node */
76  instr_time counter; /* accumulated runtime for this node */
77  double firsttuple; /* time for first tuple of this cycle */
78  double tuplecount; /* # of tuples emitted so far this cycle */
79  BufferUsage bufusage_start; /* buffer usage at start */
80  WalUsage walusage_start; /* WAL usage at start */
81  /* Accumulated statistics across all completed cycles: */
82  double startup; /* total startup time (in seconds) */
83  double total; /* total time (in seconds) */
84  double ntuples; /* total tuples produced */
85  double ntuples2; /* secondary node-specific tuple counter */
86  double nloops; /* # of run cycles for this node */
87  double nfiltered1; /* # of tuples removed by scanqual or joinqual */
88  double nfiltered2; /* # of tuples removed by "other" quals */
89  BufferUsage bufusage; /* total buffer usage */
90  WalUsage walusage; /* total WAL usage */
92 
93 typedef struct WorkerInstrumentation
94 {
95  int num_workers; /* # of structures that follow */
98 
101 
102 extern Instrumentation *InstrAlloc(int n, int instrument_options,
103  bool async_mode);
104 extern void InstrInit(Instrumentation *instr, int instrument_options);
105 extern void InstrStartNode(Instrumentation *instr);
106 extern void InstrStopNode(Instrumentation *instr, double nTuples);
107 extern void InstrUpdateTupleCount(Instrumentation *instr, double nTuples);
108 extern void InstrEndLoop(Instrumentation *instr);
109 extern void InstrAggNode(Instrumentation *dst, Instrumentation *add);
110 extern void InstrStartParallelQuery(void);
111 extern void InstrEndParallelQuery(BufferUsage *bufusage, WalUsage *walusage);
112 extern void InstrAccumParallelQuery(BufferUsage *bufusage, WalUsage *walusage);
113 extern void BufferUsageAccumDiff(BufferUsage *dst,
114  const BufferUsage *add, const BufferUsage *sub);
115 extern void WalUsageAccumDiff(WalUsage *dst, const WalUsage *add,
116  const WalUsage *sub);
117 
118 #endif /* INSTRUMENT_H */
#define PGDLLIMPORT
Definition: c.h:1252
#define PG_INT32_MAX
Definition: c.h:525
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:362
struct timespec instr_time
Definition: instr_time.h:83
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:58
@ INSTRUMENT_ALL
Definition: instrument.h:63
@ INSTRUMENT_TIMER
Definition: instrument.h:59
@ INSTRUMENT_BUFFERS
Definition: instrument.h:60
@ INSTRUMENT_WAL
Definition: instrument.h:62
@ INSTRUMENT_ROWS
Definition: instrument.h:61
void WalUsageAccumDiff(WalUsage *dst, const WalUsage *add, const WalUsage *sub)
Definition: instrument.c:280
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:246
void InstrStartNode(Instrumentation *instr)
Definition: instrument.c:68
void InstrStopNode(Instrumentation *instr, double nTuples)
Definition: instrument.c:84
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:39
int64 local_blks_written
Definition: instrument.h:33
instr_time blk_write_time
Definition: instrument.h:37
instr_time temp_blk_read_time
Definition: instrument.h:38
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
instr_time blk_read_time
Definition: instrument.h:36
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:88
BufferUsage bufusage_start
Definition: instrument.h:79
double nfiltered1
Definition: instrument.h:87
double startup
Definition: instrument.h:82
WalUsage walusage
Definition: instrument.h:90
bool need_bufusage
Definition: instrument.h:70
double ntuples
Definition: instrument.h:84
BufferUsage bufusage
Definition: instrument.h:89
bool need_walusage
Definition: instrument.h:71
instr_time starttime
Definition: instrument.h:75
instr_time counter
Definition: instrument.h:76
WalUsage walusage_start
Definition: instrument.h:80
double firsttuple
Definition: instrument.h:77
double ntuples2
Definition: instrument.h:85
double tuplecount
Definition: instrument.h:78
uint64 wal_bytes
Definition: instrument.h:53
int64 wal_fpi
Definition: instrument.h:52
int64 wal_records
Definition: instrument.h:51
Instrumentation instrument[FLEXIBLE_ARRAY_MEMBER]
Definition: instrument.h:96