pmetrics.h File Reference

Public C API for pmetrics extension. More...

#include "postgres.h"
#include "utils/jsonb.h"
#include "utils/dsa.h"

Include dependency graph for pmetrics.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
bool	pmetrics_is_initialized (void)
dsa_handle	pmetrics_get_dsa_handle (void)
dsa_area *	pmetrics_get_dsa (void)
int64	pmetrics_increment_counter (const char *name_str, Jsonb *labels_jsonb)
int64	pmetrics_increment_counter_by (const char *name_str, Jsonb *labels_jsonb, int64 amount)
int64	pmetrics_set_gauge (const char *name_str, Jsonb *labels_jsonb, int64 value)
int64	pmetrics_add_to_gauge (const char *name_str, Jsonb *labels_jsonb, int64 amount)
int64	pmetrics_record_to_histogram (const char *name_str, Jsonb *labels_jsonb, double value)
int64	pmetrics_clear_metrics (void)
int64	pmetrics_delete_metric (const char *name_str, Jsonb *labels_jsonb)
bool	pmetrics_is_enabled (void)

Detailed Description

Public C API for pmetrics extension.

Definition in file pmetrics.h.

Function Documentation

pmetrics_add_to_gauge()

int64 pmetrics_add_to_gauge ( const char *  name_str, Jsonb *  labels_jsonb, int64  amount  )

extern

Add to a gauge (can be positive or negative).

Parameters

name_str	Metric name
labels_jsonb	JSONB labels (can be NULL for empty object)
amount	Amount to add (can be negative; cannot be 0)

Returns

New gauge value after addition

pmetrics_clear_metrics()

int64 pmetrics_clear_metrics ( void  )

extern

Clear all metrics from the metrics table.

Deletes all metric entries and frees associated DSA memory for labels. This is an administrative function typically used for testing or maintenance.

Returns

Number of metrics deleted

pmetrics_delete_metric()

int64 pmetrics_delete_metric ( const char *  name_str, Jsonb *  labels_jsonb  )

extern

Delete all metrics with the specified name and labels.

Note: This can be an expensive operation as it iterates through all metrics.

Parameters

name_str	Metric name
labels_jsonb	JSONB labels (can be NULL for empty object)

Returns

Number of metrics deleted

pmetrics_get_dsa()

dsa_area * pmetrics_get_dsa ( void  )

extern

Get the DSA area pointer for sharing with other extensions. Triggers backend attachment if not already done. Do not call dsa_attach() separately if using this function.

pmetrics_get_dsa_handle()

dsa_handle pmetrics_get_dsa_handle ( void  )

extern

Get the DSA handle for pmetrics' dynamic shared memory area. This is useful for other extensions that need to store the handle in their own shared state during startup.

Raises ERROR if pmetrics is not initialized.

pmetrics_increment_counter()

int64 pmetrics_increment_counter ( const char *  name_str, Jsonb *  labels_jsonb  )

extern

Increment a counter by 1.

Parameters

name_str	Metric name
labels_jsonb	JSONB labels (can be NULL for empty object)

Returns

New counter value after increment

pmetrics_increment_counter_by()

int64 pmetrics_increment_counter_by ( const char *  name_str, Jsonb *  labels_jsonb, int64  amount  )

extern

Increment a counter by a specific amount.

Parameters

name_str	Metric name
labels_jsonb	JSONB labels (can be NULL for empty object)
amount	Amount to increment (must be > 0)

Returns

New counter value after increment

pmetrics_is_enabled()

bool pmetrics_is_enabled ( void  )

extern

Check if metrics collection is currently enabled. Returns the value of pmetrics.enabled configuration parameter.

pmetrics_is_initialized()

bool pmetrics_is_initialized ( void  )

extern

Check if pmetrics is properly initialized. Returns true if pmetrics shared state is initialized and ready.

pmetrics_record_to_histogram()

int64 pmetrics_record_to_histogram ( const char *  name_str, Jsonb *  labels_jsonb, double  value  )

extern

Record a value to a histogram.

Creates both a histogram bucket entry and a histogram_sum entry. This is the recommended way to record histogram values from C code.

Parameters

name_str	Metric name
labels_jsonb	JSONB labels (can be NULL for empty object)
value	The value to record

Returns

Bucket count after recording

pmetrics_set_gauge()

int64 pmetrics_set_gauge ( const char *  name_str, Jsonb *  labels_jsonb, int64  value  )

extern

Set a gauge to a specific value.

Parameters

name_str	Metric name
labels_jsonb	JSONB labels (can be NULL for empty object)
value	Value to set

Returns

The value that was set