Encontre e explore rastos

Para ver uma representação agregada dos dados de rastreio ou para encontrar e explorar rastreios individuais ou rastreios que contêm etiquetas específicas, use a página Explorador de rastreios.

Esta funcionalidade só é suportada para projetos do Google Cloud . Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

Acerca da página Explorador de rastreios

Para ajudar a identificar tendências e padrões nos dados de rastreio, os dados de latência são agregados e apresentados em gráficos. O mapa de calor, que é a visualização predefinida, usa a cor para representar o número de intervalos numa célula. Uma célula com muitos intervalos é apresentada com uma cor mais escura do que uma célula com poucos intervalos. Pode selecionar uma célula ou ativar a sugestão de uma célula para obter mais informações. As outras visualizações permitem ver a latência como um percentil e informações sobre a taxa de intervalos. Para todas as visualizações, pode usar o ponteiro para expandir o eixo X. Para os gráficos de linhas, pode expandir os eixos x e y.

Quando está a investigar um problema, pode querer ver um rastreio específico ou apenas intervalos com determinadas propriedades:

• Quando souber o ID de um rastreio, na barra de ferramentas, clique em visualização de página Pesquisar rastreio e, de seguida, introduza o ID do rastreio na caixa de diálogo. Em seguida, pode pesquisar as extensões e os atributos no rastreio por palavras-chave .

• Quando visualiza os dados agregados, pode pesquisar intervalos específicos aplicando filtros. Por exemplo, pode filtrar os dados para apresentar apenas os intervalos de um serviço específico. Em seguida, pode adicionar um segundo filtro que limite a apresentação a intervalos de um serviço específico que comunica um erro.

Os dados tabulares permitem ver detalhes de intervalos individuais e ajudam a identificar valores atípicos. Por exemplo, para encontrar o intervalo com o valor de latência mais elevado, selecione o separador Intervalos e, em seguida, ordene os dados por latência. Para encontrar os serviços que estão a gerar erros, filtre os dados por estado do intervalo e, de seguida, selecione o separador Agrupado, que mostra os dados agregados por intervalo e nome do serviço. Cada linha na tabela contém um link para informações detalhadas.

Os dados de rastreio apresentados pela página Explorador de rastreios dependem do seguinte:

• Os projetos nos quais foram pesquisados dados de rastreio. Por predefinição, apenas o projeto selecionado no seletor de projetos é pesquisado quanto a dados de rastreio. No entanto, pode configurar a página para pesquisar a lista de projetos num âmbito de rastreio.
• As suas autorizações da gestão de identidade e de acesso (IAM) nos projetos pesquisados. Se não tiver autorização para ver os dados de rastreio de um projeto, a consola apresenta uma mensagem de aviso e os dados desse projeto não são apresentados. Google Cloud
• A definição do intervalo de tempo.
• Os filtros que aplica.

O resto desta página fornece mais informações sobre como encontrar e explorar os dados de rastreio.

Antes de começar

Para obter as autorizações de que precisa para ver dados de rastreio através da Google Cloud consola e para selecionar um âmbito de rastreio, peça ao seu administrador para lhe conceder a função do IAM utilizador do Cloud Trace (roles/cloudtrace.user) no seu projeto. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para ver dados de rastreio através da Google Cloud consola e para selecionar um âmbito de rastreio. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

As seguintes autorizações são necessárias para ver dados de rastreio através da Google Cloud consola e para selecionar um âmbito de rastreio:

• Para selecionar um âmbito do rastreio: cloudtrace.traceScopes.[get, list]
• Para ler o âmbito do rastreio predefinido: observability.scopes.get

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Para mais informações sobre as funções, consulte o artigo Controle o acesso com a gestão de identidades e acessos.

Veja dados de rastreio agregados

Para ver as informações agregadas sobre os dados de rastreio, faça o seguinte:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

   Pode demorar vários minutos após a gravação dos primeiros dados de rastreio num Google Cloud projeto antes de esses dados estarem disponíveis para visualização. Se não vir dados de rastreio apresentados após aguardar alguns minutos, significa que o seu projeto pode não ter dados para apresentar ou pode existir um problema de configuração. Para obter informações sobre como resolver estes problemas, consulte o artigo Resolução de problemas: não existem dados na interface de rastreio.

2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

3. Opcional: configure em que projetos são pesquisados dados de rastreio através do elemento Âmbito:

   • Para mostrar os dados de rastreio armazenados no seu projeto, defina o primeiro menu do elemento Âmbito como Projeto ou _Predefinição. Estas duas definições são equivalentes.

   • Para mostrar os dados de rastreio armazenados em vários projetos, expanda o primeiro menu do elemento Âmbito, selecione Âmbito de rastreio e, de seguida, selecione o âmbito de rastreio que lista esses projetos. Depois de fazer a seleção, o menu Âmbito apresenta um ícone de âmbito de rastreio, , e o nome do âmbito de rastreio selecionado.

   Os dados devolvidos dependem das suas funções do IAM nos projetos pesquisados. Por exemplo, se os projetos pesquisados incluírem um projeto ao qual não tem acesso, não são devolvidos dados de rastreio para esse projeto. Google Cloud

   Para mais informações, consulte o artigo Crie e faça a gestão de âmbitos de rastreio.

4. Opcional: atualize o intervalo de tempo através do seletor de intervalo de tempo ou usando o ponteiro para realçar um intervalo no eixo X.

   Por exemplo, pode definir este seletor como Últimas 2 semanas quando quiser ver se existem tendências nos dados de latência.

5. Aceda à barra de ferramentas e defina o seletor de intervalo de tempo para, pelo menos, duas semanas. Dados de intervalo armazenados durante 30 dias.

6. Explore os gráficos, que mostram padrões e tendências nos seus dados de rastreio:

   • Para obter informações sobre os dados de latência do intervalo, defina o menu Vista de gráfico como Duração do intervalo (mapa térmico). A intensidade da cor é proporcional ao número de intervalos. Para ver informações sobre uma célula, use o ponteiro. A sugestão apresenta o número de intervalos, a data e a hora, bem como o intervalo de tempo da célula.

     Nota: se selecionar uma célula no mapa de calor, a tabela que apresenta os intervalos individuais ou os agrupamentos de intervalos é atualizada.

   • Para ver as tendências de latência, defina o menu Vista de gráfico como Duração do intervalo (percentil). O gráfico de duração apresenta os percentis 50, 90, 95 e 99.

   • Para ver o estado de resposta em função do tempo, defina o menu Vista do gráfico como Taxa de intervalo. O gráfico apresenta a taxa de intervalos enviados para o seu projeto.

7. Explore os dados tabulares que listam os intervalos individuais no separador Intervalos e os intervalos agrupados pelo respetivo serviço e nome no separador Agrupados.

   Cada linha nas tabelas apresenta um intervalo ou um agrupamento, juntamente com um link para informações detalhadas e algumas métricas. Por exemplo, no separador Agrupado, as métricas incluem a taxa de erro e o número de intervalos no grupo.

   Para encontrar valores atípicos, selecione um cabeçalho de coluna para ordenar a tabela.

8. Adicione filtros para restringir os intervalos apresentados. Para saber mais sobre como filtrar os dados de rastreio, consulte a secção seguinte.

Filtre os dados de rastreio

Para apresentar apenas informações do seu interesse, aplique filtros. Os filtros restringem os dados apresentados. Por exemplo, pode filtrar por nome do serviço e por estado. Em alternativa, se tiver implementado aplicações no App Hub, pode querer ver os dados de rastreio apenas para a aplicação ou para um serviço ou uma carga de trabalho específicos que façam parte da aplicação.

Quando adiciona ou remove um filtro, os dados apresentados na página Explorador de rastreios são atualizados e mostram apenas os intervalos que correspondem a todos os filtros aplicados.

Para alterar as definições de filtros, pode usar o painel Filtros de intervalo ou a barra Filtro.

Aplique filtros de intervalo

O painel Filtros de intervalo apresenta os filtros mais comuns. Pode selecionar várias entradas de qualquer subcategoria. À medida que adiciona ou remove filtros, a barra Filtro também é atualizada.

Os valores de todos os menus são derivados dos seus dados de rastreio. Quando um menu inclui uma opção sem texto, essa opção refere-se a intervalos que não incluem o atributo correspondente.

Os seguintes filtros de intervalo estão normalmente disponíveis:

• Serviço OpenTelemetry: filtra pelo atributo service.name.
• Nome do intervalo: nome do intervalo.
• Estado do intervalo: o estado do pedido. Para informações sobre os valores, consulte a documentação SpanStatus do OpenTelemetry.
• Duração: a duração do intervalo.
• Span kind: descreve as relações entre intervalos. Para obter informações acerca dos valores, consulte a documentação SpanKind do OpenTelemetry.
• Aplicação App Hub: filtra pelo gcp.apphub.application.id atributo do recurso.
• Serviço App Hub: filtra pelo gcp.apphub.service.idatributo do recurso.
• Carga de trabalho do App Hub: filtra pelo gcp.apphub.workload.id atributo do recurso.

Se quiser filtrar por um atributo que não esteja listado no painel Filtros de intervalo, use a barra Filtro.

Use a barra de filtros

A barra de Filtro permite-lhe aplicar um filtro com uma chave de filtro predefinida e um valor que selecionar, ou pode introduzir a chave e o valor.

Para adicionar um filtro, selecione Adicionar filtro e, de seguida, faça uma das seguintes ações:

• Selecione uma chave definida, como Nome do intervalo e, de seguida, selecione um valor no menu secundário.

• Selecione Adicionar filtro de atributo e, de seguida, adicione a chave e o valor personalizados. Se introduzir a sua própria chave de filtro, use a mesma sintaxe que uma chave para um atributo num intervalo.

  Por exemplo, para filtrar pelo identificador do anfitrião, defina a chave como host.id. Da mesma forma, para filtrar por código de estado, defina a chave como /http/status_code. Neste cenário, pode definir o valor como 200, o que resulta no filtro /http/status_code: 200. Para permitir que o filtro corresponda a qualquer valor, selecione Qualquer valor.

Encontre um rastreio por ID

Quando está a resolver problemas de um incidente ou uma falha, pode saber o ID de rastreio. Para explorar esse rastreio, faça o seguinte:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

3. Aceda à barra de ferramentas, clique em Visualização de página Pesquisar rastreio e introduza o ID de rastreio.

   Quando introduz um ID válido, o menu de sobreposição Detalhes é aberto e apresenta informações sobre o rastreio e os respetivos intervalos. Pode usar as opções nesse painel para explorar o rastreio. Por exemplo, pode pesquisar palavras-chave nos intervalos.

   Nota: se introduzir um ID de rastreio que não for encontrado, os dados de rastreio podem ser armazenados num projeto que não é pesquisado pela página do Explorador de rastreios ou pode não ter uma função do IAM que lhe permita ver os dados de rastreio. Para resolver estas falhas, identifique os projetos que armazenam os dados de rastreio. Para cada projeto, verifique se a sua função do IAM lhe permite ver dados de rastreio e, em seguida, certifique-se de que o elemento Âmbito está configurado para pesquisar todos os projetos que armazenam os seus dados de rastreio. Para mais informações, consulte o artigo Atualize a lista de projetos pesquisados para dados de rastreio.

Explore um rastreio

Para ver um rastreio ou um intervalo, faça o seguinte:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

   Pode demorar vários minutos após a gravação dos primeiros dados de rastreio num Google Cloud projeto antes de esses dados estarem disponíveis para visualização. Se não vir dados de rastreio apresentados após aguardar alguns minutos, significa que o seu projeto pode não ter dados para apresentar ou pode existir um problema de configuração. Para obter informações sobre como resolver estes problemas, consulte o artigo Resolução de problemas: não existem dados na interface de rastreio.

2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.

3. Efetue um dos seguintes passos:

   • Aceda à secção de tabelas da página Explorador de rastreios e selecione uma entrada da tabela que liste intervalos ou liste informações de resumo após agrupar os dados por serviço e nome do intervalo.

   • Aceda à barra de ferramentas da página Explorador de rastreios, clique em Visualização de páginas Pesquisar rastreio e introduza o ID do rastreio.

   O menu de sobreposição Detalhes é aberto e apresenta um rastreio e os respetivos intervalos:

   • A coluna Nome apresenta a hierarquia de chamadas e a primeira entrada inclui o ID do rastreio.
   • A coluna Serviço é extraída do atributo service.name do OpenTelemetry quando esse atributo é definido. Se esse atributo não estiver definido e o serviço estiver a ser executado no App Engine, é apresentado o nome do serviço do App Engine. Caso contrário, não é especificado nenhum serviço.
   • O comprimento da barra de latência é representativo do valor de latência.
   • A cor da barra de latência indica o estado. Uma barra de latência azul indica uma conclusão bem-sucedida, enquanto uma barra de latência vermelha indica que ocorreu um erro.
   • Um círculo numa barra de latência indica que uma entrada de registo ou um evento está associado ao intervalo. Para alterar este comportamento, use o menu Registos e eventos.

4. Opcional: pesquise o nome do intervalo, o nome do serviço e os atributos num rastreio através do campo Find in Trace (Encontrar no rastreio).

   Por exemplo, se introduzir GET, o texto no nome do intervalo, no nome do serviço ou no painel Atributos que apresenta GET, ignorando a capitalização, é realçado.

   Não pode pesquisar através de uma expressão regular nem pesquisar registos, eventos ou metadados.

5. Para ver os detalhes de um intervalo específico, selecione o intervalo e veja os respetivos atributos e eventos. Consulte a secção seguinte para ver mais informações.

Veja atributos e eventos

Esta secção descreve como ver etiquetas, registos e eventos.

Ver etiquetas

Para ver as etiquetas anexadas ao intervalo, aceda ao separador Atributos. Para obter informações sobre etiquetas, consulte o artigo Etiquetas de rastreio.

Veja as informações da aplicação

Pré-visualização

Este produto ou funcionalidade está sujeito aos "Termos de Ofertas de Pré-GA" na secção Termos Gerais do Serviço dos Termos Específicos do Serviço. Os produtos e as funcionalidades pré-GA estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Os seguintes atributos de recursos específicos da aplicação podem ser anexados a dados de rastreio. Nesta secção, interprete a.b.{x,y} como a.b.x e a.b.y:

• gcp.apphub.application.{container,id,location}
• gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

Para encontrar os dados de rastreio da sua aplicação, faça o seguinte:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

2. Aceda ao painel Filtros de intervalo e adicione filtros para a sua aplicação do App Hub:

   • Para filtrar pelo ID da aplicação (gcp.apphub.application.id), use o menu Aplicação do App Hub.
   • Para filtrar pelo serviço de uma aplicação (gcp.apphub.service.id), use o menu Serviço do App Hub.
   • Para filtrar pela carga de trabalho de uma aplicação (gcp.apphub.workload.id), use o menu Carga de trabalho do App Hub.

Os atributos de recursos específicos da aplicação são anexados aos dados de rastreio quando as seguintes condições são verdadeiras:

• As suas aplicações do App Hub usam recursos suportados Google Cloud .
• Instrumenta uma aplicação com o OpenTelemetry e envia os dados de rastreio recolhidos da sua aplicação para o seu projeto através do Google Cloud ponto final OTLP.
• Os dados enviados para o seu projeto incluem atributos de recursos do OpenTelemetry que identificam os recursos suportados Google Cloud usados pela sua aplicação. Os atributos têm de incluir o seguinte:
  • cloud.account.id
  • Uma de cloud.{availability_zone,region}

  • Atributos específicos do recurso. Por exemplo, para uma carga de trabalho do Kubernetes, os intervalos têm de ter o k8s.cluster.name, o k8s.namespace e o tipo de implementação do Kubernetes definidos.

    Pode usar processadores para que o OpenTelemetry Collector anexe atributos específicos de recursos aos seus intervalos. Para saber mais, consulte resourcedetectionprocessor e k8sattributesprocessor.

  Quando instrumenta uma aplicação, o Google Cloud Observability usa os atributos de recursos anteriores e a API App Hub para identificar a sua aplicação App Hub. As etiquetas específicas da aplicação são adicionadas aos dados de rastreio quando uma aplicação é identificada.

Para mais informações acerca destes atributos, consulte as Google Cloud convenções semânticas do App Hub.

Veja registos e eventos

Para ver os registos e os eventos relacionados com o intervalo, aceda ao separador Registos e eventos.

Para ver uma entrada do registo, clique em Mostrar mais.

Também pode selecionar o botão Ver registos, que abre a página do Explorador de registos com a consulta definida para filtrar por um rastreio, um intervalo e um período específicos. Esta consulta pode não devolver entradas de registo.

Nota: a sua função de IAM no projeto ou no recurso que armazena as entradas do registo determina se pode ver as entradas do registo relacionadas. Por exemplo, as entradas de registo podem ser armazenadas num contentor de registos central, que se encontra num projeto Google Cloud diferente dos seus dados de rastreio. A sua função do IAM no recurso que armazena os dados determina se pode ver os dados de registo. Para mais informações, consulte o artigo Controlo de acesso para o Cloud Logging.

Veja eventos de IA generativa

Pré-visualização

Esta funcionalidade está sujeita aos "Termos de ofertas de pré-disponibilidade geral" na secção de Termos de Utilização Gerais dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Para ver eventos relacionados com agentes de IA generativa, use o separador GenAI. Este separador está disponível quando os intervalos enviados para o rastreio seguem as Convenções semânticas do OpenTelemetry para sistemas de IA generativa, o que resulta em mensagens cujos nomes começam por gen_ai.

A captura de ecrã seguinte ilustra como a página do Explorador de rastreios renderiza eventos de IA generativa:

Para saber mais sobre a aplicação de exemplo que gerou a captura de ecrã anterior, consulte o artigo Instrumente um agente LangGraph ReAct com o OpenTelemetry.

Os atributos são pares de chave-valor que descrevem alguma característica. Seguem-se exemplos de atributos de um sistema de IA generativa:

• gen_ai.system: identifica o sistema que fornece as capacidades de IA generativa.
• gen_ai.request.model: identifica o modelo ao qual o pedido é enviado.

Os eventos cujo nome começa por "gen_ai" descrevem normalmente entradas ou saídas individuais de um sistema de IA generativa. Estas entradas e saídas incluem comandos do sistema e do utilizador, entradas e saídas de ferramentas, e respostas do modelo. Seguem-se exemplos de eventos de um sistema de IA generativa:

• gen_ai.system.message: um evento que regista o comando do sistema enviado a um modelo de IA generativa. O comando do sistema fornece instruções ao modelo que, normalmente, não são vistas pelo utilizador final e que orientam a interpretação do modelo do comando do utilizador.
• gen_ai.user.message: um evento que regista o comando fornecido pelo utilizador que foi enviado para o modelo.
• gen_ai.assistant.message: um evento que regista a saída do modelo, que pode incluir o registo de uma invocação de ferramenta ou que pode conter uma saída de resposta textual. Uma mensagem pode incluir respostas candidatas que não são usadas pela aplicação.
• gen_ai.choice: Um evento usado para comunicar que resultados candidatos são usados pela aplicação.

Veja rastreios de pilha

Para ver rastreios de pilha, use o separador Rastreios de pilha.

Veja informações gerais e outros metadados

Para encontrar informações gerais sobre o intervalo e uma tabela de links para outros intervalos, consulte o separador Metadados e links. Estas informações incluem o seguinte:

• ID do intervalo: o ID do intervalo é um número inteiro de 64 bits diferente de 0. Para obter mais detalhes, consulte TraceSpan.
• ID do intervalo principal
• ID do projeto
• Hora de início e hora de fim
• Tabela que apresenta links para outros intervalos

Cada linha na tabela denominada Links apresenta um link entre o intervalo atual e outro intervalo. O campo Atributos apresenta os pares de chave-valor para o intervalo associado. O campo Trace tem um link para o rastreio do intervalo associado. Quando este campo contém Current trace, o intervalo com link está no mesmo rastreio que o intervalo atual. Caso contrário, o campo contém um ID de rastreio. Para obter informações sobre links, consulte a página de referência da API Links.

Veja tendências

Depois de implementar uma atualização numa aplicação, pode querer determinar se a atualização afetou a latência da resposta. Pode ver as tendências nos dados de latência definindo o seletor de intervalo de tempo de forma que os dados de latência sejam apresentados antes e depois da atualização.

Para ver tendências nos dados de rastreio, faça o seguinte:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
3. Opcional: adicione filtros para configurar os intervalos apresentados.
4. Aceda à barra de ferramentas e defina o seletor de intervalo de tempo para, pelo menos, duas semanas. Os dados de intervalos são armazenados durante 30 dias.
5. Opcional: altere a seleção do menu Vista de gráficos.

O que se segue?

• Crie e faça a gestão de âmbitos de rastreio
• Partilhe rastreios e intervalos
• Resolva problemas