O log está em logfmt ou já é JSON estruturado?
Converta logfmt quando aspas ou chaves duplicadas ocultarem campos; analise diretamente um JSON com atributos tipados.
Elysia Tools
Navegação
Guia de fluxo de trabalho
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.
Novo neste fluxo? Siga os passos em ordem, começando pela primeira ferramenta abaixo. Já sabe o que precisa? Vá direto ao passo correspondente: todas as ferramentas deste fluxo estão na tabela comparativa.
Primeira ferramenta: Analisador de logs estruturados
Temas
| Ferramenta | O que faz | Categoria |
|---|---|---|
| Analisador de logs estruturados | Detecta formatos comuns de logs, extrai campos principais e exporta em JSON, CSV ou SQL. | Processamento de dados |
| Ponte logfmt ↔ JSON para logs estruturados | Converte logfmt (chave=valor) para JSON ou JSON para logfmt, com escape de aspas, coerção de números/booleanos e tratamento de chaves duplicadas. | Conversão de formatos |
| Ferramenta de Migração de Atributos Semantic-Convention v1.20 → v1.27 do OpenTelemetry | Reescreve nomes de atributos de spans/logs entre versões de convenções semânticas do OpenTelemetry: http.method → http.request.method, http.status_code → http.response.status_code, http.url → url.full, db.system → db.system.name, messaging.destination → messaging.destination.name e 25+ outros — aplicado a código JS/TS/Python/Go/Java/.NET colado, YAML do collector ou JSON de dashboards Grafana, com mapa de renomes do collector, avisos de remoção/divisão manual, estatísticas de diff por atributo e relatório de atributos não mapeados. |
Temas
| Desenvolvimento |
| Validador de propagação OpenTelemetry W3C traceparent / tracestate / baggage e cabeçalhos OTLP | Valida traceparent pela ABNF do W3C Trace Context (versão / trace-id de 16 bytes / parent-id de 8 bytes / trace-flags de 1 byte; zeros e versão ff rejeitados, maiúsculas avisadas), tracestate (≤32 membros, chaves simples e tenant@sistema, duplicatas avisadas) e baggage (valores percent-encoded com propriedades opacas); verifica o Content-Type de exportação OTLP e o contexto binário de 25 bytes do grpc-trace-context-bin; correlaciona dois traceparent num round-trip simulado (estabilidade do trace-id e colisão de um span-id filho aleatório) e emite cabeçalhos normalizados. | Desenvolvimento |
| Decodificador de trace distribuido e waterfall | Analisa JSON de Jaeger, Zipkin ou OpenTelemetry e mostra spans, duracao e erros em waterfall | Desenvolvimento |
| Planejador de orçamento de latência de API | Planeje e visualize um orçamento de latência de API. Insira um alvo P99 (ex. ≤ 300ms) e a alocação por estágio (DNS, TCP, TLS, TTFB, Processing, Network) para ver um waterfall ao vivo, a utilização do orçamento e alertas de excesso. Opcionalmente cole um trace OpenTelemetry ou Datadog para deduzir uma alocação medida. | Desenvolvimento |
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. A migração substitui texto mapeado, não interpreta a aplicação. Revise o contexto; mudar uma cadeia não prova migração da instrumentação ou dos painéis.
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. A verificação cobre cabeçalhos informados e pode mostrar spans filhos simulados. Correlação sintética não prova propagação em serviços. Compare dois cabeçalhos higienizados e exija separadamente um rastreamento conectado.
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.
A verificação cobre cabeçalhos informados e pode mostrar spans filhos simulados. Correlação sintética não prova propagação em serviços. Compare dois cabeçalhos higienizados e exija separadamente um rastreamento conectado.
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.