Escolha um sinal
Comece a investigar uma falha pelos problemas ou pelos logs. Use um trace disponível para examinar uma execução. Use a tendência de uma métrica para examinar o período mais amplo. Para atividade e retenção, leia Análise de produto.
Capture apenas os campos de que uma investigação precisa. Use nomes estáveis de serviço, operação e métrica. Não envie credenciais, dados de pagamento nem corpos brutos de requisição. O guia de captura segura apresenta os controles.
Logs
Um log é uma entrada que a aplicação grava em um momento específico. Um log útil tem:- O horário do evento na origem.
- Uma gravidade canônica.
- O escopo de projeto e de serviço.
- O ambiente e a versão.
- Os identificadores de trace e de span, quando o log tem contexto de trace ativo.
- Atributos pequenos e nomeados, com o contexto do evento.
occurred_at, severity, project_id, service_name, environment, release, trace_id, span_id e attributes. Coloque o contexto em atributos nomeados, não no texto da mensagem.
Logs de vários serviços na mesma visualização não têm, só por isso, uma relação de trace. Só o contexto de trace cria essa relação.
Traces
Um trace contém os spans de uma requisição ou operação. Um span raiz não tem pai. Um span filho identifica o pai dele. Todos os spans de um trace têm o mesmo ID de trace e IDs de span diferentes. Veja Trace distribuído. Um log, problema, ação ou métrica enviado sem contexto de trace ativo recebe um trace de captura. Esse trace contém só spans de captura. Ele não mostra o caminho de uma requisição. Veja Spans de captura.Métricas
Uma métrica registra um valor medido ao longo do tempo. Leia cada métrica com o nome, a unidade, as dimensões, o projeto, o período e o intervalo dela. O LogBrew escolhe ovalue de cada ponto a partir do kind e da temporality da métrica:
Por exemplo, três amostras de um contador delta com os valores
2, 3 e 5 no mesmo intervalo resultam em um ponto com value igual a 10 e sample_count igual a 3. Três amostras de gauge com os mesmos valores, nessa ordem, resultam em um ponto com value igual a 5. Um valor p95 não é uma média. Cerca de 95% das observações registradas ficam nesse valor ou abaixo dele.
Com status: "ready", a agregação derivada está disponível. Com status: "limited", leia aggregation.limitation e use apenas os valores brutos. Não some um gauge nem um fluxo cumulativo. Um intervalo sem ponto não é um zero medido. Para os campos de consulta, leia Filtros de consulta.
GET /api/telemetry/metrics/series retorna esses pontos. Ele exige project_id, name e since. Cada série tem uma identity com kind, unit e temporality. Séries com identidades diferentes ficam separadas. Cada ponto também pode conter:
coverage.truncated é true quando series_limit deixou de fora séries de menor volume. Para comparar um período de uma métrica com o período anterior de mesma duração, execute:
Problemas
Um problema agrupa falhas repetidas por um fingerprint estável. Ele tem gravidade, status, contagem de ocorrências, horário da primeira ocorrência e horário da última ocorrência. Os detalhes do problema podem trazer também cadeias de exceções, frames da pilha, breadcrumbs, logs relacionados e uma relação de trace.last_seen_at é a ocorrência mais recente do grupo. A ocorrência que você seleciona pode ser mais antiga. Leia os dois horários.
O status de um problema é unresolved, resolved ou archived. A versão 1 da resposta da API mostra archived como ignored. As versões 2 e 3 da resposta adicionam priority (high, medium ou low) e priority_source. A versão 3 também adiciona assignee. Veja Valores de status e Prioridade.
Ações
Uma ação registra a atividade de produto. Uma classificação compatível marca a ação como visualização de página, visualização de tela ou interação. O nome do evento sozinho não define a classificação. Use a Captura de eventos de produto para adicionar esse contexto. Sessões não são usuários. Identidades anônimas não são usuários identificados.Valores de gravidade
O LogBrew aceita os aliases na entrada com qualquer combinação de maiúsculas e minúsculas. A API, a CLI e os eventos ao vivo usam os valores canônicos. Valores de gravidade desconhecidos são rejeitados. A gravidade é a urgência registrada. Ela não mostra o impacto no negócio nem a causa raiz.
Um usuário pode mudar a gravidade exibida de um problema ou de um log. Nesse caso, a resposta contém um objeto
triage com effective_severity. O campo severity mantém o valor capturado.
Leituras ao vivo e snapshots
logbrew read retorna um snapshot do projeto, do período e dos filtros selecionados. Execute o comando de novo para ler eventos novos. logbrew watch transmite novos logs, problemas e ações enquanto a conexão estiver aberta. Ele não transmite traces nem métricas. Uma falha de conexão não mostra que o projeto está vazio.
Estados das evidências
As respostas mantêm estes estados separados: capturado, não capturado, ocultado, truncado e indisponível. As evidências de trace têm quatro estados:available, not_linked, not_found e unavailable. Veja a visão geral para saber o que cada um significa, e Limites das evidências para os campos de cobertura. Um SDK mais novo não adiciona campos a eventos que ele enviou antes.
Investigue um projeto
1
Encontre os problemas não resolvidos
2
Leia um problema
Este comando lê o histórico retido do problema. O filtro
--since da lista não se aplica.3
Abra um trace disponível
Use o ID de trace somente quando a ocorrência selecionada retornar um.
4
Leia as evidências relacionadas
Filtre logs, ações e métricas pelo mesmo projeto, serviço, ambiente e versão. Não ligue sinais apenas pelo horário.