QueryBurn

Telegram alerts for expensive queries in ClickHouse.

QueryBurn is a lightweight read-only agent that scans system.query_log, detects queries that burn memory, scan too much data, or slow down dashboards, and sends actionable alerts to Telegram.

QueryBurn is independent software and is not affiliated with or endorsed by ClickHouse, Inc.

Demo

Get a Telegram alert when a dashboard or service runs a wasteful query:

Try the same alert locally without a ClickHouse server:

go run ./cmd/queryburn mock-alert \
  --mock-file examples/mock-query.json \
  --telegram \
  --telegram-bot-token "123456:token" \
  --telegram-chat-id "123456789"

Need a bot token or chat ID? See the Telegram setup guide.

Want to test QueryBurn on a real local ClickHouse server? See the local ClickHouse demo.

Why

ClickHouse systems often make it easy to scan huge amounts of data quickly. That also makes it easy for a dashboard, BI user, or batch job to burn cluster resources without anyone noticing.

QueryBurn answers one question:

Which queries are burning my cluster right now?

Quick start

docker run --rm \
  ghcr.io/ofeliacode/queryburn:latest \
  mock-alert --mock-file examples/mock-query.json --telegram=false

Scan a ClickHouse server:

docker run --rm \
  ghcr.io/ofeliacode/queryburn:latest \
  scan --clickhouse-dsn "http://user:pass@host:8123/default"

Enable Telegram alerts:

docker run --rm \
  ghcr.io/ofeliacode/queryburn:latest \
  scan \
  --clickhouse-dsn "http://user:pass@host:8123/default" \
  --telegram \
  --telegram-bot-token "123456:token" \
  --telegram-chat-id "-1001234567890"

Read-only ClickHouse user

For the first MVP, QueryBurn only needs read access to system.query_log.

CREATE USER queryburn IDENTIFIED BY 'strong_password';
GRANT SELECT ON system.query_log TO queryburn;

What QueryBurn detects

Default alert thresholds:

• query duration >= 30 seconds
• read bytes >= 500 GB
• memory usage >= 10 GB
• huge scan with tiny result

Example alert:

QueryBurn Alert

Expensive ClickHouse query detected

Severity: warning
User: metabase
Duration: 42.1s
Read: 840.0GB
Memory: 18.0GB
Result rows: 134

Why it matters:
huge scan for a small result, read more than 500 GB

Configuration

Variable	Default	Description
CLICKHOUSE_DSN	required	ClickHouse HTTP DSN
TELEGRAM_ENABLED	false	Send Telegram alerts
TELEGRAM_BOT_TOKEN	empty	Telegram bot token
TELEGRAM_CHAT_ID	empty	Telegram chat/channel ID
SCAN_WINDOW	15m	Lookback window for system.query_log
SCAN_INTERVAL	5m	Interval for watch mode
QUERY_TIMEOUT	30s	ClickHouse query timeout
ALERT_MIN_DURATION_MS	30000	Duration threshold
ALERT_MIN_READ_BYTES	500000000000	Read bytes threshold
ALERT_MIN_MEMORY_BYTES	10000000000	Memory threshold
DEDUPE_TTL	30m	Do not repeat the same fingerprint during this period
STATE_PATH	.queryburn/state.json	Local dedupe state

CLI

queryburn scan
queryburn watch

Flags mirror the environment variables:

queryburn scan \
  --clickhouse-dsn "http://user:pass@localhost:8123/default" \
  --window 30m \
  --min-read-bytes 100000000000

Preview a Telegram alert without ClickHouse

Use the mock file to see how QueryBurn alerts look in Telegram:

go run ./cmd/queryburn mock-alert \
  --mock-file examples/mock-query.json \
  --telegram \
  --telegram-bot-token "123456:token" \
  --telegram-chat-id "-1001234567890"

To only print the message locally:

go run ./cmd/queryburn mock-alert \
  --mock-file examples/mock-query.json \
  --telegram=false

Development

go run ./cmd/queryburn scan --clickhouse-dsn "http://user:pass@localhost:8123/default"
go test ./...

License

Apache License 2.0.