Quando um time decide “medir para melhorar”, o primeiro risco não é escolher a métrica errada: é medir com dados ruins. Dados de medição são o combustível de qualquer indicador de processo. Se o combustível estiver contaminado (eventos incompletos, timestamps inconsistentes, nomes ambíguos, duplicidades), o painel pode até parecer sofisticado, mas as decisões serão frágeis. Este capítulo trata de como garantir qualidade dos dados de medição e como padronizar eventos para que métricas diferentes sejam comparáveis, auditáveis e úteis ao longo do tempo.
O que significa qualidade dos dados de medição
Qualidade dos dados de medição é o grau em que os dados coletados representam fielmente o que aconteceu no processo, com consistência suficiente para permitir análises repetíveis. Em termos práticos, é a capacidade de responder perguntas como: “Esse evento realmente ocorreu?”, “O horário está correto?”, “Consigo relacionar este evento a um item de trabalho?”, “Se eu rodar a mesma consulta amanhã, obtenho o mesmo resultado para o mesmo período?”
Em medições de engenharia de software, os dados geralmente vêm de eventos: criação de um ticket, mudança de status, abertura de pull request, merge, deploy, alerta, incidente, etc. Cada evento é um registro que descreve algo que aconteceu em um ponto do fluxo. A qualidade do dado depende tanto do evento em si quanto do contexto: quem gerou, quando, com quais campos, e com qual significado.
Dimensões práticas de qualidade
- Completude: eventos esperados existem? Campos obrigatórios estão preenchidos? Ex.: todo deploy tem um identificador de versão e ambiente.
- Consistência: o mesmo conceito é registrado do mesmo jeito em sistemas diferentes. Ex.: “production”, “prod” e “PRD” não podem coexistir sem mapeamento.
- Unicidade: não há duplicatas do mesmo evento (ou há uma regra clara de deduplicação). Ex.: webhooks reentregues não devem inflar contagens.
- Validade: valores respeitam formatos e domínios. Ex.: timestamps em ISO-8601, ambiente em lista controlada.
- Acurácia: o valor corresponde ao fato real. Ex.: horário do deploy deve refletir quando a mudança ficou ativa, não quando o pipeline começou.
- Atualidade: eventos chegam com atraso aceitável. Ex.: logs de deploy chegando horas depois distorcem análises por dia.
- Rastreabilidade: consigo ligar eventos ao item de trabalho, ao repositório, ao serviço e ao time responsável.
- Interpretabilidade: o significado do evento e dos campos é claro e documentado (sem “campo_1”, “tipo=3”).
Por que padronizar eventos (e não apenas “limpar dados”)
Limpeza de dados é reativa: corrige sintomas depois que o dado já foi coletado. Padronização de eventos é preventiva: define como os eventos devem ser gerados e registrados para reduzir ambiguidade e retrabalho analítico.
Sem padronização, cada ferramenta e cada time cria seus próprios “dialetos”: nomes de status diferentes, timestamps com fusos variados, IDs que não se conversam, eventos que representam coisas distintas com o mesmo nome. O resultado é que a mesma métrica muda de significado quando você muda de squad, sistema ou período.
Continue em nosso aplicativo
Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.
ou continue lendo abaixo...
Baixar o aplicativo
Padronizar eventos significa estabelecer um contrato: um conjunto de tipos de evento, campos obrigatórios, formatos e regras semânticas. Esse contrato permite que indicadores sejam calculados com confiança e que comparações ao longo do tempo sejam justas.
Erros comuns que degradam métricas
1) Timestamps inconsistentes
Problemas típicos: alguns eventos em UTC, outros em horário local; timestamps de criação vs. atualização; horário do cliente (browser) em vez do servidor; relógios de máquinas desalinhados.
Sintoma: eventos “no futuro”, durações negativas, picos artificiais em viradas de dia.
2) Eventos com semântica ambígua
Um exemplo comum é “deploy_started” significar “pipeline iniciou” em um serviço e “mudança ativa em produção” em outro. O nome é igual, mas o significado é diferente.
Sintoma: comparações entre serviços ficam incoerentes; análises de tempo entre etapas variam sem explicação.
3) Duplicidade por reentrega
Webhooks e filas podem reenviar eventos. Se não houver idempotência, o mesmo deploy vira dois registros.
Sintoma: contagens infladas, taxas acima de 100%, “explosões” em gráficos.
4) Falta de chaves de correlação
Sem um identificador comum (ex.: change_id), você não consegue ligar PR → build → deploy → incidente. A análise vira “ilhas” de dados.
Sintoma: métricas só existem por ferramenta, não por fluxo.
5) Campos livres demais
Campos de texto livre para “ambiente”, “serviço” ou “tipo” geram variações infinitas (“Prod”, “produção”, “production”).
Sintoma: necessidade constante de tabelas de mapeamento e regras ad hoc.
Modelo mental: evento como contrato
Pense em cada evento como uma mensagem que precisa ser entendida por pessoas e por máquinas. Um bom contrato de evento define:
- Nome do evento (tipo): o que aconteceu.
- Momento do evento: qual instante ele representa (início, fim, efetivação).
- Entidade afetada: qual item de trabalho, mudança, serviço, ambiente.
- Contexto: time, repositório, pipeline, origem.
- Versão do esquema: para evoluir sem quebrar consumidores.
Esse contrato deve ser explícito e verificável. Verificável significa que você consegue validar automaticamente se um evento está conforme o esquema e rejeitar (ou marcar) eventos inválidos.
Passo a passo prático para padronizar eventos
Passo 1: inventariar fontes e eventos atuais
Liste as fontes de dados que geram eventos de medição: issue tracker, repositórios, CI/CD, observabilidade, service desk, etc. Para cada fonte, identifique:
- Quais eventos existem (ex.: “issue_created”, “pr_merged”, “deployment_finished”).
- Quais campos vêm em cada evento.
- Como os timestamps são gerados e em qual fuso.
- Quais IDs existem e se há como correlacionar com outras fontes.
Uma forma prática é extrair uma amostra de 1 a 2 semanas de eventos e montar uma tabela com colunas: event_type, source, timestamp, id, payload.
Passo 2: definir um vocabulário controlado (taxonomia)
Crie uma lista curta e controlada de tipos de evento que representem o fluxo de ponta a ponta. Evite granularidade excessiva no início. O objetivo é padronizar o essencial.
Exemplo de taxonomia mínima (ilustrativa):
- work_item_created
- work_item_status_changed
- change_created (ex.: PR aberto)
- change_merged
- build_finished
- deployment_started
- deployment_finished
- incident_opened
- incident_resolved
Para cada tipo, escreva uma definição semântica de 2 a 4 linhas: o que é, quando deve ser emitido, e o que não é. Isso reduz “interpretações criativas”.
Passo 3: definir o esquema de evento (campos obrigatórios e opcionais)
Padronize um envelope comum para todos os eventos, com campos obrigatórios. Um exemplo de esquema conceitual:
{ "event_id": "uuid", "event_type": "deployment_finished", "event_version": 1, "occurred_at": "2026-01-13T10:15:30Z", "emitted_at": "2026-01-13T10:15:31Z", "source": { "system": "cicd", "name": "pipeline-x" }, "actor": { "type": "user|system", "id": "..." }, "entity": { "type": "change|work_item|incident", "id": "..." }, "correlation": { "change_id": "...", "work_item_id": "..." }, "service": { "name": "checkout", "team": "payments" }, "environment": "prod", "attributes": { "...": "..." }}Pontos importantes:
- event_id deve permitir deduplicação (UUID ou hash determinístico).
- occurred_at representa quando o fato aconteceu; emitted_at quando o evento foi publicado. Essa separação ajuda a lidar com atrasos.
- event_version permite evoluir o payload sem quebrar consumidores.
- environment deve ser lista controlada (ex.: dev, staging, prod).
Passo 4: estabelecer regras de timestamp e fuso horário
Defina regras simples e rígidas:
- Todos os timestamps em UTC.
- Formato ISO-8601 com “Z” (ex.: 2026-01-13T10:15:30Z).
- occurred_at deve ser o instante do evento no mundo real (ex.: deploy efetivado), não o início de uma cadeia de automação, a menos que o tipo de evento seja explicitamente “started”.
- Se o sistema fonte não fornece o instante correto, registre isso como limitação e, se possível, gere o evento no ponto certo (ex.: após health check de rollout).
Passo 5: definir chaves de correlação e estratégia de identidade
Padronização falha quando cada sistema usa um identificador diferente sem ponte. Defina um conjunto mínimo de IDs para correlacionar:
- work_item_id: ID do item de trabalho (ou equivalente).
- change_id: ID da mudança (PR, merge commit, release).
- deployment_id: ID do deploy (execução do pipeline ou rollout).
- incident_id: ID do incidente.
Regras práticas:
- Se o item de trabalho é a origem, propague work_item_id para branch, PR, commits (ex.: no nome da branch ou no título do PR com padrão validável).
- Se a mudança é a origem, garanta que o deploy carregue change_id e, quando possível, o mapeamento para work_item_id.
- Evite depender apenas de texto livre (ex.: “JIRA-123” no comentário). Prefira campos estruturados ou validações automáticas.
Passo 6: normalizar valores categóricos (dicionários)
Crie dicionários para campos que costumam virar caos:
- environment: dev, test, staging, prod.
- result: success, failure, canceled.
- severity (incidentes): sev1, sev2, sev3, sev4.
- service.name: nomes canônicos de serviços.
Quando a fonte enviar “Production”, transforme para “prod” no pipeline de ingestão. Registre a regra de normalização e mantenha-a versionada.
Passo 7: implementar validação automática (quality gates de dados)
Trate dados como código: valide antes de aceitar. Exemplos de validações:
- Esquema: campos obrigatórios presentes; tipos corretos.
- Domínio: environment pertence à lista; severity válida.
- Temporal: occurred_at não pode ser maior que emitted_at por mais de X minutos (tolerância); não pode estar no futuro além de uma margem.
- Unicidade: event_id não pode repetir; ou regra de idempotência por (source, entity.id, occurred_at, event_type).
Eventos inválidos podem seguir três caminhos: rejeitar, armazenar em “quarentena” para correção, ou aceitar com flag de qualidade (ex.: data_quality_status=invalid) para não contaminar indicadores oficiais.
Passo 8: monitorar a qualidade dos dados como uma métrica em si
Crie indicadores operacionais de qualidade do dado. Exemplos:
- % de eventos válidos por fonte e por tipo.
- % de eventos sem correlação (ex.: deploy sem change_id).
- Atraso de ingestão: emitted_at - occurred_at (p50/p95).
- Taxa de duplicidade detectada por janela de tempo.
- Cardinalidade inesperada em campos categóricos (ex.: surgiram 15 valores novos de environment).
Esses indicadores ajudam a detectar regressões quando alguém muda um webhook, altera um pipeline ou renomeia um serviço.
Padronização de eventos na prática: exemplo de deploy
Suponha que você queira medir eventos de deploy de forma consistente. Sem padrão, um time registra “deploy” quando o job inicia; outro registra quando termina; um terceiro registra quando o tráfego é migrado. Para padronizar:
- Defina dois eventos: deployment_started e deployment_finished.
- Defina que deployment_finished ocorre quando a versão está ativa e passou em um critério mínimo (ex.: health check).
- Campos obrigatórios: deployment_id, service.name, environment, result, occurred_at, change_id.
Exemplo de evento finalizado:
{ "event_id": "2f1f0f2c-8f7e-4d7a-9c1a-9b2c8b1a1d11", "event_type": "deployment_finished", "event_version": 1, "occurred_at": "2026-01-13T10:22:10Z", "emitted_at": "2026-01-13T10:22:12Z", "source": { "system": "cicd", "name": "github-actions" }, "entity": { "type": "deployment", "id": "run-88421" }, "correlation": { "change_id": "pr-1938", "work_item_id": "WI-1042" }, "service": { "name": "checkout", "team": "payments" }, "environment": "prod", "attributes": { "result": "success", "duration_seconds": 420, "strategy": "rolling" }}Com isso, qualquer análise que dependa de deploys (contagem, falhas, janelas de mudança) passa a ter base consistente. Se um time usa outra ferramenta de CI/CD, ele ainda emite o mesmo contrato de evento, mudando apenas source e alguns attributes.
Tratamento de casos difíceis (edge cases)
Eventos tardios e reprocessamento
Alguns sistemas enviam eventos com atraso. Se você agrega por dia, um deploy de ontem pode “aparecer” hoje e bagunçar séries históricas. Estratégias:
- Use occurred_at para agregações e mantenha emitted_at para monitorar atraso.
- Implemente janelas de reprocessamento (ex.: recalcular últimos 3 dias diariamente).
- Versione resultados de agregação (tabelas “snapshot”) para auditoria.
Eventos duplicados por idempotência fraca
Se a fonte não garante entrega única, deduplicate no consumidor:
- Defina event_id determinístico (hash de campos estáveis) quando possível.
- Se não for possível, use chave composta (event_type + entity.id + occurred_at arredondado + source).
- Registre contagem de duplicatas para atacar a causa.
Mudanças de nomenclatura e reorganização de times/serviços
Serviços mudam de nome e times reorganizam ownership. Se você gravar apenas “team=Squad A”, séries históricas quebram. Boas práticas:
- Use identificadores estáveis (ex.: service_id) e mantenha nomes como atributos mutáveis.
- Guarde histórico de ownership em uma dimensão (tabela de vigência) para análises por período.
Documentação mínima: catálogo de eventos
Padronização sem documentação vira “conhecimento tribal”. Mantenha um catálogo de eventos com:
- Lista de event_type e descrição.
- Campos obrigatórios/opcionais e exemplos.
- Regras de timestamp (o que significa occurred_at).
- Regras de correlação (quais IDs devem existir).
- Regras de normalização (dicionários).
- Versionamento do esquema e política de depreciação.
Esse catálogo deve ser usado como referência para quem instrumenta sistemas e para quem consome dados em análises.
Checklist de implementação rápida
- Definir 8–12 tipos de evento essenciais e suas definições semânticas.
- Padronizar envelope com event_id, event_type, event_version, occurred_at, emitted_at, source, entity, correlation, service, environment.
- UTC + ISO-8601 para todos os timestamps.
- Lista controlada para environment, result, severity e nomes canônicos de serviço.
- Validação automática de esquema e domínios na ingestão.
- Deduplicação e monitoramento de duplicatas.
- Métricas de qualidade do dado (validade, atraso, correlação ausente).
- Catálogo de eventos versionado e acessível.
