Elysia Tools
Navegação
Workflow Playbook
Levante atributos antigos, migre convenções semânticas, valide a propagação e examine um trace real antes de publicar mudanças de instrumentação.
Temas
Este roteiro atende quem mantém um serviço e planeja atualizar as convenções semânticas do OpenTelemetry; não substitui a investigação de um incidente. Separe um log anterior à mudança, a configuração da instrumentação ou do Collector e uma requisição que atravesse pelo menos dois serviços. Remova dados pessoais e segredos antes de compartilhar amostras. structured-log-analyzer revela os atributos existentes. Se o log estiver em logfmt, logfmt-to-json-structured-log-bridge ajuda a expor valores entre aspas, conversões de tipo e chaves duplicadas. JSON já estruturado não precisa desse passo. Para uma revisão abrangente de informações sensíveis, use pii-log-redaction.
Execute otel-semantic-convention-migration-tool sobre uma cópia do código, das regras do Collector ou das consultas de painéis. Guarde as versões de origem e destino, os mapeamentos propostos, os atributos removidos e os casos sem mapeamento. O resultado é uma proposta, não uma implantação automática. http.target pode exigir a separação deliberada entre caminho e consulta, em vez de uma troca literal de nome. Resolva esses casos com os responsáveis e publique somente a alteração revisada. Verifique também os painéis, pois o número de campos renomeados não identifica consultas que ainda dependem dos nomes antigos.
Passe exemplos de traceparent, tracestate, baggage e cabeçalhos OTLP para opentelemetry-w3c-traceparent-tracestate-baggage-and-otlp-protobuf-headers-propagation-validator. A passagem seguinte deve conservar o identificador do trace e usar um identificador de span diferente. Cabeçalhos corretos não demonstram que os spans foram exportados. Por isso, analise uma exportação posterior com distributed-trace-decoder-waterfall-visualizer. Compare a sequência de serviços, a relação entre pais e filhos, os erros e as durações. Anote spans faltantes em vez de presumir que foram produzidos.
Se houver uma meta de latência, use api-latency-budget-planner para confrontar os tempos observados com as parcelas por etapa. Um único trace sugere onde o tempo foi gasto, mas não mede o P99. A aprovação deve registrar versões, diferenças de atributos, validação de cabeçalhos, evidência do trace e pendências. Para diagnóstico de incidente ou repetição de requisição de API, siga observability-debugging ou api-request-replay-and-debugging, respectivamente.
Guia de fluxo de trabalho
Analise um exemplo de log anterior à mudança e sem dados sensíveis. Converta logfmt em JSON somente para esclarecer aspas e chaves duplicadas.
Reescreva atributos suportados a partir da v1.20, examine o diff e separe campos removidos ou não mapeados para decisão manual.
Confira traceparent, tracestate, baggage e cabeçalhos OTLP em uma passagem representativa, preservando o trace e alterando o span.
Decodifique uma exportação JSON OTel, Jaeger ou Zipkin posterior e compare serviços, relações, erros e duração com a rota esperada.
Converta logfmt quando aspas ou chaves duplicadas ocultarem campos; analise diretamente um JSON com atributos tipados.
Revise atributos removidos ou não mapeados, como http.target, antes de aplicar regras no Collector.
Valide cabeçalhos para o contexto, o trace exportado para spans realmente conectados e o orçamento apenas quando houver meta.
Quando houver meta, compare durações de spans com os limites combinados para cada etapa e registre qualquer excesso.