Observability for programs
Export OpenTelemetry data
A run, including a syntic -p run, can export OpenTelemetry data. Export is off until SYNTIC_ENABLE_TELEMETRY=1 is set and an exporter is chosen for each signal:
| Variable | Effect |
|---|---|
OTEL_LOGS_EXPORTER | Events: syntic.user_prompt, syntic.tool_decision, syntic.tool_result, syntic.api_request, syntic.api_error, syntic.hook_execution. |
OTEL_METRICS_EXPORTER | Session counters: sessions, cost, tokens, edit decisions, lines changed. |
OTEL_TRACES_EXPORTER | One syntic.turn span per turn and a syntic.tool span per tool call. Timing and names only. |
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS | Where the otlp exporter posts, and the headers it sends. |
Each exporter is console (OTLP JSON on standard error) or otlp (OTLP over HTTP with JSON). Only the http/json protocol is supported; grpc or http/protobuf turns that signal off with a warning. Prompt text is sent only with OTEL_LOG_USER_PROMPTS, and tool arguments only with OTEL_LOG_TOOL_DETAILS. Exported text passes the same secret redaction as tool output. Records carry the trace id from TRACEPARENT, so they line up with the caller’s trace.
SYNTIC_ENABLE_TELEMETRY=1 OTEL_LOGS_EXPORTER=console OTEL_METRICS_EXPORTER=console \
syntic -p "summarise the changelog"Project settings cannot set these variables, and a privacy setting that rules out telemetry turns export off. See the monitoring page.
The run’s own record
A run also reports its own record, which is enough for many pipelines:
- With
--output-format json, the result object has the session id, the turn count, the stop reason, the token usage and the estimated cost. See Cost tracking. - With
--output-format stream-json --verbose, the same fields arrive in the finalresultmessage, and each step arrives as its own line. See Streaming output. - With
--include-hook-events, each hook run appears in the stream as ahook_eventrecord.
Write these records to your own log store for a per-run trail without an exporter.
Keep a run offline
For a run that must make no telemetry calls, set the offline switch in its environment:
SYNTIC_OFFLINE=1 syntic -p "summarise the changelog"Related
- Scripting and CI for the run options and output shapes.