DuckMetrics

OpenTelemetry collector for DuckDB. Ingest metrics, traces, and logs with OpenTelemetry Protocol (OTLP) and Prometheus, and query them with SQL using Quack.

flowchart LR
    metrics[Metrics]
    traces[Traces]
    logs[Logs]

    metrics -- Prometheus --> duckmetrics[DuckMetrics]
    traces -- OTel gRPC --> duckmetrics
    logs -- OTel HTTP --> duckmetrics

    duckmetrics -- Quack --> dashboard[Dashboard]

Usage

DuckMetrics --duckdb ./telemetry.duckdb --quack.token super_secret

This starts Quack on quack:0.0.0.0:9494 by default. If --quack.token is empty, DuckMetrics generates one before starting; set --quack.token when another client needs to connect:

ATTACH 'quack:duckmetrics.example.com' AS duckmetrics (TOKEN 'super_secret');
FROM duckmetrics.query('
SELECT *
FROM otel_number_points AS points
JOIN otel_metric_series AS series USING (series_id)
');

After the Quack attach handshake, remote Quack data queries are restricted to read-only statements beginning with SELECT, FROM, WITH, DESCRIBE, or SHOW.

Dashboard

Run DuckMetrics with the dashboard enabled:

DuckMetrics --duckdb ./telemetry.duckdb --dashboard --dashboard.refresh 5s

The dashboard opens an in-memory DuckDB client, loads the linked Quack extension, attaches DuckMetrics, and serves OTel table totals plus recent metrics, traces, and logs on 0.0.0.0:8080 by default. Use --dashboard.listen to change the HTTP address.

Options

Each CLI option can also be set with an environment variable. CLI flags take precedence over environment variables.

CLI option	Environment variable
--prometheus.config	DUCKMETRICS_PROMETHEUS_CONFIG
--duckdb	DUCKMETRICS_DUCKDB_PATH
--otlp.grpc-endpoint	DUCKMETRICS_OTLP_GRPC_ENDPOINT
--otlp.http-endpoint	DUCKMETRICS_OTLP_HTTP_ENDPOINT
--quack.uri	DUCKMETRICS_QUACK_URI
--quack.token	DUCKMETRICS_QUACK_TOKEN
--telemetry.metrics-endpoint	DUCKMETRICS_TELEMETRY_METRICS_ENDPOINT

Dashboard options are available when --dashboard is set: --dashboard.listen, --dashboard.limit, and --dashboard.refresh.

Prometheus

Scrape a Prometheus config in addition to OTLP:

DuckMetrics --prometheus.config ./prometheus.yml --duckdb ./metrics.duckdb

Install

go

GOPROXY=https://trev.zip/api/packages/llc/DuckMetrics \
    go install trev.zip/llc/DuckMetrics@latest

go run trev.zip/llc/DuckMetrics@latest

docker

docker run trev.zip/llc/duckmetrics:latest

nix

nix run git+https://trev.zip/llc/DuckMetrics.git

download

https://trev.zip/llc/DuckMetrics/releases

Development

requirements

• nix

getting started

nix develop

run

nix run .#dev

format

nix fmt

check

nix flake check

build

nix build