Telemetry#

Sidekick is instrumented with OpenTelemetry. Every command invocation opens a trace span, records a counter and a duration histogram, and — when the command throws — captures an exception event plus an error counter.

Instrumentation is on by default but quiet: with no configuration it writes newline-delimited JSON to local files and never touches the network.

What gets captured#

The setup-telemetry init hook wraps the root config's runCommand — the single point every command is dispatched through — so every command that actually executes is measured. That includes built-in commands, JIT/installed plugin commands (Jira, MySQL, etc.), and nested runs triggered through the MCP server or search.

Metrics

Span attributes

A successful command's span is marked OK. A thrown exception is recorded as an error trace; a non-zero exit(code) is tagged with command.exit_code instead. Calling exit(0) is treated as success.

Safe by default#

Because spans can be shipped off the machine, potentially secret-bearing values are not captured unless you explicitly opt in.

• Command arguments are reduced to a count (command.argc) — the raw argument vector can carry tokens, passwords, or URLs with embedded credentials.
• Failures record only the exception type, not the message or stack.

Opt in when you need the detail:

export SDKCK_OTEL_CAPTURE_ARGV=1    # attach the full command.argv
export SDKCK_OTEL_CAPTURE_ERRORS=1  # attach exception messages + stack traces

Choosing an exporter#

The exporter is selected from the environment at startup so the CLI stays network-free unless you ask otherwise.

Local files (default)#

With nothing configured, traces and metrics are appended as newline-delimited JSON under <configDir>/logs/:

• otel-traces.jsonl
• otel-metrics.jsonl

The file metric exporter uses delta temporality, so each flush records only new activity rather than repeated cumulative snapshots.

OTLP/HTTP collector#

Set an OTLP endpoint to send traces and metrics to a collector (Jaeger, Grafana, Honeycomb, etc.):

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
sdkck api list

Signal-specific endpoints are also honoured:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://localhost:4318/v1/metrics

Authenticated collectors. Most hosted backends require an API key for authentication. The exporter reads the standard OTEL_EXPORTER_OTLP_HEADERS environment variable for this purpose. Add your authentication header alongside the endpoint:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
export OTEL_EXPORTER_OTLP_HEADERS="x-honeycomb-team=YOUR_API_KEY"
sdkck api list

Headers are comma-separated key=value pairs ("key1=val1,key2=val2"), and OTEL_EXPORTER_OTLP_TRACES_HEADERS / OTEL_EXPORTER_OTLP_METRICS_HEADERS override per signal. Because these carry secrets, keep them in your shell or CI secret store rather than committing them.

Console#

Print to stdout — useful for a quick look while developing. Selection is per signal, using the standard OpenTelemetry exporter variables:

OTEL_TRACES_EXPORTER=console sdkck api list    # traces to stdout
OTEL_METRICS_EXPORTER=console sdkck api list   # metrics to stdout

Set both to send traces and metrics to the console at once.

Because the CLI is short-lived, metrics are force-flushed when the outermost command finishes rather than on a timer.

Turning it off#

export SDKCK_OTEL_DISABLED=true  # disable telemetry for sdkck only
export OTEL_SDK_DISABLED=true    # disable instrumentation entirely (standard OTEL var)
export OTEL_DEBUG=1              # enable OpenTelemetry diagnostic logging

Use SDKCK_OTEL_DISABLED when OpenTelemetry is enabled host-wide for other tools but you want sdkck to stay silent — it turns off sdkck's instrumentation without touching the shared OTEL_SDK_DISABLED that those other tools honour.

Spans carry service.name = sdkck and the CLI version as service.version.

Environment reference#

When no OTLP endpoint and no console exporter are configured, telemetry falls back to the local JSON files under <configDir>/logs/.