OpenTelemetry export

pg_stat_ch can export query telemetry as OpenTelemetry logs instead of inserting directly into ClickHouse. This lets you route data through your existing observability pipeline (Grafana, Datadog, Honeycomb, etc.) without running a separate ClickHouse instance.

Enable OpenTelemetry mode

Set these parameters in postgresql.conf and restart PostgreSQL:

pg_stat_ch.use_otel = on
pg_stat_ch.otel_endpoint = 'localhost:4317'

When use_otel is enabled, the ClickHouse connection parameters are ignored. The background worker sends events to the OTel collector via gRPC.

How it works

The OTel exporter maps pg_stat_ch events to OpenTelemetry semantic conventions:

Logs: Each query execution becomes an OTel log record with attributes following the database semantic conventions (db.name, db.user, db.operation.name, db.query.text).

The exporter builds OTLP log requests directly in the bgworker. pg_stat_ch’s shared-memory queue already buffers events, and the exporter chunks those events into bounded gRPC requests.

Configuration

All OTel-specific parameters require a PostgreSQL restart.

Parameter	Default	Description
`pg_stat_ch.otel_endpoint`	`localhost:4317`	OTel collector gRPC endpoint (`host:port`)
`pg_stat_ch.otel_log_queue_size`	`65536`	Compatibility no-op; pg_stat_ch’s shared-memory queue already buffers events
`pg_stat_ch.otel_log_batch_size`	`8192`	Max records per OTLP log export call
`pg_stat_ch.otel_log_max_bytes`	`3145728` (3 MiB)	Soft byte budget per OTLP log export call
`pg_stat_ch.otel_log_delay_ms`	`100`	Per-export gRPC deadline
`pg_stat_ch.otel_metric_interval_ms`	`5000`	Compatibility no-op retained for legacy configs

See the configuration reference for details on each parameter.

Example: OTel Collector to ClickHouse

You can use the OpenTelemetry Collector as a middle layer between pg_stat_ch and ClickHouse. This is useful when you want to fan out data to multiple backends or apply transformations.

# otel-collector-config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  clickhouse:
    endpoint: tcp://clickhouse:9000
    database: pg_stat_ch
  otlphttp:
    endpoint: https://your-observability-platform.com

service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [clickhouse, otlphttp]
    metrics:
      receivers: [otlp]
      exporters: [otlphttp]

Example: Grafana with Tempo/Loki

Route pg_stat_ch logs to Loki for Grafana dashboards:

exporters:
  loki:
    endpoint: http://loki:3100/loki/api/v1/push
service:
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [loki]

Verify data is flowing

Check export health the same way as with ClickHouse:

SELECT
    exported_events,
    send_failures,
    last_error_text,
    queue_usage_pct
FROM pg_stat_ch_stats();

If send_failures is increasing, check:

The OTel collector is running and reachable at the configured endpoint
The collector’s gRPC receiver is listening on port 4317
PostgreSQL logs for connection error details

Documentation Index

​Enable OpenTelemetry mode

​How it works

​Configuration

​Example: OTel Collector to ClickHouse

​Example: Grafana with Tempo/Loki