Open-source · ClickHouse observability

Turn ClickHouse telemetry into query insight.

Click-Dog reads spans and query logs straight from ClickHouse and turns them into traces, query families, and dashboards for Datadog, Splunk, Honeycomb, Grafana Tempo, and any OTLP backend — read-only and bounded, so it never becomes another production load risk.

$ curl -fsSL https://github.com/coltconsulting/click-dog/releases/latest/download/install.sh -o install.sh && sudo bash install.sh

Signed and checksummed before install.

Get started View on GitHub (opens in a new tab)
Public betaApache-2.0 licensed
Read-only by design
One static binary
Fork it freely
trace · slow-query-monitor live · clickhouse
SELECT events JOIN users GROUP BY day 1,284 ms
query · root1284ms
read events487ms
merge parts312ms
hash join users436ms
aggregate day231ms
sort + limit140ms
Click-Dog telemetry conduit diagram showing a read-only ClickHouse source feeding Click-Dog and fanning out to Datadog, Splunk, and Honeycomb
Exports to Datadog Splunk Honeycomb Grafana Tempo Jaeger Elastic Any OTLP
Why Click-Dog

Built to run in production.

Three things shape Click-Dog: it's manageable to run, it stays out of your source system's way, and it explains what your queries are doing.

Manageable in production

Run it as a single static binary, a container, or generated Kubernetes / Docker Compose manifests. Validate config before it talks to anything, dry-run exports, and monitor Click-Dog itself.

healthreadinessstatusmetrics

Low-impact source safety

The non-invasive property. Read-only connections, bounded polling, SQL-level filtering, batching, circuit-breaker protection, and adaptive backoff — so your source system stays in control.

read-onlycircuit breakerbackoffleader-gated HA

Query analysis, not trace shipping

Click-Dog exports spans, but the goal is to explain queries: slow-query traces, query-log enrichment, normalized query families, log-comment context, and ready-made dashboards.

slow queriesquery familiesper-sink health
Features

What Click-Dog ships out of the box.

Click-Dog does more than forward spans. It packages the reports, dashboards, export health, and rollout controls a team needs before trusting a production telemetry path.

01

Slow-query traces

Export ClickHouse native spans enriched with query-log context so slow traces carry the database behavior that caused them.

02

Query families

Group thousands of statements into normalized shapes that make p95, volume, and trend changes easier to reason about.

03

Ready-made dashboards

Provision Datadog application query-analysis dashboards without starting from a blank canvas.

04

Per-sink export health

Know which backend is accepting spans, which one is failing, and when fan-out needs operator attention.

05

Deployment assets

Run as a static binary, systemd service, Docker Compose stack, Kubernetes deployment, or Ansible-managed sidecar fleet.

06

Local analysis reports

Generate bounded read-only reports, including redacted JSON for downstream tooling and AI-assisted review.

Architecture

One bounded pipeline, from source to sink.

Click-Dog sits beside your database — never in the request path — reads telemetry over a read-only connection, filters and batches at the source, then fans out to one or more backends.

Source
ClickHouse
system.opentelemetry_span_log
read-only · no DDL
Query log
system.query_log · backfill
Click-Dog
Collector
poll → filter → dedupe → batch
SQL filterLRU dedupebatchcircuit breakerbackoffleader election
Sinks · fan-out
Datadog
OTLP/gRPC
Splunk
HEC
Honeycomb
OTLP/gRPC
Any OTLP
Tempo · Jaeger · more
Query analysis

Follow a query from signal to finding.

Group queries into families

Roll normalized_query_hash values into stable shapes, then compare volume, p95, and outliers.

Add query-log context

Enrich query root spans with system.query_log metrics and log_comment metadata.

Drill into the evidence

Start from a query, query ID, trace ID, or normalized hash and follow it through spans and family findings.

Build a bounded report

Generate a read-only report with redacted JSON for operators, downstream tooling, or AI-assisted review.

query families · p95 last 24h 12 shapes
Query familyCallsp95Trend
SELECT events JOIN users …48.2k1.28s
SELECT count() FROM orders …211k340ms
INSERT INTO metrics …1.9M22ms
SELECT * FROM sessions WHERE …17.4k512ms
SELECT uniq(uid) FROM events …9.1k2.04s
Safety

Conservative by default — it runs next to your production database.

Click-Dog should make query telemetry easier to trust without making the source system harder to operate.

Source protection

1
Read-only ClickHouse sessionsAll runtime connections enforce readonly=2.
2
No schema changesNo DDL requirement and no write grants to your database.
3
Bounded pollingSQL-level filters, lookback windows, and max spans per cycle cap load.
4
Failure backpressureCircuit breaker and adaptive backoff reduce pressure during incidents.

Rollout control

1
Validate offlineCheck configuration before connecting to source or sink.
2
Dry-run real readsExercise the fetch and filter path while discarding exports.
3
Probe readinessExpose health, readiness, status, and metrics for operations.
4
Use secure transportTLS and mTLS are available for collector and source links.
Deployment

Start small, then roll it out like infrastructure.

Single binary

Static Linux binary for a quick first node or a controlled manual install.

systemd

Installer-generated service, config validation, and local health checks.

Kubernetes

Generated manifests for a centralized cluster reader with readiness probes.

Ansible

Fleet rollout, canary playbook, bounded concurrency, and repeatable config.

Configuration example

Point it at ClickHouse. Pick your sinks. Run.

One YAML file and one command. Validate it, dry-run the export, then turn it on.

click-dog.yaml
clickhouse:
  host: localhost
  port: 9000
  username: default
  password: ${CLICKHOUSE_PASSWORD}

exporters:
  otel:
    - collector_address: localhost:4317
      service_name: click-dog-monitor

monitor:
  enabled: true
  min_trace_duration_ms: 1000
  check_interval_s: 30

log_level: info
terminal~/click-dog
# 1 · validate before it talks to anything
$ ./click-dog -validate -config click-dog.yaml
✓ config valid · 1 source · 1 sink

# 2 · dry-run the export pipeline
$ ./click-dog --dry-run -config click-dog.yaml
→ 248 spans matched · 0 sent (dry-run)

# 3 · run it
$ export CLICKHOUSE_PASSWORD="secret"
$ ./click-dog -config click-dog.yaml
● collector up · leader · exporting
  clickhouse → otel://localhost:4317 healthy

Put a watchdog on your queries.

Open source under Apache 2.0 — run, modify, and redistribute it under the license terms. Read-only by design, and live in minutes.

Get started — it's free Star on GitHub (opens in a new tab)