3 * Definitions related to backend status reporting
5 * Copyright (c) 2001-2025, PostgreSQL Global Development Group
7 * src/include/utils/backend_status.h
10#ifndef BACKEND_STATUS_H
11#define BACKEND_STATUS_H
38 * Shared-memory data structures
45 * For each backend, we keep the SSL status in a separate struct, that
46 * is only filled in if SSL is enabled.
48 * All char arrays must be null-terminated.
52 /* Information about SSL connection */
59 * serial number is max "20 octets" per RFC 5280, so this size should be
70 * For each backend, we keep the GSS status in a separate struct, that
71 * is only filled in if GSS is enabled.
73 * All char arrays must be null-terminated.
77 /* Information about GSSAPI connection */
79 bool gss_auth;
/* If GSSAPI authentication was used */
80 bool gss_enc;
/* If encryption is being used */
89 * Each live backend maintains a PgBackendStatus struct in shared memory
90 * showing its current activity. (The structs are allocated according to
91 * ProcNumber, but that is not critical.) Note that this is unrelated to the
92 * cumulative stats system (i.e. pgstat.c et al).
94 * Each auxiliary process also maintains a PgBackendStatus struct in shared
101 * To avoid locking overhead, we use the following protocol: a backend
102 * increments st_changecount before modifying its entry, and again after
103 * finishing a modification. A would-be reader should note the value of
104 * st_changecount, copy the entry into private memory, then check
105 * st_changecount again. If the value hasn't changed, and if it's even,
106 * the copy is valid; otherwise start over. This makes updates cheap
107 * while reads are potentially expensive, but that's the tradeoff we want.
109 * The above protocol needs memory barriers to ensure that the apparent
110 * order of execution is as it desires. Otherwise, for example, the CPU
111 * might rearrange the code so that st_changecount is incremented twice
112 * before the modification on a machine with weak memory ordering. Hence,
113 * use the macros defined below for manipulating st_changecount, rather
114 * than touching it directly.
118 /* The entry is valid iff st_procpid > 0, unused if st_procpid == 0 */
121 /* Type of backends */
124 /* Times when current backend, transaction, and activity started */
130 /* Database OID, owning user's OID, connection client address */
136 /* Information about SSL connection */
140 /* Information about GSSAPI connection */
147 /* application name; MUST be null-terminated */
151 * Current command string; MUST be null-terminated. Note that this string
152 * possibly is truncated in the middle of a multi-byte character. As
153 * activity strings are stored more frequently than read, that allows to
154 * move the cost of correct truncation to the display side. Use
155 * pgstat_clip_activity() to truncate correctly.
160 * Command progress reporting. Any command which wishes can advertise
161 * that it is running by setting st_progress_command,
162 * st_progress_command_target, and st_progress_param[].
163 * st_progress_command_target should be the OID of the relation which the
164 * command targets (we assume there's just one, as this is meant for
165 * utility commands), but the meaning of each element in the
166 * st_progress_param array is command-specific.
172 /* query identifier, optionally computed using post_parse_analyze_hook */
175 /* plan identifier, optionally computed using planner_hook */
181 * Macros to load and store st_changecount with appropriate memory barriers.
183 * Use PGSTAT_BEGIN_WRITE_ACTIVITY() before, and PGSTAT_END_WRITE_ACTIVITY()
184 * after, modifying the current process's PgBackendStatus data. Note that,
185 * since there is no mechanism for cleaning up st_changecount after an error,
186 * THESE MACROS FORM A CRITICAL SECTION. Any error between them will be
187 * promoted to PANIC, causing a database restart to clean up shared memory!
188 * Hence, keep the critical section as short and straight-line as possible.
189 * Aside from being safer, that minimizes the window in which readers will
192 * Reader logic should follow this sketch:
196 * int before_ct, after_ct;
198 * pgstat_begin_read_activity(beentry, before_ct);
199 * ... copy beentry data to local memory ...
200 * pgstat_end_read_activity(beentry, after_ct);
201 * if (pgstat_read_activity_complete(before_ct, after_ct))
203 * CHECK_FOR_INTERRUPTS();
206 * For extra safety, we generally use volatile beentry pointers, although
207 * the memory barriers should theoretically be sufficient.
209 #define PGSTAT_BEGIN_WRITE_ACTIVITY(beentry) \
211 START_CRIT_SECTION(); \
212 (beentry)->st_changecount++; \
213 pg_write_barrier(); \
216 #define PGSTAT_END_WRITE_ACTIVITY(beentry) \
218 pg_write_barrier(); \
219 (beentry)->st_changecount++; \
220 Assert(((beentry)->st_changecount & 1) == 0); \
221 END_CRIT_SECTION(); \
224 #define pgstat_begin_read_activity(beentry, before_changecount) \
226 (before_changecount) = (beentry)->st_changecount; \
230 #define pgstat_end_read_activity(beentry, after_changecount) \
233 (after_changecount) = (beentry)->st_changecount; \
236 #define pgstat_read_activity_complete(before_changecount, after_changecount) \
237 ((before_changecount) == (after_changecount) && \
238 ((before_changecount) & 1) == 0)
242 * LocalPgBackendStatus
244 * When we build the backend status array, we use LocalPgBackendStatus to be
245 * able to add new values to the struct when needed without adding new fields
246 * to the shared memory. It contains the backend status as a first member.
252 * Local version of the backend status entry.
262 * The xid of the current transaction if available, InvalidTransactionId
268 * The xmin of the current session if available, InvalidTransactionId if
274 * Number of cached subtransactions in the current session.
279 * The number of subtransactions in the current session which exceeded the
280 * cached subtransaction limit.
295 * Other global variables
302 * Functions called from postmaster
310 * Functions called from backends
314/* Initialization functions */
322/* Activity reporting functions */
338 * Support functions for the SQL-callable functions to
339 * generate the pgstat* views.
349#endif /* BACKEND_STATUS_H */
Datum idx(PG_FUNCTION_ARGS)
#define PGSTAT_NUM_PROGRESS_PARAM
int pgstat_fetch_stat_numbackends(void)
struct PgBackendGSSStatus PgBackendGSSStatus
LocalPgBackendStatus * pgstat_get_local_beentry_by_proc_number(ProcNumber procNumber)
void pgstat_clear_backend_activity_snapshot(void)
void pgstat_bestart_security(void)
struct PgBackendSSLStatus PgBackendSSLStatus
void pgstat_bestart_initial(void)
void pgstat_report_query_id(int64 query_id, bool force)
PGDLLIMPORT bool pgstat_track_activities
PGDLLIMPORT PgBackendStatus * MyBEEntry
char * pgstat_clip_activity(const char *raw_activity)
int64 pgstat_get_my_query_id(void)
struct LocalPgBackendStatus LocalPgBackendStatus
@ STATE_IDLEINTRANSACTION_ABORTED
@ STATE_IDLEINTRANSACTION
const char * pgstat_get_crashed_backend_activity(int pid, char *buffer, int buflen)
void BackendStatusShmemInit(void)
PGDLLIMPORT int pgstat_track_activity_query_size
LocalPgBackendStatus * pgstat_get_local_beentry_by_index(int idx)
struct PgBackendStatus PgBackendStatus
void pgstat_report_activity(BackendState state, const char *cmd_str)
BackendType pgstat_get_backend_type_by_proc_number(ProcNumber procNumber)
void pgstat_report_xact_timestamp(TimestampTz tstamp)
void pgstat_report_plan_id(int64 plan_id, bool force)
PgBackendStatus * pgstat_get_beentry_by_proc_number(ProcNumber procNumber)
int64 pgstat_get_my_plan_id(void)
void pgstat_bestart_final(void)
Size BackendStatusShmemSize(void)
void pgstat_report_appname(const char *appname)
const char * pgstat_get_backend_current_activity(int pid, bool checkUser)
void pgstat_report_tempfile(size_t filesize)
TransactionId backend_xid
PgBackendStatus backendStatus
int backend_subxact_count
TransactionId backend_xmin
bool backend_subxact_overflowed
char gss_princ[NAMEDATALEN]
char ssl_version[NAMEDATALEN]
char ssl_cipher[NAMEDATALEN]
char ssl_client_dn[NAMEDATALEN]
char ssl_client_serial[NAMEDATALEN]
char ssl_issuer_dn[NAMEDATALEN]
BackendType st_backendType
TimestampTz st_state_start_timestamp
TimestampTz st_proc_start_timestamp
PgBackendGSSStatus * st_gssstatus
TimestampTz st_activity_start_timestamp
ProgressCommandType st_progress_command
int64 st_progress_param[PGSTAT_NUM_PROGRESS_PARAM]
PgBackendSSLStatus * st_sslstatus
TimestampTz st_xact_start_timestamp
Oid st_progress_command_target