Troubleshooting

SQL API Reference

pg_stat_ch_stats()

Returns queue and exporter statistics:

SELECT * FROM pg_stat_ch_stats();
Column Type Description
enqueued_events bigint Total events added to queue
dropped_events bigint Events dropped due to full queue
exported_events bigint Events successfully sent to ClickHouse
send_failures bigint Failed export attempts
last_success_ts timestamptz Last successful export timestamp
last_error_text text Most recent error message
last_error_ts timestamptz Most recent error timestamp
queue_size int Current events in queue
queue_capacity int Maximum queue capacity
queue_usage_pct float Queue utilization percentage

Extension Won’t Load

WARNING:  pg_stat_ch must be loaded via shared_preload_libraries

Add shared_preload_libraries = 'pg_stat_ch' to postgresql.conf and restart PostgreSQL.

Events Not Appearing in ClickHouse

  1. Check connection settings: sql SHOW pg_stat_ch.clickhouse_host; SHOW pg_stat_ch.clickhouse_port;

  2. Check stats for errors: sql SELECT * FROM pg_stat_ch_stats();

  3. Check PostgreSQL logs for connection errors.

High Queue Usage

If queue_usage_pct is consistently high: - Increase pg_stat_ch.queue_capacity (restart required) - Decrease pg_stat_ch.flush_interval_ms - Increase pg_stat_ch.batch_max - Ensure ClickHouse is healthy and reachable

Dropped Events

Check the dropped_events counter: sql SELECT dropped_events FROM pg_stat_ch_stats();

Dropped events indicate the queue filled faster than the background worker could export. This is safe (queries continue unaffected) but means some telemetry is lost.