SDKObservability

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:

VariableEffect
OTEL_LOGS_EXPORTEREvents: syntic.user_prompt, syntic.tool_decision, syntic.tool_result, syntic.api_request, syntic.api_error, syntic.hook_execution.
OTEL_METRICS_EXPORTERSession counters: sessions, cost, tokens, edit decisions, lines changed.
OTEL_TRACES_EXPORTEROne syntic.turn span per turn and a syntic.tool span per tool call. Timing and names only.
OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERSWhere 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 final result message, and each step arrives as its own line. See Streaming output.
  • With --include-hook-events, each hook run appears in the stream as a hook_event record.

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"