Skip to content

Trazas

control.observability.traces

Sapsan exporta trazas mediante OTLP/HTTP con protobuf. Configure el receptor en Sapsan; el endpoint HTTP debe incluir la ruta completa /v1/traces.

Iniciar Jaeger

Para diagnosticar en una máquina, inicie 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

Esta configuración guarda las trazas en RAM y las pierde al detener el proceso. De forma predeterminada, el número de trazas es ilimitado: al acumularse, aumenta el consumo de RAM y puede agotarse la memoria disponible. Configure jaeger_storage.backends.<nombre>.memory.max_traces en Jaeger para limitar las trazas almacenadas; limita su número, no la memoria en bytes. El almacenamiento en memoria de Jaeger está pensado para diagnósticos breves. Para un uso prolongado, configure almacenamiento persistente.

Configurar Sapsan

telemetry es una configuración local del proceso: central no entrega esta sección al streamer. Añádala a su configuración de inicio existente /etc/sapsan/sapsan.yaml (o al archivo indicado por CONFIG_PATH):

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

enabled activa la exportación. sample_ratio es una cadena con la proporción de muestreo de trazas nuevas: "0.01" equivale al 1% y "1.0" a todas; se respeta la decisión del span padre. El valor predeterminado es "0.01". Para un diagnóstico breve puede usar "1.0" temporalmente.

Recargue la configuración local del servicio. El exportador aplica los cambios sin reiniciar el proceso:

sudo systemctl reload sapsan

Tras realizar operaciones cubiertas por las trazas, abra http://127.0.0.1:16686, seleccione el servicio sapsan y busque trazas. La exportación se realiza por lotes, por lo que aparecen con retraso.

Si Sapsan se ejecuta en Docker, 127.0.0.1 apunta a su propio contenedor. Conecte Sapsan y Jaeger a la misma red Docker y utilice http://jaeger:4318/v1/traces, donde jaeger es el nombre del contenedor receptor.

Compatibilidad con variables de entorno

Si falta telemetry.otlp, Sapsan admite OTEL_ENDPOINT y 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

La sección telemetry.otlp tiene prioridad sobre estas variables. Sin la sección ni OTEL_ENDPOINT, la exportación está desactivada; los logs JSON siguen escribiéndose en stdout.