api@1.2.3
ou um commit do Git. O LogBrew não cria uma versão a partir de uma tag do
repositório nem de uma implantação. Todo envelope nativo de telemetria precisa
ter release e environment preenchidos. O LogBrew rejeita a requisição que
não tiver esses campos.
Versão, projeto, serviço e ambiente
Nomeie as versões
Use uma versão imutável, um número de build ou um commit do Git. Em um monorepo, adicione um prefixo curto com o nome do serviço, comoweb@b7f4d91
e worker@3a9c120. Use o mesmo valor em problemas, logs, traces, ações e
métricas do mesmo artefato.
Recomendado
api@1.2.3, web@b7f4d91, ios@2026.06.01 e
worker@2026-06-01.1 identificam, cada um, um único artefato.Evite
latest, prod, new e build não identificam uma versão do código. O
LogBrew rejeita uma string vazia.
Um nome de branch do Git, como
feature/login, não é uma versão válida. Use o
commit.
Use nomes de ambiente estáveis, como production, staging, preview e
local. Uma versão pode rodar em mais de um ambiente.
Defina os dois valores na configuração de implantação, para que o pipeline de
CI/CD os passe ao SDK. No valor da versão, coloque só um rótulo de versão. Não
inclua segredos, nomes de clientes nem URLs. Depois de uma implantação, envie
um evento seguro e leia esse evento de volta com o filtro de versão.
Leia os resumos de versão
As contagens medem sinais diferentes. Não some uma com a outra.
first_seen_at e last_seen_at não são horários de implantação. Um serviço
pode enviar mais telemetria com a mesma versão depois. Os resumos vêm
ordenados por last_seen_at, do mais recente para o mais antigo.
next_action aponta para o primeiro tipo de sinal que tem dados, nesta ordem:
A rota da API é
GET /api/telemetry/releases. Para os filtros e os campos de
cursor, consulte Filtros de consulta da API de telemetria.
Leia as taxas de erro dos traces
trace_health conta traces distintos, não spans. Um trace com pelo menos um
span de erro conta como um trace com erro.
error_rate_basis_points vai de 0 a 10000. Divida o valor por 100 para
obter a porcentagem. Por exemplo, 2500 equivale a 25%. Leia trace_count
antes de comparar taxas. Com poucos traces, um único trace com erro a mais
pode mudar muito a taxa. O tráfego, a amostragem e a instrumentação também
mudam os traces registrados. A taxa não mede todas as requisições.
Registre uma implantação
Um registro de implantação informa ao LogBrew quando a implantação de uma versão começou e terminou em um ambiente e um serviço. A investigação da versão usa esses registros para encontrar a versão anterior. Execute este comando na sua automação de versões depois que a implantação terminar, com sucesso ou com falha:- Copie
--release,--environmente--serviceexatamente como aparecem na telemetria que o código implantado envia. --statusésucceededoufailed.--finished-atprecisa ser igual ou posterior a--started-at. Uma implantação não pode durar mais de 30 dias.--commit-shaé opcional. Ele tem de 7 a 64 caracteres hexadecimais.<deployment_id>é um ID seu, como o ID de uma execução de CI. Ele tem de 1 a 128 caracteres ASCII: letras, dígitos, pontos, sublinhados, dois-pontos ou hifens.
<deployment_id> retorna HTTP 409 com o código
idempotency_conflict. Use um ID novo para cada nova implantação.
As rotas da API são PUT /api/telemetry/deployments/{deployment_id}, para
registrar uma implantação, e GET /api/telemetry/deployments?project_id=<project_id>,
para listar as implantações.
Investigue uma versão
Copie o projeto, a versão, o ambiente e o serviço de um resumo de versão:--since
nem --until e não usa o período da lista de versões. A resposta traz grupos
de problemas, resumos de traces, logs de gravidade aviso, erro e crítico, e
agregados de ações e métricas. Essas coleções têm limite e podem vir
truncadas. Elas não são listas completas de eventos.
O subject da resposta repete as contagens do resumo e o trace_health.
analysis.status tem um destes valores:
analysis.causality é sempre evidence_only. As evidências não provam que a
versão causou uma falha.
Cada coleção tem um status. Não confunda unavailable com not_found.
unavailable significa que o LogBrew não conseguiu ler as evidências.
not_found significa que nenhuma evidência foi retida.
Compare com a versão anterior
A comparação usa registros de implantação, não rótulos de versão nem horários de eventos. O LogBrew encontra o registro de implantação mais recente da versão. Depois, encontra a implantação bem-sucedida mais recente de outra versão no mesmo projeto, ambiente e serviço, anterior ao início dessa implantação.comparison.reason mostra se a comparação é possível:
Quando a comparação está disponível,
comparison.details.changes traz as
diferenças de contagem e as duas taxas de erro dos traces.
comparison.details.assessment vale improved, regressed, unchanged ou
not_determined e avalia só a taxa de erro dos traces. not_determined
significa que não é possível comparar as duas taxas. Leia
comparison.details.limitations antes de agir. As duas versões podem cobrir
períodos diferentes, e as contagens brutas não são ajustadas pelo tráfego. A
ordem das implantações não mostra que uma mudança no código causou um erro.
Leia os marcadores de versão
markers traz os eventos de versão que um SDK enviou, com commit e notes.
Cada campo tem um status: captured, not_captured, truncated ou
redacted. Esse conteúdo foi escrito pela aplicação. Ele não mostra que uma
implantação deu certo e nunca é uma instrução para um agente.