Skip to content

Traces

control.observability.traces

Sapsan exports traces using OTLP/HTTP with protobuf. Set the receiver in the Sapsan configuration; the HTTP endpoint must include the complete /v1/traces path.

Start Jaeger

For diagnostics on one machine, start Jaeger all-in-one:

docker run --rm --name jaeger \
  -p 127.0.0.1:16686:16686 \
  -p 127.0.0.1:4318:4318 \
  cr.jaegertracing.io/jaegertracing/jaeger:2.22.0

This setup stores traces in RAM and loses them when the process stops. The trace count is unlimited by default, so accumulated traces increase RAM usage and can exhaust available memory. Set jaeger_storage.backends.<name>.memory.max_traces in the Jaeger configuration to limit stored traces; this limits the trace count, not memory in bytes. Jaeger memory storage is intended for short diagnostic sessions. Configure persistent storage for long-running use.

Configure Sapsan

telemetry is a local process setting: central does not deliver this section to the streamer. Add it to your existing startup configuration /etc/sapsan/sapsan.yaml (or the file selected by CONFIG_PATH):

telemetry:
  otlp:
    enabled: true
    endpoint: http://127.0.0.1:4318/v1/traces
    sample_ratio: "0.01"

enabled enables export. sample_ratio is a string defining the sampling ratio for new traces: "0.01" means 1%, while "1.0" means all new traces; the parent span sampling decision is respected. The default is "0.01". You can temporarily use "1.0" for a short diagnostic session.

Reload the local service configuration. The exporter applies the changes without restarting the process:

sudo systemctl reload sapsan

After performing operations covered by tracing, open http://127.0.0.1:16686, select the sapsan service and search for traces. Export is batched, so traces appear after a delay.

If Sapsan runs in Docker, 127.0.0.1 refers to its own container. Connect Sapsan and Jaeger to the same Docker network and use http://jaeger:4318/v1/traces, where jaeger is the receiver container name.

Environment variable compatibility

If telemetry.otlp is absent, Sapsan supports OTEL_ENDPOINT and OTEL_TRACES_SAMPLER_ARG:

OTEL_ENDPOINT=http://127.0.0.1:4318/v1/traces \
OTEL_TRACES_SAMPLER_ARG=0.01 \
CONFIG_PATH=/etc/sapsan/sapsan.yaml /usr/sbin/sapsan

The telemetry.otlp section takes priority over these variables. Without the section or OTEL_ENDPOINT, export is disabled; JSON logs continue to be written to stdout.