otlp

OpenTelemetry-Traces, -Logs und -Metriken mit SQL abfragen — oder Live-OTLP/HTTP in DuckDB, DuckLake oder Iceberg streamen

Maintainer: smithclay

Installation und Laden

INSTALL otlp FROM community;
LOAD otlp;

Beispiel

-- Load the extension
LOAD otlp;

-- Traces: find the slow spans
SELECT trace_id, span_name, service_name, duration
FROM read_otlp_traces('traces.jsonl')
WHERE duration > 1e9            -- longer than one second
ORDER BY duration DESC
LIMIT 10;

-- Or run a live OTLP/HTTP endpoint and query what arrives
SELECT listen_url, auth_token FROM otlp_serve('otlp:localhost:4318');
-- POST telemetry to http://localhost:4318/v1/logs.
-- Rows commit automatically in the background; otlp_stop commits remaining rows.
SELECT status FROM otlp_stop('otlp:localhost:4318');
SELECT * FROM otlp_logs;

-- Metrics: latest gauge readings (works native and in the browser)
SELECT timestamp, service_name, metric_name, value
FROM read_otlp_metrics_gauge('metrics.jsonl')
ORDER BY timestamp DESC;

-- Logs: just the errors, read straight from S3
SELECT timestamp, severity_text, body, service_name
FROM read_otlp_logs('s3://bucket/logs-*.jsonl')
WHERE severity_text = 'ERROR';

-- Protobuf works too, on native builds
SELECT * FROM read_otlp_traces('traces.pb') LIMIT 10;

Über otlp

OpenTelemetry, in SQL

Richten Sie diese Erweiterung auf OTLP-Daten und fragen Sie sie wie jede andere Tabelle ab. Traces, Logs und Metriken kommen als richtige Spalten an — service_name, trace_id, duration, value — nicht als JSON, das Sie durchsuchen müssen. Das Schema folgt dem OpenTelemetry-ClickHouse-Exporter, daher sind die Spalten typisiert, schnell zu filtern und stabil.

Es gibt zwei Einstiege.

Dateien lesen

Sechs Tabellenfunktionen lesen OTLP-Exporte direkt von Datenträger oder Objektspeicher:

• read_otlp_traces() — Spans mit Attributen, Events, Links und einer berechneten Duration
• read_otlp_logs() — Datensätze mit Severity, Body und Trace-Korrelation
• read_otlp_metrics_gauge(), read_otlp_metrics_sum(), read_otlp_metrics_histogram(), read_otlp_metrics_exp_histogram()

JSON, JSONL und protobuf werden automatisch erkannt. Pfade können lokal, ein Glob, S3, HTTP(S), Azure oder GCS sein. Der Browser-Build (DuckDB-WASM) liest alle drei Formate — versuchen Sie die interaktive Demo.

Live-Ingest bereitstellen (native Builds)

otlp_serve() startet einen OTLP/HTTP-Endpunkt innerhalb von DuckDB. Richten Sie einen Collector oder SDK-Exporter auf http://localhost:4318 und die Zeilen landen in Tabellen, die Sie abfragen können:

SELECT listen_url, auth_token
FROM otlp_serve('otlp:localhost:4318');

Lassen Sie catalog leer, damit die Zeilen im Standardkatalog für schnelle lokale Arbeit landen. Setzen Sie ihn auf ein angehängtes DuckLake-Lakehouse oder einen schreibbaren Iceberg-REST-Katalog für dauerhaften Lakehouse-Ingest.

Ingest wird gepuffert und gruppenweise committet. Ein POST gibt 202 Accepted zurück, sobald Zeilen geparst und gepuffert sind; sie werden beim nächsten automatischen Hintergrund-Commit dauerhaft, derzeit wenn die älteste gepufferte Zeile etwa 5 Sekunden alt ist oder die aufgenommenen Request-Body- Bytes etwa 64 MiB erreichen. otlp_server_list() meldet die Zähler, und otlp_stop() committet den Rest vor dem Herunterfahren. otlp_flush() ist optional: verwenden Sie es nur, wenn Leser die zuletzt akzeptierten Zeilen sofort dauerhaft brauchen, während der Server weiterläuft. Stoppen Sie vor dem Schließen der Datenbank — ein einfaches Schließen committet gepufferte Zeilen nicht.

Anwendungsfälle

• Collector- oder SDK-Exporte lesen und analysieren
• Eine kleine, dauerhaft laufende OTLP-Senke, die nach DuckDB, DuckLake oder Iceberg schreibt
• Telemetrie nach Parquet, CSV oder jedes von DuckDB geschriebene Format konvertieren
• Traces, Logs und Metriken während der lokalen Entwicklung prüfen

Gut zu wissen

• Der Live-Server ist nur nativ und nur HTTP — kein WASM, kein gRPC.
• Dateilesen ist auf 100 MB pro Datei begrenzt.
• Summary-Metriken und das einheitliche read_otlp_metrics() sind noch nicht implementiert.

Referenzen

• OpenTelemetry Protocol (OTLP)
• OpenTelemetry ClickHouse Exporter

Hinzugefügte Funktionen

Überladene Funktionen

Diese Erweiterung fügt keine Funktionsüberladungen hinzu.

Hinzugefügte Typen

Diese Erweiterung fügt keine Typen hinzu.

Hinzugefügte Einstellungen

Diese Erweiterung fügt keine Einstellungen hinzu.