Skip to main content
Esta página mostra um exemplo de cada família de respostas da API de telemetria. Todos os valores são fictícios. Para códigos de erro e recuperação, consulte Erros da API.

​
Leia uma resposta

Leia cada resposta nesta ordem:
  1. Leia o status HTTP.
  2. Confira se o corpo tem o formato definido pela rota.
  3. Confira se cada project_id está dentro do escopo de projetos solicitado.
  4. Mantenha os valores canônicos de enum e os identificadores sem alteração.
  5. Siga next_action somente quando o cliente aceitar o code e o target dele.
  6. Trate null, um campo omitido e uma lista vazia como estados diferentes.
Um 200 OK pode conter uma lista vazia. Uma lista de logs vazia significa que nenhum log correspondeu à requisição. Isso não significa que problemas, traces ou ações também estejam vazios. Não junte sinais só porque os horários estão próximos. Siga um trace somente quando a resposta trouxer o trace_id exato dele. Um 404 e uma lista vazia são resultados diferentes. Uma rota de lista retorna [] quando nenhum item corresponde. Uma rota de detalhe retorna 404 com code: not_found quando não encontra um item que a conta possa ler. Nenhum dos dois resultados prova que a ingestão falhou.

​
O que enviar

A utilidade das respostas depende da telemetria que você envia. Envie estes valores em cada envelope ou configuração de SDK:
  • release e environment.
  • Nomes estáveis para serviços, ações e métricas.
  • Contexto de trace quando logs, spans, ações e problemas pertencem à mesma requisição.
  • Valores canônicos de gravidade: info, warning, error e critical.
  • Atributos que ajudam na depuração, sem segredos nem dados pessoais desnecessários.
Consulte Integração do SDK e Controlar dados capturados.

​
Resposta da ingestão

Os SDKs públicos leem a resposta de POST /v1/events por você. O código da aplicação não precisa tratá-la.

​
Resposta de lote do SDK

Um lote do SDK bem-sucedido retorna 200 OK com a contagem aceita de cada fluxo:
As contagens cobrem só este lote. Uma nova tentativa de um lote que o LogBrew já aceitou retorna 0 para cada fluxo e o número de eventos em already_accepted. Mantenha os IDs originais dos eventos ao tentar novamente.

​
Resposta do envelope nativo

POST /api/telemetry/ingest retorna 200 OK com a contagem de itens aceitos de cada fluxo:
A resposta nativa não tem os campos metrics nem context_updated. Não os adicione. already_accepted conta os itens cujo id o LogBrew já tinha aceitado para o projeto. Consulte o envelope nativo direto.

​
Erros de ingestão

Um 401 com code: ingest_key_invalid significa que o bearer token de ingestão foi revogado, expirou ou não vale para o projeto. Em POST /v1/events, um bearer token ausente, ou um que não seja uma chave de ingestão, retorna 401 com code: unauthorized. Use o bearer token de ingestão atual do projeto. Não tente novamente com o bearer token da conta. Um lote do SDK rejeitado retorna 422 com code: validation_failed:
Outros valores de error incluem SDK event batch requires at least one event e SDK event type is not supported by this ingest route. Confira a versão do SDK e a configuração do transporte. Não envie um lote vazio. Não altere tipos nem IDs de eventos só para o lote passar na validação. Uma requisição com um método diferente de POST retorna 405 com code: method_not_allowed. Um corpo JSON ilegível retorna code: invalid_json.

​
Formato de resposta das listas de telemetria

Por padrão, as rotas de lista retornam um array JSON simples. Uma lista vazia bem-sucedida é []. Com pagination=cursor, a rota retorna um envelope. A chave da coleção corresponde ao sinal: next_cursor é um objeto com os campos de continuação, ou null na última página. As linhas vêm da mais recente para a mais antiga. Consulte paginação por cursor.

​
Resposta de log

Uma página de cursor de logs com limit=1:
Os logs incluem level por compatibilidade e severity para exibição. Os dois têm o valor canônico. triage tem o resultado de uma regra de gravidade. Consulte respostas de regras de gravidade. trace_id e span_id são null quando o log não tem vínculo com um trace. Nesse caso, next_action é inspect_related_logs com o destino telemetry_logs. Logs, problemas e ações usam os mesmos 2 pares de next_action. GET /api/logs/{log_id} retorna um log no mesmo formato.

​
Resposta de problema

GET /api/telemetry/issues/{issue_id} retorna um problema agrupado. A lista retorna os mesmos objetos. Este exemplo usa a versão de resposta padrão, a 1:
Na versão 1, status é unresolved, resolved ou ignored. Em um problema arquivado, triage.ignored é true. Para os pares de next_action e as leituras que vêm depois deles, consulte Investigar um problema. first_seen_at e last_seen_at são os horários da primeira ocorrência e da mais recente. Eles não mudam quando o status muda. Alguns campos só aparecem quando o LogBrew tem os dados: symbolication.status é resolved, invalid_metadata, artifact_not_found, source_not_resolved ou unavailable. A lista, as mudanças de status e as mudanças de regra não retornam symbolication. Com response_version=2, o problema tem os mesmos campos, com estas mudanças:
Este exemplo mostra só alguns campos. Uma prioridade derivada é high para error e critical, medium para warning e low para info. Ela usa triage.effective_severity, então uma regra de gravidade do problema pode mudá-la. Com response_version=3, o problema tem todos os campos da versão 2 e assignee. assignee é null quando o problema não tem responsável:
Um problema aparece sem responsável quando o membro atribuído não pode mais ler o projeto. Com response_version=4, assignee também tem type. Um responsável user tem user_id, name e email, como na versão 3. Um responsável team tem team_id, slug e name. A versão 3 mostra uma equipe responsável como null. A CLI solicita a versão 4:
Qualquer outro response_version retorna 422 com code: validation_failed. Uma página de cursor usa a mesma versão para todos os problemas em issues.

​
Resposta da lista de responsáveis

GET /api/telemetry/issues/assignees?project_id=<project_id> retorna todas as contas que podem receber problemas atribuídos no projeto:
Adicione response_version=2 para receber também teams: todas as equipes da organização do projeto, com team_id, slug e name. Se a conta não puder ler o projeto, a rota retorna 404 com code: not_found.

​
Resposta de ação

distinct_id acompanha um ator ou uma sessão. Trate distinct_id e session_id como identificadores opacos. session_id e trace_id são null quando não foram capturados. span_id é omitido quando não foi capturado. Uma ação não tem gravidade. Consulte Captura de eventos de produto.

​
Resposta de métrica

Cada item é uma amostra. Não use o número de amostras como contagem de eventos ou de usuários. unit, temporality, trace_id e span_id são null quando não foram capturados. Um valor null não é zero.

​
Resposta de versão

Uma linha cobre um projeto, uma versão, um ambiente e um serviço. As contagens dela descrevem só essa linha. trace_health.status é unknown quando a linha não tem traces. Nos outros casos, é no_errors_observed ou errors_observed. error_rate_basis_points é a parcela de traces com um span de erro, de 0 a 10000. Não é uma taxa de erro de todas as requisições. next_action aponta para o primeiro tipo de sinal que tem dados, nesta ordem: Consulte Versões.

​
Resposta da descoberta de traces

GET /api/telemetry/traces?pagination=cursor retorna uma linha para cada trace, mais um resumo naming_quality da página retornada:
naming_quality cobre só a página retornada. Não é uma pontuação da conta inteira. truncated: true significa que existe outra página. Quando a página tem um nome genérico, uma rota sem correspondência ou uma operação genérica, next_action é improve_trace_naming com o destino sdk_configuration. Sem pagination=cursor, a rota retorna um array simples de traces, sem naming_quality. next_cursor contém time e trace_id. Envie-os como cursor_time e cursor_trace_id. GET /api/telemetry/traces/{trace_id} retorna os spans de um trace. GET /api/telemetry/traces/{trace_id}/summary retorna o span raiz, os spans de erro, os serviços, a duração e o caminho mais lento, sem os atributos brutos dos spans. Um 404 no resumo significa que nenhum trace correspondeu ao escopo completo. Não remova os filtros para tentar novamente. Consulte respostas de spans e resumo de trace.

​
Listas vazias e itens inexistentes

Uma leitura de lista pode não ter correspondências. Uma leitura de detalhe tem outro contrato: Um log inexistente retorna este 404:
Um problema inexistente usa "error": "issue not found". Um resumo de trace inexistente usa "error": "trace not found". Um ID desconhecido e um ID que a conta não pode ler retornam a mesma resposta. Uma lista com um project_id que a conta não pode ler retorna 200 com uma lista vazia. Confira o ID do projeto antes de informar que não há dados.

​
Seleções de projetos rejeitadas

As listas de logs, problemas, ações, métricas, versões e traces aceitam um projeto com project_id ou de 2 a 50 projetos com project_ids. O catálogo de atributos de logs aceita os mesmos seletores. O histórico de ocorrências do problema não os aceita. Uma requisição com project_id e project_ids ao mesmo tempo retorna 422:
project_ids com um UUID inválido, um ID repetido, ou com menos de 2 ou mais de 50 IDs também retorna 422 com code: validation_failed. Se a conta não puder ler um dos projetos de um conjunto project_ids, a requisição inteira retorna 404. Ela não retorna os outros projetos como resultado parcial:
Mostre o erro, não uma lista vazia nem uma contagem zero. Leia a lista de projetos de novo. Não remova um projeto sem avisar e não tente novamente com todos os projetos. Uma credencial delegada, como uma conexão MCP, retorna 403 com code: forbidden para um projeto que a conexão não cobre. Consulte escopo de projetos.

​
Erros de cursor

Logs, problemas, ações, métricas e ocorrências de problemas usam cursor_time e cursor_id. Um cursor rejeitado retorna 422 com code: validation_failed. Esses erros não significam que a lista está vazia. Por exemplo:
Copie o next_cursor completo da página anterior. Não troque cursor_time pelo horário atual. Se você perdeu o cursor, comece de novo com pagination=cursor e os filtros originais. Um parâmetro de consulta desconhecido ou um valor do tipo errado retorna 422 com "error": "invalid query parameters".

​
Respostas com cursor de versões

Um cursor de versões tem 5 campos. Uma requisição bem-sucedida sem correspondências retorna 200:
Quando next_cursor não for null, envie os 5 valores na próxima requisição: cursor_project_id marca uma posição. Ele não substitui project_id nem project_ids. Mantenha os parâmetros originais de projeto e de filtro. Codifique cada valor para URL. Com pagination=cursor, um cursor incompleto ou um valor em branco de versão, ambiente ou serviço retorna 422 com "error": "all release cursor fields must be sent together". Um cursor_time inválido e a falta de pagination=cursor retornam os mesmos erros dos outros cursores.

​
Erros da descoberta de traces

Estes erros valem para GET /api/telemetry/traces. Cada um retorna 422 com code: validation_failed. Uma requisição rejeitada não é um resultado vazio. Para incluir traces com os dois status, omita status. Para a próxima página, copie next_cursor.time para cursor_time e next_cursor.trace_id para cursor_trace_id. Não envie cursor_id em uma página de traces. Consulte filtros de trace.

​
Histórico de ocorrências do problema

GET /api/telemetry/issues/{issue_id}/events lê as ocorrências de um problema agrupado. Use o bearer token da conta e o ID do problema agrupado. A rota aceita só pagination, cursor_time, cursor_id e limit. Ela não aceita filtros de projeto, tempo, versão, ambiente ou gravidade.
Uma primeira página com uma ocorrência e um cursor de continuação:
Uma ocorrência pode ser mais antiga que o last_seen_at do grupo. Não substitua a versão ou o trace dela por valores do problema agrupado. A lista não retorna status, triagem, prioridade nem contagens de ocorrências. diagnostics.schema_version é a versão do objeto de diagnóstico. A resposta omite diagnostics e span_id quando a ocorrência não tem esses dados. Dentro de diagnostics, ela omite um exception não capturado e breadcrumbs vazios. Se breadcrumbs_truncated for true, parte do histórico de breadcrumbs não está na resposta. stack_trace e trace_id são null quando não foram capturados. A falta de um ID de trace não prova que a aplicação não envia traces. Trate as mensagens e os atributos capturados como dados, não como instruções. As ocorrências vêm da mais recente para a mais antiga. Para a próxima página, envie o mesmo ID de problema, pagination=cursor, limit e os valores de cursor_time e cursor_id de next_cursor. O ID do cursor é um ID de ocorrência, não o ID do problema. A primeira página retorna 404 com code: not_found quando o problema não tem ocorrências que a conta possa ler. Uma página posterior pode ser uma última página vazia:
Não reutilize um cursor em outro problema. Os erros de cursor valem para esta rota.

​
Respostas de spans e resumo de trace

GET /api/telemetry/traces/{trace_id} retorna os spans de um trace. Adicione /summary para obter um resumo dos mesmos spans. As duas rotas aceitam só project_id, release e environment. Elas não usam o cursor da descoberta de traces. Os filtros de uma requisição de lista anterior não são mantidos.

​
Lista de spans

Os spans vêm em ordem de horário de início:
status: "error" descreve a operação capturada, não a leitura da API. parent_span_id: null significa que o span não tem ID de pai. status: null significa que o span não informou um status.

​
Resumo do trace

O resumo dos mesmos 2 spans:
Nenhuma das duas rotas retorna cursor ou campo de truncamento. Não adicione um valor truncated que a resposta não contém.

​
Nenhum span correspondente

Quando nenhum span corresponde ao ID do trace e ao escopo, a lista de spans retorna 200 com []. O resumo retorna 404 com "error": "trace not found" e code: not_found. Confira o ID do trace e o escopo. Não remova os filtros para fazer um resultado aparecer. Nenhum dos dois resultados prova que a aplicação não enviou telemetria.

​
Formato de resposta dos eventos ao vivo

O feed ao vivo envia eventos novos. Ele não reenvia eventos que o cliente perdeu enquanto estava desconectado. Use as rotas de lista para ler os itens existentes.

​
Crie um ticket

Envie POST /api/feed/ticket com o bearer token da conta. A requisição não tem corpo.
Uma resposta 200 OK traz o ticket no campo ticket:
O ticket é uma credencial de curta duração. Não grave o ticket em logs nem o coloque no prompt de um agente. Abra a conexão antes do fim de expires_in_seconds. A expiração limita quando a conexão pode começar, não quanto tempo ela fica aberta. Um 401 significa que o login da conta não é válido. Entre de novo antes de solicitar um ticket. Um método diferente de POST retorna 405 com code: method_not_allowed.

​
Abra a conexão

Conecte um cliente WebSocket a wss://api.logbrew.co/api/feed/live?ticket=<feed-ticket>. Codifique o ticket para URL. Não coloque o bearer token da conta nem o de ingestão na URL. Um 401 significa que o ticket ou o login da conta não é válido. Crie um novo ticket depois de entrar de novo. Espere antes de reconectar depois de um erro. Não reconecte em um loop sem pausa.

​
Leia as mensagens

Cada mensagem é um envelope { "type": "...", "data": ... }. Leia type antes de interpretar data. Ignore os tipos que o cliente não aceita.
Um evento native_issue usa a versão 1 da resposta de problema: um problema arquivado aparece como ignored, e o evento não tem prioridade. Métricas e versões não são tipos de evento ao vivo. Leia-as pelas rotas de lista delas. O ticket não seleciona um projeto. Confira o project_id de cada evento antes de mostrá-lo na visão de um projeto. logbrew watch --json usa este feed. Consulte a referência da CLI.

​
Trate uma conexão fechada

Outras desconexões podem vir sem um motivo do LogBrew. Depois de reconectar, leia as rotas de lista de novo e associe os itens pelo ID.

​
Exemplos de resposta de status do problema

PATCH /api/telemetry/issues/{issue_id} com { "status": "resolved" } retorna 200 OK com o problema agrupado atualizado, no mesmo formato da resposta de problema. O parâmetro de consulta response_version escolhe a versão. A rota não retorna um indicador de sucesso. O corpo define 1 ou mais destes campos: status, priority e assignee. status aceita unresolved, resolved ou archived. ignored é um nome antigo de archived. Consulte Atualizar um problema. Confira id, status e priority retornados antes de mostrar sucesso. Não monte o resultado com os valores enviados. Uma mudança de status não exclui ocorrências nem altera first_seen_at e last_seen_at. Ela não altera severity nem uma regra de gravidade. Uma alteração rejeitada retorna 422 com code: validation_failed:
Um campo que já tem o valor solicitado não muda. Depois de um timeout ou de uma resposta perdida, envie a mesma requisição de novo ou leia o problema primeiro. Não envie uma alteração diferente antes de ler o estado atual. Consulte Escritas. POST /api/telemetry/issues/bulk retorna 200 OK com 1 resultado para cada ID de problema solicitado, na ordem da requisição. Cada problema encontrado usa o formato da versão 3. Um resultado not_found tem issue: null:
Este exemplo mostra só alguns campos do problema. outcome é updated, unchanged ou not_found. Uma requisição repetida retorna unchanged e não altera nada. Consulte Atualizar problemas em lote. Uma requisição em lote falha por inteiro nestes casos:

​
Escopo das requisições de análise

As rotas de análise, a rota de séries de métricas e a rota de volume de sinais leem um projeto e um período. Toda requisição precisa de project_id e since. since aceita uma duração compacta, como 24h ou 7d, ou um timestamp RFC3339. until aceita um timestamp RFC3339 e, por padrão, é o horário da requisição. O período inclui since, exclui until e não pode passar de 31 dias. service_name, release e environment são filtros exatos opcionais. Cada valor precisa ter de 1 a 256 caracteres depois que o LogBrew remove os espaços das pontas. A rota de comparação de segmentos coloca esses filtros dentro de cada segmento, não no nível superior. Se a conta não puder ler o projeto, essas rotas retornam 200 OK com contagens zeradas. Elas não retornam 404. Um resultado vazio não confirma o acesso ao projeto. Compare project_id com os projetos que a conta pode ler. Uma requisição por uma conexão MCP que não inclui o projeto retorna 403 e forbidden. Cada resposta começa com schema_version, query e purpose. query repete o escopo efetivo e omite os filtros que você não enviou. purpose é um texto simples que explica o que a rota responde. Uma taxa é omitida quando o denominador dela é zero. Uma taxa omitida não é 0 nem null. Leia coverage antes de confiar em uma taxa.

​
Erros de escopo comuns

Estes erros usam HTTP 422 e validation_failed: Por exemplo, uma requisição sem project_id retorna:
As rotas de séries de métricas e de volume de sinais usam as mesmas regras de escopo, com textos próprios de error. As seções delas, mais abaixo, listam esses erros. Um parâmetro de consulta desconhecido retorna 422 com a resposta de parâmetros de consulta inválidos. Um campo JSON desconhecido, a falta de um campo JSON obrigatório ou um valor de enum não aceito retorna invalid_json. Consulte JSON inválido. Uma requisição com o método HTTP errado retorna 405 e method_not_allowed. O texto de next dela informa o método e os campos aceitos. Consulte Método não aceito.

​
Resposta da visão geral de análise de produto

GET /api/telemetry/analytics/overview mostra a atividade de um projeto: volume de ações, usuários, sessões, uma série temporal, as principais ações e as visualizações de página, visualizações de tela e interações classificadas. Use essa rota para encontrar os nomes exatos de eventos das outras rotas de análise. Envie response_version=3. As versões 1 e 2 retornam as mesmas contagens, mas o valor de estimation.method delas é um nome mais antigo. A versão 1 não confere o tipo de identidade ao contar usuários identificados. As versões 2 e 3 contam só identidades do tipo user e adicionam contagens de identidades anônimas e subject_coverage. Esta requisição lê uma hora em intervalos de cinco minutos e retorna duas linhas em cada lista de principais itens:

​
Visão geral bem-sucedida

Neste resultado fictício, o projeto tem 120 ações em dois dos doze intervalos. Vinte ações vêm de identidades anônimas. Todas as ações têm um ID de sessão. Metade das ações tem um ID de trace.

​
Leia a visão geral

As cinco contagens de subject_coverage somam o total de eventos da seção delas. Só identified_user_events conta para usuários. anonymous_actions é summary.actions menos identified_actions. series contém só os intervalos com atividade. expected_buckets é o número de intervalos possíveis no período. Não desenhe um intervalo ausente como um zero medido, a menos que o gráfico informe essa regra. Os intervalos se alinham a limites fixos em UTC. Um período que começa no meio de um intervalo inclui esse intervalo parcial. classified_activity conta visualizações de página, visualizações de tela e interações. Visualizações de tela e interações também são ações. Visualizações de página não são. Não some summary.actions a classified_activity.summary.events. Copie kind e event_name de classified_activity.top_events para etapas de funil, seletores de retenção, seletores de ciclo de vida, âncoras de caminhos e alvos de segmentos. Um valor true em top_events_truncated significa que existem nomes com volume menor. Aumente top_limit até 20 para ver mais. analysis_level é no_data, event_only, user_level ou user_and_session. Se o projeto não tiver ações nem eventos classificados, next_action.code é capture_product_activity. Consulte Análise de produto.

​
Erros da visão geral

Além dos erros de escopo comuns, a visão geral retorna 422 e validation_failed para estes valores: O interval padrão é auto. Ele escolhe a menor largura de intervalo que gera no máximo 300 intervalos. O top_limit padrão é 10.

​
Resposta de funil ordenado

POST /api/telemetry/analytics/funnel mede a conclusão ordenada de 2 a 8 etapas. Copie cada kind e event_name exatos de classified_activity.top_events na visão geral. Um nome de ação parecido não é uma correspondência. Este corpo de requisição conta as sessões que visualizam /pricing e depois concluem o cadastro em até uma hora:
analysis_unit é session ou identified_user. O padrão é session. O kind de cada etapa é page_view, screen_view ou interaction. A rota de funil não aceita response_version.

​
Funil bem-sucedido

Uma resposta 200 OK:
As taxas são frações de 0 a 1. Leia coverage antes de confiar em uma taxa. selected_unit_coverage_rate é a parcela dos eventos das etapas selecionadas que o LogBrew conseguiu usar. A resposta não retorna identidades brutas. Consulte Análise de produto.

​
Leia a conversão e a cobertura

entry_rate é entered_units dividido por candidate_units: 50 de 60. overall_conversion_rate é completed_units dividido por entered_units: 15 de 50, ou 30%. Não é 15 dividido por todos os candidatos. Essas contagens não explicam por que as unidades pararam. A cobertura conta eventos, não sessões. Aqui, 120 eventos correspondem a uma etapa, e 20 deles não têm ID de sessão. O resultado exclui esses 20 eventos das contagens de sessões. Não os trate como 20 sessões que falharam. A primeira etapa não tem conversion_from_previous. A última etapa não tem drop_off_to_next_units nem drop_off_to_next_rate. Uma unidade só chega a uma etapa posterior quando os horários das etapas aumentam estritamente. Eventos com o mesmo timestamp não podem cumprir duas etapas seguidas. A etapa final precisa ocorrer em até conversion_window_seconds depois da primeira etapa. O modo de sessão conta sessões, não pessoas. Use identified_user só para eventos que trazem um ID de identidade opaco do tipo user. Esse modo pode juntar eventos de sessões diferentes dentro da janela de conversão. Mantenha a mesma unidade e as mesmas etapas ao comparar resultados. O conversion_window_seconds padrão é 24 horas ou a duração do período, o que for menor. O máximo é a duração do período em segundos inteiros, arredondada para cima.

​
Resultados de funil vazios

Uma resposta vazia bem-sucedida ainda lista as etapas solicitadas com units zerado. Se não houver unidades candidatas, summary omite entry_rate e overall_conversion_rate. A rota não retorna 404 só porque nenhum evento corresponde. Leia coverage e next_action para encontrar a causa:

​
Requisições de funil rejeitadas

Além dos erros de escopo comuns, estas requisições retornam 422 e validation_failed. Menos de 2 ou mais de 8 etapas:
Um conversion_window_seconds igual a 0, ou um valor maior que a duração do período:
Um event_name vazio, com mais de 256 caracteres ou com um caractere de controle retorna product analytics funnel event_name must be non-empty, control-free, and at most 256 characters. Uma etapa interaction também precisa ter um nome de ação válido. Caso contrário, o erro é product analytics interaction event_name must be a bounded stable action name. Corrija a requisição antes de enviá-la de novo. Não remova etapas nem mude a unidade de análise só para obter um resultado não vazio.

​
Análise por evento exato e análise automática

Retenção e ciclo de vida aceitam dois formatos de requisição. Use response_version para escolher o formato que responde à sua pergunta: Um seletor exato contém kind e event_name. kind é page_view, screen_view ou interaction. Copie event_name de classified_activity.top_events. Não deduza um nome de evento pelo rótulo de um botão. Os dois formatos contam só usuários: IDs de identidade opacos do tipo user. Identidades anônimas e eventos sem um ID de identidade utilizável não contam como usuários. As respostas nunca retornam IDs de identidade. Os intervalos fixos são hour, day, week e thirty_day. São durações fixas. thirty_day equivale a 30 dias, não a um mês do calendário. Se você omitir interval, a API usa hour para um período de até 48 horas e day para um período maior.

​
Requisição de retenção por evento exato

Envie este corpo para POST /api/telemetry/analytics/retention. Ele pergunta se os usuários concluem outra compra depois da primeira compra deles no período:
O primeiro evento inicial correspondente no período marca o ponto de partida de cada usuário. Um retorno precisa ocorrer estritamente depois desse ponto de partida e antes de until. Os dois seletores podem ser o mesmo evento.

​
Retenção por evento exato bem-sucedida

Neste exemplo fictício, dois usuários concluem uma compra. O primeiro conclui uma compra às 12:00 de 1º de junho e de novo às 13:00. O segundo conclui uma compra às 12:00 de 2 de junho. Às 13:00 de 2 de junho, o segundo usuário visualiza uma página, mas não conclui outra compra.

​
Leia a retenção

A cobertura conta os quatro eventos classificados, mas só três correspondem a cada seletor de compra. A visualização de página não conta como retorno. Um dos dois usuários repete a compra, então return_rate_after_start é 0.5. Só o primeiro usuário tem um dia inteiro de observação depois do ponto de partida. Ele volta dentro desse dia, então a taxa da curva é 1.0. O segundo usuário tem só 12 horas de observação. Ele não é elegível para o período 0, então a célula da segunda coorte omite retention_rate. Não conte esse usuário como perdido. weighted_retention_rate divide todos os usuários retidos por todos os usuários elegíveis. fully_observed_cohort_average_rate é a média simples das taxas das coortes em que todos os usuários são elegíveis. As coortes são intervalos fixos que começam em since. cohorts contém só as coortes que têm usuários. Com mode: "return_on_or_after", a curva omite window_end_seconds.

​
Retenção automática

Envie response_version: 2, sem start_event nem return_event. Toda visualização de página, visualização de tela e interação compatível conta como início e como retorno. Essa versão escolhe um conjunto de eventos. Ela não escolhe um formato de captura do SDK.
A resposta tem os mesmos formatos de summary, curve, cohorts e next_action da resposta por evento exato. Este trecho mostra os campos que mudam. Neste exemplo, os mesmos dois usuários têm três eventos e nenhuma visualização de página:
No modo automático, start_events e return_events são iguais a classified_events. Essas contagens são de eventos, não de usuários.

​
Retenção sem usuários elegíveis

Um resultado bem-sucedido pode não ter usuários em nenhuma coorte. Este trecho mostra um período solicitado sem coortes:
Leia coverage e next_action. Eles distinguem um escopo sem eventos classificados (capture_product_activity) de eventos sem usuários (identify_product_users ou identify_returning_users). Uma taxa ausente não é um zero medido.

​
Erros de retenção

Além dos erros de escopo comuns, estas requisições retornam 422 e validation_failed: O limite de células depende do período consultado e dos períodos de retenção, não do número de usuários. Um período de 30 dias com interval: "hour" tem 720 intervalos de coorte. Com interval_count: 1, são 720 células, mais que 500:
Para usar a retenção automática, remova os dois seletores. Não altere o SDK para corrigir esta requisição de leitura.

​
Requisição de ciclo de vida por evento exato

Envie este corpo para POST /api/telemetry/analytics/lifecycle. Ele classifica os usuários por um evento, não por toda a atividade do projeto:
history_period_count define quantos períodos completos antes de since o LogBrew lê como histórico. Ele aceita de 2 a 31. O padrão é 2. Um usuário pode estar inativo para este evento enquanto faz outras atividades.

​
Ciclo de vida por evento exato bem-sucedido

Este exemplo fictício usa dois dias de histórico e dois dias de análise. As letras só identificam os usuários do exemplo. A resposta não retorna IDs de usuário. C também visualiza uma página em 2 de junho. Esse evento não corresponde ao seletor de compra.

​
Leia o ciclo de vida

Em 1º de junho, A é recorrente, B é reativado, C é novo e D está inativo. Em 2 de junho, A e B são recorrentes, e C está inativo para a compra, apesar da visualização de página. A variação líquida em 2 de junho é 2 - 3 = -1. Em cada intervalo, os usuários novos, recorrentes e reativados somam active_subjects. returning_subjects mais dormant_subjects é igual a previous_active_subjects. net_active_change é active_subjects menos previous_active_subjects. Não some as contagens diárias de ativos para obter usuários distintos. Aqui, as contagens diárias somam 5, mas analysis_active_subjects é 3. Quatro usuários distintos aparecem entre o histórico e a análise. fully_observed é false em um intervalo final que termina depois de until. As contagens dele podem mudar quando o período inteiro puder ser observado. O next_action sugere uma investigação. Ele não mostra uma causa.

​
Ciclo de vida automático

Envie response_version: 2, sem o seletor event. Toda visualização de página, visualização de tela e interação compatível conta como atividade:
A resposta tem os mesmos formatos de summary, buckets e next_action da resposta por evento exato. Este trecho mostra os campos que mudam:
No modo automático, coverage.selected_events é igual a coverage.analysis_classified_events. O quinto item de limitations é Returning, resurrected, and dormant compare any supported classified product activity; no event is ranked, selected, or inferred.

​
Ciclo de vida sem usuários

Se nem o período de análise nem o histórico tiverem usuários utilizáveis, buckets fica vazio e summary omite latest_fully_observed_period:
Usuários que aparecem só no histórico ainda podem gerar intervalos com usuários inativos quando o período de análise não tem atividade.

​
Erros de ciclo de vida

Além dos erros de escopo comuns, estas requisições retornam 422 e validation_failed: Por exemplo, dez períodos de histórico week precisam de 70 dias:

​
Leia o escopo de análise selecionado

As respostas por evento exato têm schema_version: 1. O query delas repete os seletores e omite activity_scope. As respostas automáticas têm schema_version: 2 e query.activity_scope: "all_classified_activity". Elas omitem os seletores. Um seletor diferente pode mudar o resultado sem nenhuma mudança na atividade capturada.

​
Resposta de série de métricas

GET /api/telemetry/metrics/series lê um nome exato de métrica em um projeto. Copie o nome de GET /api/telemetry/metrics. Esta requisição agrupa um contador delta por serviço:

​
Série de métricas bem-sucedida

Esta resposta fictícia contém uma série de contador delta. Três amostras com os valores 2, 3 e 5 ocorrem no primeiro intervalo. Duas amostras com os valores 1 e 4 ocorrem no último intervalo. Nenhuma amostra ocorre no intervalo do meio, então a resposta não tem ponto para ele.

​
Leia uma série de métricas

O primeiro ponto registra 10 tarefas concluídas, não 10 amostras. rate_per_second divide essa variação pelo intervalo de 300 segundos. last é a última variação registrada, não a soma. Consulte significados da agregação de métricas. O tipo e a temporalidade de uma série definem o aggregation.code e as estatísticas de cada ponto. Um ponto omite as estatísticas que não se aplicam. Uma estatística ausente não é zero. limited é uma resposta bem-sucedida, não um erro. Ela adiciona aggregation.limitation, que explica por que o LogBrew mostra só valores brutos. ready não prova que a captura está completa. Leia coverage antes de desenhar um gráfico:
  • samples conta as amostras de todas as séries correspondentes, incluindo séries que a resposta não retorna.
  • series conta as séries correspondentes. returned_series e points contam os dados retornados.
  • truncated é true quando series_limit removeu séries de volume menor.
  • expected_buckets_per_series é o número de intervalos possíveis no período.
Não adicione um ponto para um intervalo sem amostras. Não insira um zero nem copie o valor anterior. Cada ponto retorna até 3 trace_exemplars. Um exemplar de trace vincula uma amostra a um trace. Ele não explica todas as amostras do intervalo. Se nenhum ponto tiver um exemplar de trace, next_action.target é metric_samples.

​
Escopo e erros da série de métricas

project_id, name e since são obrigatórios. name pode ter no máximo 200 caracteres. interval é auto, 1m, 5m, 15m, 1h, 6h ou 1d. O padrão é auto, que escolhe a menor largura de intervalo com no máximo 300 intervalos. Uma largura explícita não pode gerar mais de 500 intervalos. group_by é none, service_name, release ou environment. O padrão é none. Sem agrupamento, tipos, unidades e temporalidades diferentes ficam em séries separadas. series_limit aceita de 1 a 20. O padrão é 10. Um resultado vazio retorna 200 com series: [] e samples zerado. O objeto coverage omite first_seen_at e last_seen_at. Isso não prova que a aplicação nunca enviou a métrica. Confira o projeto, o nome da métrica e o período. Omitir name retorna 422:
Intervalos de um minuto ao longo de sete dias retornam 422:
Outros erros 422 são metric series group_by is not supported, metric series interval is not supported e metric series_limit must be between 1 and 20.

​
Resposta da análise de caminhos

POST /api/telemetry/analytics/paths encontra os eventos nomeados antes ou depois de um evento selecionado, na mesma sessão. O evento selecionado é a âncora. Copie o kind e o event_name dele de classified_activity.top_events. A rota retorna schema_version: 1. Ela não aceita response_version nem analysis_unit.
direction e anchor são obrigatórios.

​
Caminhos bem-sucedidos

Neste resultado fictício, quatro sessões contêm a âncora. Os dois caminhos retornados representam três dessas sessões. Um caminho com classificação menor não é retornado.

​
Leia os caminhos

share_of_anchored_sessions divide as sessões de um caminho pelas quatro sessões com âncora. As parcelas são 50% e 25%, não 67% e 33%. unrepresented_sessions conta as sessões com âncora que nenhum caminho retornado representa. paths_truncated: true significa que o resultado está incompleto. A cobertura conta eventos, não sessões. Aqui, cinco eventos correspondem à âncora, mas um não tem ID de sessão. Esse evento não pode entrar em um caminho. Cada caminho retorna até 3 exemplares de trace. Use um ID de trace da sua própria resposta. Um vínculo com um trace não mostra o que causou uma ação do usuário ou uma falha. Os nós ficam em ordem cronológica nas duas direções. Um caminho não é uma reprodução completa da sessão. O LogBrew lê no máximo 1024 eventos nomeados por sessão antes de escolher a âncora: os eventos mais antigos para following e os mais recentes para preceding. Uma âncora fora desse limite pode ser omitida.

​
Filtre a âncora por propriedade

Envie até quatro property_filters, cada um com um key e um value exatos. Copie a chave do catálogo de propriedades. Os filtros valem só para a âncora, não para os eventos ao redor dela. Os valores diferenciam maiúsculas de minúsculas. Quando há filtros, query os repete, e coverage.anchor_property_filters informa: Chaves ausentes e valores diferentes pedem correções diferentes. Não some os dois. O objeto é omitido quando a requisição não tem filtro de propriedade.

​
Caminhos vazios e requisições rejeitadas

Um array paths vazio pode ser uma resposta 200 bem-sucedida. Leia summary, coverage e next_action. Estes códigos distinguem as causas: capture_product_activity, choose_captured_path_anchor, capture_anchor_properties, improve_anchor_property_coverage, verify_anchor_property_values, sessionize_product_activity e narrow_or_move_path_anchor. Além dos erros de escopo comuns, estas requisições retornam 422 e validation_failed: Por exemplo, depth: 0 retorna:

​
Catálogo de propriedades de análise

GET /api/telemetry/analytics/properties lista as chaves de propriedade dos eventos de produto classificados de um projeto. Use as chaves em comparações de segmentos e em filtros de âncora de caminhos. O catálogo retorna chaves e contagens. Ele nunca retorna valores de propriedades nem identidades.

​
Leia as chaves de propriedade disponíveis

Envie project_id e since. Você também pode enviar until, service_name, release, environment, limit e response_version. limit aceita de 1 a 50 chaves. O padrão é 20. Envie response_version=2 para obter o valor público de estimation.method.

​
Catálogo de propriedades bem-sucedido

Neste resultado fictício, existem 100 eventos classificados. Cinco deles foram capturados antes do índice de propriedades atual.
source é standard_context para uma chave de contexto padrão, como resource.runtime.name, ou custom_tag para uma chave que começa com tag.. value_type é sempre string. properties vem ordenado por events, do maior para o menor. tag.plan está em 60 de 100 eventos classificados. Ela tem cerca de 3 valores distintos. A descrição da chave não mostra esses valores. Use valores que você conhece da sua aplicação. Não deduza um valor a partir de uma contagem. Um evento pode ter várias chaves, então não some as contagens de events por chave. Um array properties vazio não prova que o projeto não tem eventos de produto. Leia summary, coverage e next_action.

​
Erros do catálogo de propriedades

Além dos erros de escopo comuns, limit=0 ou limit=51 retorna 422:
Um response_version diferente de 1 ou 2 retorna product analytics response_version must be 1 or 2. O LogBrew confere response_version antes dos outros valores. Uma requisição POST retorna 405:

​
Comparação de segmentos de análise

POST /api/telemetry/analytics/segments/compare compara com que frequência sessões ou usuários chegam a um evento exato em 2 a 4 segmentos de um projeto. Um segmento seleciona eventos por serviço, versão, ambiente e valores de propriedades. O primeiro segmento é a referência.

​
Defina a comparação

Envie este corpo JSON com a autenticação da conta e Content-Type: application/json. Aqui, basic e premium são valores de plano da aplicação de exemplo, não planos do LogBrew:
target e segments são obrigatórios. analysis_unit é session ou identified_user. O padrão é session, que conta sessões, não pessoas. interval aceita os mesmos valores da visão geral. O padrão é auto. Cada segmento precisa de um key único, um label e um conjunto de filtros diferente:
  • key: de 1 a 32 bytes. Comece com uma letra ASCII minúscula ou um dígito. Use só letras ASCII minúsculas, dígitos, _ e -.
  • label: de 1 a 80 caracteres, sem caracteres de controle.
  • service_name, release, environment: opcionais. Cada valor tem de 1 a 256 caracteres, sem caracteres de controle.
  • property_filters: de 0 a 4 filtros. Cada chave pode aparecer uma vez em um segmento. Um evento precisa corresponder a todos os filtros do segmento. Os valores diferenciam maiúsculas de minúsculas e têm de 1 a 256 caracteres. O LogBrew remove os espaços do início e do fim.
Um segmento sem filtros seleciona toda a atividade classificada do projeto no período. Os segmentos podem se sobrepor. Um rótulo ou uma chave diferente não torna válidos dois conjuntos de filtros idênticos.

​
Comparação de segmentos bem-sucedida

Neste resultado fictício, a referência chega ao checkout em 10 de 50 sessões. O segmento premium chega a ele em 18 de 60 sessões.

​
Leia as taxas e as diferenças

eligible_units estima as sessões ou os usuários com atividade classificada no segmento. reached_units estima quantos deles chegaram ao alvo. reach_rate é reached_units dividido por eligible_units. Eventos sem o ID da unidade selecionada não contam para essas unidades. A taxa da referência é 20%. A taxa do premium é 30%. A diferença é de 10 pontos percentuais. O aumento relativo é de 50%, não de 10%. Pequenos erros nas casas decimais vêm da aritmética de ponto flutuante. Arredonde as taxas para exibição, mas calcule com os valores retornados. O segmento de referência não tem comparison_to_baseline. O aumento relativo é omitido quando a taxa de alcance da referência é zero. Em query, um filtro de segmento que você não enviou é null. Uma lista property_filters vazia é omitida. coverage.property_filters tem os mesmos campos da cobertura dos filtros de âncora de caminhos. Aqui, matching_events é igual a classified_events. Mantenha separadas as chaves ausentes e os valores diferentes. Os segmentos podem se sobrepor, e uma sessão pode aparecer em vários intervalos. Não some contagens de unidades entre segmentos ou intervalos. A comparação é descritiva. confidence.causal_inference é not_established e confidence.statistical_significance é not_tested. Uma taxa de 30% contra 20% não mostra que um plano causou mais compras.

​
Erros da comparação de segmentos

Além dos erros de escopo comuns, estas requisições retornam 422 e validation_failed: Os erros de interval são os mesmos dos erros da visão geral. Por exemplo, dois segmentos com chaves diferentes e filtros idênticos retornam:
Um rótulo diferente ou outra ordem dos filtros de propriedade não muda os eventos selecionados. Uma falha de validação não é evidência de que nenhum evento corresponde. Uma requisição GET retorna 405:

​
Resposta de volume de sinais

GET /api/telemetry/summary/volume conta os sinais retidos de um projeto em um período. A rota exige project_id e since. Ela não aceita project_ids. until não pode estar no futuro. Se você o omitir, o fim é o horário da requisição. Um since compacto, como 24h, conta para trás a partir de until. interval é auto, 1m, 5m, 15m, 1h, 6h ou 1d. O padrão auto escolhe a menor largura de intervalo com no máximo 120 intervalos. Uma requisição não pode gerar mais de 500 intervalos. O único response_version é 1.

​
Contagens de sinais

Esta resposta fictícia cobre dois intervalos de um minuto. A requisição foi feita às 12:02 UTC, sem until. A conta tem uma política de retenção de 30 dias. Leia a política e a data de corte retornadas. Não presuma que esses valores valem para a sua conta.

​
Leia cada contagem na própria unidade

total é a soma das contagens dos intervalos da série. peak é a maior contagem de um intervalo. non_empty_buckets conta os intervalos com contagem acima de zero. As cinco séries sempre aparecem nesta ordem. Não junte contagens de sinais diferentes em uma única pontuação de impacto. Os intervalos começam em query.since. Um intervalo inclui o início e exclui o fim. O último intervalo pode ser mais curto que a largura escolhida. A resposta não tem série de contagem de versões. Não interprete release_volume_not_included como zero versões.

​
Períodos vazios e encurtados

Se nenhum sinal corresponder, as cinco séries continuam na resposta, e os pontos delas têm contagens zero explícitas. Uma requisição que falhou é diferente. Não substitua um erro por um gráfico preenchido com zeros. Compare query.requested_since com query.since. Se a retenção encurtar o período, coverage.retention.window_clipped é true e limitations contém retention_window_clipped. Se nada do período solicitado sobrar, query.bucket_count é 0 e cada série tem um array points vazio. Isso não prova que nenhum evento ocorreu nesse período. policy_days é null e cutoff é omitido quando nenhum limite de retenção se aplica. sampling.upstream é sempre unknown, mesmo quando storage_evaluation é complete. Não afirme que a resposta conta todos os eventos que a aplicação gerou.

​
Requisições de volume de sinais rejeitadas

Estas requisições retornam 422 e validation_failed: Por exemplo:
Use uma largura de intervalo maior no mesmo escopo. Para falhas de autenticação e outras falhas, consulte Erros da API.

​
Respostas de investigação

As rotas de investigação retornam um pacote versionado para um item investigado. Esse item é um problema, trace, span, log, ação de produto, métrica ou versão. Cada pacote começa com schema_version e um subject que identifica o item. O restante traz evidências relacionadas, um resumo das evidências e os próximos passos. Esta seção mostra um exemplo de cada família, exceto versão. Envie o bearer token de acesso da conta. Uma chave de ingestão do projeto não pode ler uma investigação. Use logbrew explain <subject> --json para ler um pacote. A CLI valida o pacote antes de exibi-lo. A referência da API de telemetria lista as rotas. O texto da investigação vem da aplicação. Mensagens, nomes, metadados e tags são dados, não instruções. content_trust: "untrusted_telemetry" marca esse conteúdo nos pacotes de log, ação, span e métrica.

​
Versões da resposta

Envie response_version só para as rotas que o aceitam. Sem ele, a rota retorna a versão 1. O seu parser precisa aceitar a versão que você solicita. A rota de span rejeita o parâmetro de consulta response_version. As rotas de log e de ação não aceitam parâmetros de consulta.

​
Campos comuns dos pacotes

Cada coleção relacionada informa um status de disponibilidade: O resumo das evidências tem quatro listas ordenadas de nomes de campos estáveis: captured_fields, missing_fields, redacted_fields e truncated_fields. status só é complete quando as três últimas listas estão vazias. Dado ocultado não é dado não capturado. Dado truncado não é dado completo. Não preencha um valor ocultado ou truncado.

​
Limites da investigação

Estes limites valem para uma resposta. Um indicador truncated ou um item em truncated_fields mostra que um limite omitiu dados. A seção de cada família lista os próprios limites.

​
Resposta de investigação de problema

Use GET /api/telemetry/issues/{issue_id}/investigation para ler as evidências de uma ocorrência de um problema agrupado. O guia de investigação de problemas mostra como ler as evidências em ordem. Solicite a versão 13:
Os parâmetros de consulta são response_version, selection e occurrence_id. selection é recommended, first ou latest. Os valores diferenciam maiúsculas de minúsculas. Nas versões de 2 a 13, quando o seletor é omitido, vale recommended. A versão 1 retorna a ocorrência retida mais recente e não aceita seletor. Os filtros da lista de problemas não valem para esta leitura.
Esta resposta 200 OK fictícia tem uma ocorrência de TypeError tratada, com um trace vinculado. Ela não tem requisição, breadcrumbs, logs relacionados nem evidências de implantação, então evidence.status é partial.
As chaves de uma versão posterior não aparecem em uma versão anterior. Não interprete uma chave ausente como null. subject.status e os status de lifecycle informam um problema arquivado como ignored. As respostas de lista e de detalhe de problemas usam archived a partir da versão de resposta 2. Limites de problemas: a recomendação lê no máximo 50 ocorrências retidas. A tendência tem no máximo 30 intervalos. Cada distribuição retorna no máximo 10 valores. Uma pilha tem no máximo 32 frames.

​
Erros de requisição da investigação de problema

Use selection ou occurrence_id. Não envie os dois, mesmo quando eles selecionam a mesma ocorrência:
Uma ocorrência inexistente não significa que o problema não existe. Um 404 não mostra se outra conta pode ler o problema.

​
Resposta de investigação de trace

Use GET /api/telemetry/traces/{trace_id}/investigation para ler um trace com o caminho da falha, o caminho mais lento e os sinais relacionados. Os parâmetros de consulta são response_version, project_id, release e environment. Todos são opcionais. Solicite a versão 3:
A versão 2 adiciona cause e fix a cada problema relacionado. A versão 3 adiciona span_id aos problemas, ações e métricas relacionados quando ele foi capturado.
Esta resposta fictícia tem um span raiz de servidor e um span de cliente com falha. O span com falha também é o span filho mais lento. Os spans não têm contexto estruturado, então spans.context fica como não capturado.
trace.parentage fica como não capturado quando um span indica um pai que o LogBrew não reteve. A prévia de spans tem no máximo 64 spans. Cada caminho de análise tem no máximo 64 spans. As leituras relacionadas usam no máximo 8 escopos de implantação. Um próximo passo com o destino trace_span indica um span_id deste pacote. Para ler esse span, chame a rota de span com o project_id, o environment e o release do span.

​
Resposta de investigação de span

Use GET /api/telemetry/traces/{trace_id}/spans/{span_id}/investigation para ler uma operação de um trace. Envie project_id, environment e release. Os três são obrigatórios. Copie-os do span selecionado. Não envie o id da linha do span como span_id.
Esta resposta fictícia descreve o span de cliente com falha do exemplo de trace. Um log de erro tem o mesmo ID de span. O span demorou mais que o percentil 95 aproximado dos spans semelhantes retidos.
A linha de base lê as 24 horas antes do início do span. since é inclusivo e until é exclusivo. error_rate_basis_points: 500 significa 5%. subject_percentile_basis_points: 9500 significa que 95% dos spans semelhantes retidos não demoraram mais que este span. Os percentis são aproximados. Mantenha baseline.limitations junto com os valores. Uma linha de base not_found não tem spans semelhantes retidos. Uma linha de base unavailable é uma leitura que falhou, não uma contagem zero. parent_chain_status: "complete" significa que a cadeia retida chega a uma raiz. Isso não prova que o LogBrew reteve todos os spans da requisição. A topologia retorna no máximo 64 ancestrais, 50 filhos diretos e 50 ligações entre serviços.

​
Resposta de investigação de log

Use GET /api/logs/{log_id}/investigation para ler um log e as evidências relacionadas. Esta rota não tem parâmetros de consulta. Copie o ID do log de uma lista de logs.
A leitura pode retornar evidências fora dos filtros da lista de logs. As leituras relacionadas usam o projeto, o ambiente e a versão do log, e 5 minutos antes e depois do log. Os logs próximos também usam o mesmo serviço. Eles não precisam de ID de trace. As leituras pelo trace exato precisam do ID de trace do log e podem incluir outros serviços. O resumo do trace usa o mesmo ID de trace e o mesmo escopo, sem o período.
Esta resposta fictícia tem um log de aviso sem contexto de trace e um log próximo. A resposta não cria um vínculo de trace a partir dos horários.
Um ID de trace pode estar presente quando o status do trace é not_found ou unavailable. Um resumo de trace disponível não garante um exact_span.

​
Resposta de investigação de ação

Use GET /api/telemetry/actions/{action_id}/investigation para ler uma ação de produto, o status informado dela e as evidências relacionadas. Esta rota não tem parâmetros de consulta. As leituras relacionadas usam o mesmo período e os mesmos escopos de uma investigação de log.
correlations, timeline e next_actions usam os formatos da investigação de log. As ações relacionadas não incluem a ação investigada.
Esta resposta fictícia descreve uma ação de checkout que falhou, feita por um usuário conectado. A ação não tem ID de trace.
A resposta nunca retorna identificadores da identidade nem da sessão. O resumo das evidências sempre lista subject.distinct_id como ocultado, e subject.session_id quando uma sessão foi capturada. Por isso, todo pacote de ação é partial e inclui improve_capture. Não remova controles de privacidade para atender a esse próximo passo.

​
Resposta de investigação de métrica

Use GET /api/telemetry/metrics/investigation para ler um nome de métrica em um projeto e um período. A resposta traz a série atual, uma comparação com o período anterior de mesma duração, a amostra mais recente, exemplares de trace e as implantações concluídas. A versão 2 adiciona a descrição da métrica a partir da amostra retida mais recente. A versão 1 sempre informa description_status: "not_captured".
project_id, name e since são obrigatórios. since é inclusivo e until é exclusivo. Por padrão, until é o momento atual. A comparação também lê o período anterior de mesma duração.
Este histograma fictício tem 5 amostras em dois intervalos de 5 minutos. O intervalo mais recente tem p95 de 48 ms. O intervalo mais recente do período anterior tem p95 de 24 ms.
relative_change_percent é (current - previous) / abs(previous) * 100. Ele é null quando o valor anterior é zero ou está ausente. expected_buckets_per_series conta os intervalos possíveis, não os intervalos com dados. Não desenhe intervalos vazios como zero. Uma implantação perto de uma variação não prova que ela causou a variação. Um projeto que a conta não pode ler retorna 200 OK com analysis.status: "no_samples", não 404. Um resultado vazio não descreve outros tipos de sinal. Limites de métricas: o período tem no máximo 31 dias. Cada série tem no máximo 500 intervalos. series_limit vai de 1 a 20, com padrão 10. A resposta retorna no máximo 20 exemplares e 20 implantações. interval é auto, 1m, 5m, 15m, 1h, 6h ou 1d. group_by é none, service_name, release ou environment. Outros valores retornam 422.

​
Erros de investigação

Um 404 significa que nenhum projeto que a conta pode ler tem o registro. Cada rota também retorna 401 sem autenticação válida e 405 para um método diferente de GET. Consulte Erros da API para ver as respostas de recurso não encontrado, caminho, autenticação e método. Uma leitura opcional de evidências pode falhar dentro de uma resposta 200 OK. Nesse caso, a coleção informa unavailable. Não a mostre como not_found nem como zero registros.

​
Valores de gravidade

Os valores de gravidade exibidos às pessoas são info, warning, error e critical. SDKs e runtimes podem enviar aliases comuns, como trace, debug, warn ou fatal. As respostas REST e ao vivo sempre retornam o valor canônico. Por exemplo, o LogBrew aceita warn na entrada e retorna warning. A ingestão rejeita valores de gravidade desconhecidos.

​
Respostas de regras de gravidade

Uma regra de gravidade muda como o LogBrew mostra um log ou um problema. Ela não muda a gravidade que a aplicação capturou. Logs e problemas retornam um objeto triage: Use triage.effective_severity para exibir a gravidade. Mantenha severity como o valor capturado. Por padrão, a lista de logs omite os logs ignorados. Para incluí-los, envie status=ignored ou status=all em GET /api/logs. A conta precisa de permissão para gerenciar problemas no projeto. Acesso de leitura não basta. Sem essa permissão, uma mudança de regra retorna 403 com code: forbidden.

​
Altere uma regra de log

PUT /api/logs/{log_id}/triage-rule define a regra para o log e para os logs posteriores com a mesma assinatura. O corpo precisa de severity e de ignored:
Uma resposta 200 OK contém o log completo. O severity dele continua warning. O triage mostra a regra:
Este trecho mostra só os campos alterados. Na requisição, severity é source, info, warning, error ou critical. source restaura a gravidade capturada. Ele não torna ativo um log ignorado. Para mostrar o log de novo, envie "ignored": false.

​
Altere uma regra de problema

PUT /api/telemetry/issues/{issue_id}/triage-rule define a gravidade exibida de um problema agrupado e das ocorrências posteriores dele. O corpo aceita só severity:
Uma resposta 200 OK contém o problema completo na versão 1 da resposta. O severity e o status capturados não mudam:
Este trecho mostra só alguns campos. Uma regra não resolve, não arquiva nem reabre um problema. Para isso, use a mudança de status. Uma prioridade derivada acompanha a nova gravidade efetiva. Para vê-la, leia o problema com response_version=2 ou 3. Uma gravidade não aceita retorna 422:
Um campo desconhecido no corpo, como status em uma regra de problema, retorna 422 com code: invalid_json. Um log ou problema inexistente, ou que a conta não pode ler, retorna 404 com code: not_found. Se a resposta se perder, leia o log ou o problema de novo antes de reenviar a regra.

​
Formato da resposta de erro

Os erros da aplicação retornam um envelope JSON. Este exemplo mostra uma requisição rejeitada. O texto de error e de next varia conforme o erro:
Use code para as ramificações do programa e next_action para automação. Mostre error e next às pessoas como texto simples. Não analise a redação deles. Alguns erros adicionam campos, como limit, reset_at ou retry_after_seconds. Uma resposta sem corpo JSON não tem code do LogBrew. Consulte Erros da API para ver todos os códigos.

​
Leia dados com a CLI

A CLI lê as mesmas rotas e retorna o mesmo JSON com --json. Comece com uma leitura ampla e depois restrinja:
Adicione --pagination cursor para receber o envelope de cursor. A CLI solicita a versão 4 da resposta de problemas. Consulte Ler a próxima página e Acompanhamento ao vivo.