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.

A captura de ecrã seguinte ilustra como os dados de rastreio são apresentados:

Exemplo de apresentação de dados de rastreio.

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

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 usa a cor para representar o número de intervalos numa célula. Uma célula com muitos intervalos tem uma cor mais escura do que uma com poucos intervalos. A sugestão de cada célula apresenta a latência e outras informações. Também pode ver percentis de latência e informações sobre a taxa de intervalos.

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

  • Para restringir os intervalos apresentados, aplique filtros. Por exemplo, pode filtrar por serviço, aplicação, estado de erro e outras propriedades.

  • Para apresentar um rastreio específico, use a opção da barra de ferramentas.

Para identificar valores atípicos e ver detalhes de intervalos individuais, use a secção tabular:

  • Pode ordenar as linhas dos separadores Intervalos e Agrupados pelo cabeçalho de duração.

  • Para compreender quantos intervalos diferentes serviços estão a gerar, use o separador Agrupado. Cada linha corresponde a um serviço e a um nome de intervalo e, para cada entrada, são apresentadas estatísticas de latência.

Para explorar os detalhes de um intervalo ou um agrupamento, selecione a entrada de uma linha na secção tabular. É aberto um menu flutuante que apresenta o intervalo no contexto do respetivo rastreio. Nesta vista, pode explorar o intervalo, os respetivos atributos e ver eventos e dados de registo. Também pode pesquisar palavras-chave nos intervalos e atributos no rastreio.

Os dados de rastreio dos quais a página Explorador de rastreios depende do seguinte:

  • Os projetos nos quais foram pesquisados dados de rastreio. Por predefinição, o sistema só pesquisa o projeto selecionado pelo selecionador de projetos para encontrar 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 receber 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. Configure a página do Explorador de rastreios:

    1. 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 ou o projeto de gestão do App Hub.

    2. 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.

    3. 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. Os dados de intervalo são armazenados durante 30 dias.

  3. Explore o mapa térmico:

    • Use a cor para identificar tendências e valores atípicos. Uma célula com muitos intervalos tem uma cor mais escura do que uma com poucos intervalos.

    • Veja os detalhes da célula através da sugestão da célula. A sugestão apresenta o número de intervalos, a data e a hora, e o intervalo de tempo da célula.

  4. Explore os percentis de latência e as taxas de erro:

    • 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.

  5. Para encontrar valores atípicos, selecione o separador Intervalos e ordene a tabela por duração.

    Se quiser mais informações sobre um período específico, selecione-o. É aberto um menu flutuante que apresenta o intervalo no contexto do respetivo rastreio. Em seguida, pode explorar o intervalo e o rastreio.

  6. Para explorar o número de intervalos gerados para cada serviço, juntamente com informações estatísticas, selecione o separador Agrupado:

    • Cada linha destina-se a um serviço específico e a um nome de intervalo.
    • Pode ordenar as linhas pelo cabeçalho de duração.

    Se quiser mais informações sobre um agrupamento específico, selecione o nome do intervalo de uma linha. É aberto um menu de sobreposição que apresenta o intervalo no contexto do respetivo rastreio. Em seguida, pode explorar o intervalo e o rastreio.

  7. Para restringir os intervalos apresentados, adicione filtros. 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 do Explorador de rastreios são atualizados e mostram apenas os intervalos que correspondem a todos os filtros aplicados.

Filtre 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, aceda à barra de ferramentas, clique em Pesquisar rastreio e introduza o ID do 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.

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.id atributo 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 Filtrar 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.

Filtrar por aplicação

Os intervalos de rastreio gerados pela instrumentação que adicionou às suas aplicações podem incluir os seguintes atributos de recursos:

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

A página Explorador de rastreios inclui os seguintes filtros de intervalos cujos menus listam aplicações, serviços e cargas de trabalho registados no App Hub:

  • Aplicação App Hub: filtra pelo gcp.apphub.application.id atributo do recurso.
  • Serviço App Hub: filtra pelo gcp.apphub.service.id atributo do recurso.
  • Carga de trabalho do App Hub: filtra pelo gcp.apphub.workload.id atributo do recurso.

Para obter informações sobre como instrumentar a sua aplicação para que os intervalos de rastreio incluam atributos específicos da aplicação, consulte o artigo Instrumente para a monitorização de aplicações.

Explore um rastreio

Esta secção fornece informações sobre como pode explorar um intervalo no contexto do respetivo rastreio:

  1. Abra e configure a página Explorador de rastreios. Para obter informações acerca destes passos, consulte o artigo Veja dados de rastreio agregados.

  2. Para ver os detalhes de um intervalo ou um rastreio, faça o seguinte:

    • Aceda à secção de tabelas da página Explorador de rastreios e selecione uma entrada da secção tabular. Pode ordenar as linhas das tabelas por qualquer cabeçalho da tabela. Pode aplicar filtros para restringir os intervalos que as tabelas mostram.

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

    O menu de sobreposição Detalhes é aberto e apresenta um rastreio e os respetivos intervalos. São apresentados os detalhes do intervalo ou do rastreio que selecionou:

    • A coluna Nome apresenta a hierarquia de chamadas e a primeira entrada inclui o ID do rastreio. Esta coluna também pode incluir anotações que indicam se estão disponíveis eventos de IA generativa ou dados de registo.
    • 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.

  3. Para explorar o rastreio, faça o seguinte:

    • Use o ponteiro para selecionar diferentes intervalos. Quando seleciona um intervalo, os separadores na página são atualizados para mostrar os atributos, as entradas de registo e os eventos do intervalo.

    • Para pesquisar os intervalos no rastreio por palavras-chave, use o campo Localizar no rastreio.

      A pesquisa aplica-se apenas aos campos de nome do intervalo, nome do serviço e atributos. Só pode pesquisar por texto simples e não pode pesquisar registos, eventos nem metadados.

      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.

Veja atributos, entradas de registo e eventos

O menu de sobreposição Detalhes de um intervalo contém um separador para cada um dos seguintes elementos:

  • Atributos: este separador apresenta etiquetas anexadas a intervalos. Para obter informações sobre etiquetas, consulte o artigo Etiquetas de rastreio.

  • Registos e eventos: este separador apresenta os eventos e as entradas de registo cujos campos trace_id e span_id correspondem ao intervalo selecionado. Apenas são apresentadas as entradas de registo que tem autorização para ver.

    Para explorar uma entrada neste separador, clique em Mostrar mais.

    Se preferir usar a página Logs Explorer para ver os dados de registo, clique em Ver registos. A consulta está definida para filtrar para um rastreio, um intervalo e um período específicos.

  • Stacktraces: lista as stacktraces disponíveis.

  • Metadados e links: apresenta informações gerais sobre o intervalo:

    • 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. Para cada associação, esta tabela apresenta o seguinte:

      • Os pares de chave-valor para o intervalo associado.
      • O ID de rastreio do intervalo associado. Quando este campo apresenta Rastreio atual, o intervalo está a criar um link para outro intervalo no mesmo rastreio.

      Para obter informações sobre links, consulte a página de referência da API Links.

Os Detalhes também podem incluir um separador com a etiqueta Entradas/Saídas. Este separador apresenta eventos de IA generativa.

Veja eventos de IA generativa

Para ver eventos relacionados com agentes de IA generativa, use o separador Entradas/Saídas. Este separador apresenta eventos que seguem as convenções semânticas da GenAI do OpenTelemetry.

Existem duas configurações suportadas:

  • Comandos e respostas baseados em texto anexados aos intervalos como atributos, que são pares de chave-valor que descrevem alguma característica ou um evento. Por exemplo, o valor da chave gen_ai.system identifica o sistema que fornece as capacidades de IA generativa. As chaves dos atributos de IA generativa começam com gen_ai.

  • Comandos e respostas multimodais armazenados num contentor do Cloud Storage. O Cloud Trace identifica estes eventos correlacionando os seus dados de rastreio e registo. Para saber mais sobre as configurações suportadas, consulte o artigo Recolha e veja comandos e respostas multimodais.

A captura de ecrã seguinte ilustra como a página do Explorador de rastreios renderiza eventos de IA generativa baseados em texto anexados aos intervalos:

Apresentação de intervalos de rastreio.

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.

O que se segue?