API Reference

The DuckDB OpenTelemetry Extension API includes file readers and live-ingest functions. All file readers accept a path or glob pattern and detect OTLP JSON, JSONL, and protobuf. Native builds also support live ingest.

Table Functions

Use these table functions to read OTLP data:

Traces

read_otlp_traces(path)

Streams trace spans with identifiers, attributes, events, and links. See the schema reference for all 24 columns.

Parameters:

• path (VARCHAR): File path or glob pattern. DuckDB file systems provide local, S3, HTTP(S), Azure, and GCS access.

Logs

read_otlp_logs(path)

Reads log records with severity, body, and trace correlation. See the schema reference for all 18 columns.

Parameters: Same as read_otlp_traces

Metrics

read_otlp_metrics_gauge(path)

Returns gauge metrics (17 columns). See the schema reference for details.

read_otlp_metrics_sum(path)

Returns sum/counter metrics (19 columns) with int_value, double_value, aggregation_temporality, and is_monotonic. See the schema reference for details.

read_otlp_metrics_histogram(path)

Returns standard histogram metrics (22 columns) with counts, sum, min/max, explicit bucket bounds, and bucket counts. See the schema reference for details.

read_otlp_metrics_exp_histogram(path)

Returns exponential histogram metrics (27 columns) with scale, zero bucket, positive buckets, negative buckets, and aggregation temporality. See the schema reference for details.

Parameters: Same as read_otlp_traces

read_otlp_metrics(path) and read_otlp_metrics_summary(path) are registered placeholders. Use the shape-specific metric readers above.

Live Ingest

In native builds, you can run an HTTP server that accepts live OTLP/HTTP exports and streams them into the default DuckDB catalog or an attached writable catalog such as DuckLake or an Iceberg REST catalog. The server buffers rows and commits them in batches: a POST returns 202 Accepted, and rows become durable at the next background commit or on graceful stop. Current native builds commit after about 5 seconds for the oldest buffered row, or when admitted request-body bytes reach about 64 MiB.

• otlp_serve([uri], catalog := '<attached_db>', ...) - Start the ingest server, target a catalog, and create/validate the target tables.
• otlp_flush(uri) - Force a synchronous commit when readers need the latest accepted rows now.
• otlp_stop(uri) - Stop the server listening on uri (commits remaining rows first).
• otlp_server_list() - List running servers with live counters, buffer state, and health.

See the Serve Reference for parameters, catalog targeting, endpoints, auth, and buffered commit behavior. For task-oriented walkthroughs, start with the Live Ingest Quickstart, Stream to Local DuckLake, Stream to Remote DuckLake, Stream to Parquet, Stream to Amazon S3 Tables, or Stream to Cloudflare R2 Data Catalog.

Examples

For task-oriented examples, see the How-to Guides.

For complete schema details, see the Schema Reference.