Aspectos gerais do Cloud Trace

O Cloud Trace é um sistema de rastreamento distribuído para o Google Cloud que rastreia a latência de solicitações e ajuda a resolver gargalos de desempenho em serviços e aplicativos de IA generativa. Ao coletar dados de latência de serviços doGoogle Cloud e aplicativos instrumentados, o Trace ajuda você a entender como as solicitações são processadas em uma arquitetura de microsserviços e a identificar registros relevantes.

Com o Trace, é possível medir a latência de solicitações de ponta a ponta, comparar tendências de desempenho ao longo do tempo e identificar quais dependências downstream causam atrasos. Para um tutorial sobre como correlacionar traces e registros, consulte Como usar traces e registros juntos para análise de causa raiz.

Suporte ao ambiente

O Trace é executado no Linux nos seguintes ambientes:

Componentes

O Trace consiste em um cliente de rastreamento, que coleta traces e os envia ao projeto do Google Cloud . Em seguida, use o console doGoogle Cloud para visualizar e analisar a coleta de dados coletados pelo cliente de rastreamento. Para informações sobre o modelo de dados, consulte Traces e períodos.

Cliente de rastreamento

Um cliente de rastreamento coleta dados de latência e de período do aplicativo e os exporta para o projeto do Google Cloud . Dependendo do ambiente e dos requisitos, é possível coletar dados de trace de forma automática ou manual instrumentando o código do aplicativo.

interface de rastreamento

Para visualizar e analisar os dados de período, use as páginas Trace Explorer e Análise de Observabilidade no console doGoogle Cloud :

  • Explorador de traces: exibe informações agregadas sobre os dados de trace e permite examinar traces individuais em detalhes. Os dados de latência agregados são mostrados em um mapa de calor, que pode ser analisado com o ponteiro. Para restringir os dados exibidos, adicione filtros. Também é possível visualizar e analisar períodos e traces individuais:

  • Análise de Observabilidade: oferece uma interface de consulta SQL. As consultas podem mesclar os dados de trace e de registro, e os resultados podem ser visualizados como uma tabela ou um gráfico. É possível usar o BigQuery para analisar os dados de trace se você criar um conjunto de dados vinculado do BigQuery. Para mais informações, consulte Consultar e analisar traces.

Configurações com rastreamento automático

As configurações a seguir capturam automaticamente os dados de trace:

  • Ambiente padrão do App Engine

  • Cloud Run functions e Cloud Run

    Para solicitações HTTP de entrada e saída, os dados de latência são enviados automaticamente para o Trace.

Instrumentar um aplicativo

Instrumente seu aplicativo para coletar informações específicas que ajudam a entender o desempenho dele e solucionar falhas. Vários frameworks de instrumentação de código aberto coletam dados de registro, métrica e trace e podem enviá-los a qualquer fornecedor, incluindo o Google Cloud. Para seus aplicativos de agentes, alguns frameworks podem coletar seus comandos e respostas ou transmitir contexto que permite o rastreamento de algumas chamadas remotas de servidores MCP do Google Cloud.

Para instrumentar seu aplicativo, recomendamos o uso de um framework de instrumentação de código aberto e neutro em relação a fornecedores, como o OpenTelemetry, em vez de APIs ou bibliotecas de cliente específicas de fornecedores e produtos. Para mais informações sobre esses frameworks, consulte Observabilidade para desenvolvedores de aplicativos e Escolher uma abordagem de instrumentação.

As amostras de instrumentação que fornecemos usam o OpenTelemetry:

Embora seja possível usar as bibliotecas de cliente do Cloud Trace para instrumentar seu aplicativo, recomendamos o uso do OpenTelemetry. As bibliotecas do OpenTelemetry são preferíveis às bibliotecas de cliente do Trace porque são mais simples e exportam dados de trace no formato OTLP, definido pelo OpenTelemetry. Para mais informações, consulte Instrumentar para o Trace e Bibliotecas de cliente do Cloud Trace.

Cloud Trace e aplicativos agênticos

Para entender o comportamento dos seus aplicativos de agentes, configure-os para coletar comandos e respostas ou gerar períodos quando eles chamarem servidores MCP remotos do Google Cloud. Os comandos e as respostas ajudam a entender o raciocínio usado pelo aplicativo de agente. Os períodos que registram chamadas de ferramentas ajudam a confirmar a invocação de ferramentas, os status de chamada e as latências de solicitação.

Várias amostras de instrumentação mostram como configurar um aplicativo para coletar comandos e respostas. Essas amostras dependem do OpenTelemetry. Para mais informações, consulte Como instrumentar seus aplicativos de IA generativa.

Os servidores MCP do Google Cloud podem gerar períodos de trace. Para mais informações, consulte Investigar chamadas do MCP usando o Trace.

APIs que ingerem dados de trace

É possível enviar dados de trace para seu projeto usando a API Telemetry ou a API Cloud Trace. Recomendamos a API Telemetry pelos seguintes motivos:

  • A API é compatível com o ecossistema de código aberto do OpenTelemetry, e os limites dela costumam ser mais generosos do que os da API Cloud Trace, que é uma API Google Cloud proprietária.

  • Os dados de trace são armazenados em um formato que geralmente é consistente com os arquivos proto definidos pelo OTLP. Alguns campos podem ser convertidos de um tipo de dados específico do OpenTelemetry para um tipo de dados JSON antes do armazenamento. Para informações sobre o formato de armazenamento, consulte Esquema para dados de trace.

  • Para a exportação de dados de trace baseada em coletor, sua instrumentação não depende de um exportador específico do Google Cloud.

  • Alguns recursos, como o Monitoramento de Aplicativos, dependem de informações que só estão disponíveis quando você envia dados de trace para a API Telemetry.

Para impedir que o projeto do Google Cloud armazene dados de trace, desative a API Cloud Trace. A desativação da API Cloud Trace tem os seguintes efeitos:

  • Os serviços doGoogle Cloud não enviam dados de trace para seu projeto.
  • OGoogle Cloud responde às solicitações enviadas a um endpoint de API Cloud Trace com um código de erro.
  • O Google Cloud Observability descarta os dados de trace enviados ao endpoint de API Telemetry específico para traces. Não desative a API Telemetry, porque ela pode receber dados de registro, métrica e trace.

Se você gerencia uma organização e quer impedir o uso do Cloud Trace, crie uma restrição de política da organização.

Suporte do VPC Service Controls

Os serviços doGoogle Cloud e seus aplicativos podem enviar dados de trace para o projeto usando a API Cloud Trace ou a API Telemetry. Os serviços de visualização fornecidos pelo Cloud Trace usam a API Cloud Trace para buscar os dados de trace que exibem:

  • O Cloud Trace é um serviço compatível com o VPC Service Controls. O nome do serviço do Trace é cloudtrace.googleapis.com. Para detalhes e limitações, consulte Produtos compatíveis: Cloud Trace.

  • A API Telemetry é um serviço compatível com o VPC Service Controls. O nome do serviço é telemetry.googleapis.com. Para detalhes e limitações, consulte Produtos compatíveis: API Telemetry.

Para definir padrões que especificam a região do Google Cloud em que os dados de trace são armazenados e se uma chave gerenciada pelo cliente criptografa os dados, use a API Observability. Você também usa essa API para configurar conjuntos de dados vinculados do BigQuery, que permitem consultar seus dados de trace usando os serviços do BigQuery, e para configurar escopos de trace, que permitem agregar dados de trace armazenados em vários projetos.

  • A API Observability é um serviço compatível com o VPC Service Controls. O nome do serviço é observability.googleapis.com. Para detalhes e limitações, consulte Produtos compatíveis: API Observability.

Para ver mais informações, consulte os seguintes tópicos:

Cloud Trace e residência de dados

Se você estiver usando o Assured Workloads porque tem requisitos de residência de dados ou nível de impacto 4 (IL4), não use a API Cloud Trace para enviar períodos de trace.

Para impedir que o projeto do Google Cloud armazene dados de trace, desative a API Cloud Trace. Não desative a API Telemetry, porque ela pode receber dados de registro, métrica e trace.

Retenção de traces

Categoria Período de armazenamento
Períodos armazenados no bucket _Trace 30 dias

Papéis do IAM

O Cloud Trace usa o Identity and Access Management (IAM) para controlar o acesso aos recursos. Para uma lista de papéis da API Cloud Trace e da API Telemetry, consulte Controlar o acesso com o IAM.

Como a API Telemetry é uma API de consumidor, para enviar dados a ela, é necessário especificar um projeto de cota e conceder à conta de serviço do aplicativo permissão para usar essa cota. Para mais informações, consulte API Telemetry: autenticação.

A seguir