Repository navigation
[FEATURE] --output otel phase 2 and 3: OTLP/HTTP push exporter and backend recipes #755
Description
Summary
Follow-up to #738, which shipped phase 1 (--output otel as a general output format, one OTLP/JSON LogsData per row plus a completion record per statement) in #754 and is documented under Output Modes. This issue carries the two remaining phases from that design.
Phase 2: OTLP/HTTP push exporter
Push the records straight to an OTLP-capable backend instead of (or as well as) writing the file, driven by the standard environment variables so no new flags are needed:
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT(falling back toOTEL_EXPORTER_OTLP_ENDPOINT+/v1/logs)OTEL_EXPORTER_OTLP_HEADERS(for example a Datadog API key or ClickStack ingestion token)
The LogsData emitted today is byte for byte the body of POST /v1/logs, so this is an HTTP client plus batching per statement (chunked for large result sets), no new dependency. Targets ClickStack's OTLP intake and Datadog's OTLP endpoint directly, and any OpenTelemetry Collector otlp receiver.
- Exporter behind the env vars above; batch per statement, chunked for large results; retry with backoff on 429 / 5xx
- Robot scenario against a mocked OTLP endpoint asserting the request body, headers and batching
-
global-flags/ Output Modes docs updated
Phase 3: backend recipes
A docs page with the joint use cases end to end:
- ClickHouse: materialized view from
otel_logsinto a typed inventory table keyed by(snapshot_id, identity); latest state per resource (argMaxby timestamp); drift between two snapshots (join on identity, fingerprint inequality, anti-joins for appeared and disappeared); entitlement history (principal, role, first seen, last seen) - Datadog: resource attribute mapping and the equivalent log queries
- A scheduled CI example (
TRACEPARENT,OTEL_RESOURCE_ATTRIBUTESstampingdeployment.environmentand a job name)
Design already settled in #738
Per-row grain; statement start time as the snapshot instant on every record; stackql.snapshot.id, stackql.query.hash and stackql.row.fingerprint as the correlation keys; no identity heuristics (the backend chooses the key); nested columns as JSON strings in attributes with the full document in the body. The attribute schema is pinned at scope github.com/stackql/stackql/internal/stackql/output version 1.0.0.
Activity
desc-alias-and-otlp-push-exporter (#795)
jeffreyaven commentedon Sep 27, 2026
Closing as completed. Phase 2 shipped in #795 (merged to main as 15c83e7) and the phase 2 and phase 3 docs are published.
Phase 2: OTLP/HTTP push exporter
One change from the design above: the exporter is configured through a new
--otel.configflag, not through theOTEL_EXPORTER_OTLP_*environment variables. Following review on #795, configuration lives in a DTO like the other raw-config flags, and no exporter environment variables are read.{ "exporter": { "endpoint": "http://collector:4318/v1/logs", "headers": { "authorization": "<token>" }, "timeout_ms": 10000, "batch_size": 512 } }exporter.endpointis required to enable the exporter and is used verbatim.timeout_msandbatch_sizedefault to 10000 and 512. Records still stream to stdout or the output file as before, and a failed push is reported on stderr. Retries run up to four attempts with a doubling backoff from 500ms, honouringRetry-After.The phase 1 variables
OTEL_RESOURCE_ATTRIBUTES,OTEL_SERVICE_NAMEandTRACEPARENTare unchanged.Phase 3: backend recipes
Published as OTel Backend Recipes:
TRACEPARENTandOTEL_RESOURCE_ATTRIBUTESNot in scope here
The MCP audit
otelformat still writes to file only. It can adopt the same exporter and DTO in a follow-up if there is demand.