Configuration

pg_stat_ch is configured through PostgreSQL GUC (Grand Unified Configuration) parameters. All parameters use the pg_stat_ch. prefix.

How to set parameters

Parameters can be set in postgresql.conf, via ALTER SYSTEM, or with SET (for session-level parameters only):

# postgresql.conf
pg_stat_ch.enabled = on
pg_stat_ch.flush_interval_ms = 500
pg_stat_ch.clickhouse_host = 'clickhouse.internal'

Context determines when a change takes effect:

Context	When it takes effect	How to apply
`postmaster`	Server restart only	`systemctl restart postgresql`
`sighup`	Configuration reload	`SELECT pg_reload_conf();` or `pg_ctl reload`
`suset`	Superuser SET	`SET pg_stat_ch.param = value;`

General

`pg_stat_ch.enabled`

Enable or disable query telemetry collection.


Type	boolean
Default	`on`
Context	sighup

When disabled, hooks still fire but skip event creation. The background worker continues running but has nothing to export. Use this to temporarily pause collection without restarting PostgreSQL.

-- Disable collection (takes effect immediately after reload)
ALTER SYSTEM SET pg_stat_ch.enabled = off;
SELECT pg_reload_conf();

-- Re-enable
ALTER SYSTEM SET pg_stat_ch.enabled = on;
SELECT pg_reload_conf();

`pg_stat_ch.hostname`

Override the machine hostname sent with events.


Type	string
Default	`''` (empty, uses system hostname)
Context	postmaster

Useful in containerized environments where the system hostname is a random container ID. Set this to a stable identifier like the pod name or instance ID.

`pg_stat_ch.log_min_elevel`

Minimum error severity level to capture via the emit_log_hook.


Type	enum
Default	`warning`
Context	suset
Values	`debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `info`, `notice`, `warning`, `error`, `fatal`, `panic`

Controls which PostgreSQL log messages are captured as events. The default (warning) captures warnings, errors, fatals, and panics. Set to error to skip warnings, or debug5 to capture everything.

-- Capture only errors and above
SET pg_stat_ch.log_min_elevel = 'error';

-- Capture everything including debug messages (noisy)
SET pg_stat_ch.log_min_elevel = 'debug5';

Queue

The shared-memory ring buffer sits between the foreground hooks and the background worker. These settings control its size and drain behavior.

`pg_stat_ch.queue_capacity`

Maximum number of events the ring buffer can hold.


Type	integer
Default	`131072` (128K events)
Min	`1024`
Max	`4194304` (4M events)
Context	postmaster

Must be a power of 2 (1024, 2048, 4096, … 4194304). The ring buffer uses bitmask arithmetic for slot indexing, which requires a power-of-2 capacity. Each event is approximately 4.5 KB. The default capacity of 131072 events uses about 576 MB of shared memory. Adjust based on your query throughput and acceptable memory usage.

Changing this parameter requires a PostgreSQL restart.

Sizing guidance:

Workload	QPS	Recommended capacity	Memory
Low traffic	< 1,000	8192	~36 MB
Medium traffic	1,000 - 10,000	65536	~288 MB
High traffic	10,000 - 100,000	131072 (default)	~576 MB
Very high traffic	> 100,000	524288+	~2.3 GB+

The queue needs to hold enough events to buffer a burst while the background worker flushes a batch. If dropped_events in pg_stat_ch_stats() is non-zero, increase this value.

`pg_stat_ch.flush_interval_ms`

Interval between export batches, in milliseconds.


Type	integer
Default	`200`
Min	`100`
Max	`60000`
Context	sighup
Unit	milliseconds

The background worker sleeps for this duration between drain cycles. Lower values reduce latency from query execution to ClickHouse visibility. Higher values reduce the number of ClickHouse inserts (fewer, larger batches).

`pg_stat_ch.batch_max`

Maximum number of events per ClickHouse insert.


Type	integer
Default	`200000`
Min	`1`
Max	`1000000`
Context	sighup

Limits the size of each batch sent to ClickHouse. The background worker drains up to batch_max events per insert, then loops until the queue is empty or below the threshold. Larger batches are more efficient for ClickHouse but use more memory in the background worker.

ClickHouse connection

These parameters configure the connection to ClickHouse. All require a PostgreSQL restart to take effect.

`pg_stat_ch.clickhouse_host`

ClickHouse server hostname.


Type	string
Default	`localhost`
Context	postmaster

`pg_stat_ch.clickhouse_port`

ClickHouse native protocol port.


Type	integer
Default	`9000`
Min	`1`
Max	`65535`
Context	postmaster

This is the native TCP protocol port, not the HTTP port (8123). The native protocol is more efficient for bulk inserts.

`pg_stat_ch.clickhouse_user`

ClickHouse username.


Type	string
Default	`default`
Context	postmaster

`pg_stat_ch.clickhouse_password`

ClickHouse password.


Type	string
Default	`''` (empty)
Context	postmaster

This parameter is restricted to superusers (GUC_SUPERUSER_ONLY). It is not visible via SHOW to non-superuser roles.

`pg_stat_ch.clickhouse_database`

ClickHouse database name where the events_raw table and materialized views live.


Type	string
Default	`pg_stat_ch`
Context	postmaster

`pg_stat_ch.clickhouse_use_tls`

Enable TLS encryption for ClickHouse connections.


Type	boolean
Default	`off`
Context	postmaster

`pg_stat_ch.clickhouse_skip_tls_verify`

Skip TLS certificate verification.


Type	boolean
Default	`off`
Context	postmaster

Only use this for testing. In production, configure proper TLS certificates.

OpenTelemetry

These parameters configure the OpenTelemetry export backend. Enable it with pg_stat_ch.use_otel = on. When OTel mode is active, events are sent as OpenTelemetry logs and metrics instead of ClickHouse inserts.

`pg_stat_ch.use_otel`

Send events via OpenTelemetry instead of ClickHouse.


Type	boolean
Default	`off`
Context	postmaster

When enabled, the background worker sends events to an OTel collector via gRPC instead of inserting into ClickHouse. The ClickHouse connection parameters are ignored.

`pg_stat_ch.otel_endpoint`

OpenTelemetry gRPC endpoint.


Type	string
Default	`localhost:4317`
Context	postmaster

The host:port of the OTel collector’s gRPC receiver. Port 4317 is the standard OTel gRPC port.

`pg_stat_ch.otel_log_queue_size`

Maximum number of log records buffered in the OTel batch processor before dropping.


Type	integer
Default	`65536`
Min	`512`
Max	`1048576`
Context	postmaster

`pg_stat_ch.otel_log_batch_size`

Number of log records per gRPC export call.


Type	integer
Default	`8192`
Min	`1`
Max	`131072`
Context	postmaster

`pg_stat_ch.otel_log_max_bytes`

Maximum gRPC message size in bytes for OTel log export.


Type	integer
Default	`3145728` (3 MiB)
Min	`65536` (64 KiB)
Max	`67108864` (64 MiB)
Context	postmaster
Unit	bytes

The gRPC default maximum is 4 MiB. The default value of 3 MiB leaves a safety margin.

`pg_stat_ch.otel_log_delay_ms`

Delay between OTel batch export attempts.


Type	integer
Default	`100`
Min	`10`
Max	`60000`
Context	postmaster
Unit	milliseconds

`pg_stat_ch.otel_metric_interval_ms`

How often aggregated metric histograms are exported via gRPC.


Type	integer
Default	`5000`
Min	`100`
Max	`300000`
Context	postmaster
Unit	milliseconds

Metrics export is asynchronous and does not block the background worker.

Debug

These parameters are for development and testing only.

`pg_stat_ch.debug_force_locked_overflow`

Force the overflow code path in the locked enqueue path.


Type	boolean
Default	`off`
Context	suset

Used to deterministically test the overflow-under-lock deadlock fix. Do not enable in production.

Get started

Guides

Reference

How to set parameters

General

`pg_stat_ch.enabled`

`pg_stat_ch.hostname`

`pg_stat_ch.log_min_elevel`

Queue

`pg_stat_ch.queue_capacity`

`pg_stat_ch.flush_interval_ms`

`pg_stat_ch.batch_max`

ClickHouse connection

`pg_stat_ch.clickhouse_host`

`pg_stat_ch.clickhouse_port`

`pg_stat_ch.clickhouse_user`

`pg_stat_ch.clickhouse_password`

`pg_stat_ch.clickhouse_database`

`pg_stat_ch.clickhouse_use_tls`

`pg_stat_ch.clickhouse_skip_tls_verify`

OpenTelemetry

`pg_stat_ch.use_otel`

`pg_stat_ch.otel_endpoint`

`pg_stat_ch.otel_log_queue_size`

`pg_stat_ch.otel_log_batch_size`

`pg_stat_ch.otel_log_max_bytes`

`pg_stat_ch.otel_log_delay_ms`

`pg_stat_ch.otel_metric_interval_ms`

Debug

`pg_stat_ch.debug_force_locked_overflow`

Get started

Guides

Reference

​How to set parameters

​General

​pg_stat_ch.enabled

​pg_stat_ch.hostname

​pg_stat_ch.log_min_elevel

​Queue

​pg_stat_ch.queue_capacity

​pg_stat_ch.flush_interval_ms

​pg_stat_ch.batch_max

​ClickHouse connection

​pg_stat_ch.clickhouse_host

​pg_stat_ch.clickhouse_port

​pg_stat_ch.clickhouse_user

​pg_stat_ch.clickhouse_password

​pg_stat_ch.clickhouse_database

​pg_stat_ch.clickhouse_use_tls

​pg_stat_ch.clickhouse_skip_tls_verify

​OpenTelemetry

​pg_stat_ch.use_otel

​pg_stat_ch.otel_endpoint

​pg_stat_ch.otel_log_queue_size

​pg_stat_ch.otel_log_batch_size

​pg_stat_ch.otel_log_max_bytes

​pg_stat_ch.otel_log_delay_ms

​pg_stat_ch.otel_metric_interval_ms

​Debug

​pg_stat_ch.debug_force_locked_overflow

How to set parameters

General

`pg_stat_ch.enabled`

`pg_stat_ch.hostname`

`pg_stat_ch.log_min_elevel`

Queue

`pg_stat_ch.queue_capacity`

`pg_stat_ch.flush_interval_ms`

`pg_stat_ch.batch_max`

ClickHouse connection

`pg_stat_ch.clickhouse_host`

`pg_stat_ch.clickhouse_port`

`pg_stat_ch.clickhouse_user`

`pg_stat_ch.clickhouse_password`

`pg_stat_ch.clickhouse_database`

`pg_stat_ch.clickhouse_use_tls`

`pg_stat_ch.clickhouse_skip_tls_verify`

OpenTelemetry

`pg_stat_ch.use_otel`

`pg_stat_ch.otel_endpoint`

`pg_stat_ch.otel_log_queue_size`

`pg_stat_ch.otel_log_batch_size`

`pg_stat_ch.otel_log_max_bytes`

`pg_stat_ch.otel_log_delay_ms`

`pg_stat_ch.otel_metric_interval_ms`

Debug

`pg_stat_ch.debug_force_locked_overflow`