Traces¶

control.observability.traces

O Sapsan exporta traces por OTLP/HTTP com protobuf. Configure o receptor no Sapsan; o endpoint HTTP deve incluir o caminho completo /v1/traces.

Iniciar o Jaeger¶

Para diagnóstico em uma máquina, inicie o 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

Essa configuração armazena traces na RAM e os perde quando o processo para. Por padrão, a quantidade de traces é ilimitada: o acúmulo aumenta o uso de RAM e pode esgotar a memória disponível. Configure jaeger_storage.backends.<nome>.memory.max_traces no Jaeger para limitar os traces armazenados; ele limita a quantidade, não a memória em bytes. O armazenamento em memória do Jaeger destina-se a diagnósticos breves. Para uso prolongado, configure armazenamento persistente.

Configurar o Sapsan¶

telemetry é uma configuração local do processo: o central não entrega esta seção ao streamer. Adicione-a à configuração de inicialização existente /etc/sapsan/sapsan.yaml (ou ao arquivo indicado por CONFIG_PATH):

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

enabled ativa a exportação. sample_ratio é uma string com a proporção de amostragem de novos traces: "0.01" equivale a 1% e "1.0" a todos; a decisão do span pai é respeitada. O padrão é "0.01". Para um diagnóstico breve, você pode usar "1.0" temporariamente.

Recarregue a configuração local do serviço. O exportador aplica as alterações sem reiniciar o processo:

sudo systemctl reload sapsan

Após executar operações cobertas por traces, abra http://127.0.0.1:16686, selecione o serviço sapsan e pesquise traces. A exportação ocorre em lotes, portanto eles aparecem com atraso.

Se o Sapsan estiver no Docker, 127.0.0.1 aponta para seu próprio contêiner. Conecte o Sapsan e o Jaeger à mesma rede Docker e use http://jaeger:4318/v1/traces, onde jaeger é o nome do contêiner receptor.

Compatibilidade com variáveis de ambiente¶

Se telemetry.otlp estiver ausente, o Sapsan aceita OTEL_ENDPOINT e 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

A seção telemetry.otlp tem prioridade sobre essas variáveis. Sem a seção nem OTEL_ENDPOINT, a exportação fica desativada; os logs JSON continuam sendo escritos em stdout.