Aspectos gerais do Cloud Trace

O Cloud Trace é um sistema de rastreamento distribuído para 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çosGoogle 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ção 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 Usar traces e registros juntos para análise da causa raiz.

Suporte ao ambiente

O rastreamento é executado no Linux nos seguintes ambientes:

Componentes

O Trace consiste em um cliente de rastreamento, que coleta traces e os envia ao seu projeto Google Cloud . Em seguida, use o consoleGoogle Cloud para conferir e analisar os dados coletados pelo cliente de rastreamento. Para informações sobre o modelo de dados, consulte Traces e intervalos.

Cliente de rastreamento

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

interface de rastreamento

Para conferir e analisar os dados de extensão, use as páginas Explorador de rastreamentos e Análise de observabilidade no console doGoogle Cloud :

  • Explorador de traces: mostra informações agregadas sobre seus 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 explorado com o ponteiro. Para restringir os dados mostrados, adicione filtros. Também é possível ver e analisar intervalos e rastreamentos individuais:

  • Análise de observabilidade: oferece uma interface de consulta SQL. Suas consultas podem unir dados de rastreamento e de registros, e você pode conferir os resultados como uma tabela ou um gráfico. Você pode usar o BigQuery para analisar seus dados de rastreamento se 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 dados de rastreamento automaticamente:

  • Ambiente padrão do App Engine

    • Os ambientes de execução de primeira geração interceptam e enviam automaticamente intervalos de rastreamento para o Cloud Trace. Para mais informações, consulte Visão geral dos serviços incluídos legados.

    • Os ambientes de execução de segunda geração capturam automaticamente a latência geral da solicitação e adicionam o cabeçalho HTTP X-Cloud-Trace-Context às solicitações. Para mais informações, consulte Programação de suporte do ambiente de execução.

  • Funções do Cloud Run e Cloud Run

    Para solicitações HTTP de entrada e saída, os dados de latência são enviados automaticamente ao 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étricas e traces e podem enviar esses dados a qualquer fornecedor, incluindo o Google Cloud. Para seus aplicativos generativos, alguns frameworks podem coletar seus comandos e respostas ou transmitir contexto que permite o rastreamento de algumas chamadas remotas dos servidores MCP do Google Cloud.

Para instrumentar seu aplicativo, recomendamos que você use 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 do fornecedor e do produto. Para informações sobre esses frameworks, consulte Instrumentação e observabilidade 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 usar o OpenTelemetry. As bibliotecas do OpenTelemetry são preferíveis às bibliotecas de cliente do Trace porque são mais simples e exportam dados de rastreamento no formato OTLP, que o OpenTelemetry define. 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 com agentes, configure-os para coletar comandos e respostas ou gerar intervalos quando eles chamarem servidores MCP do Google Cloud remotos. Os comandos e as respostas ajudam a entender o raciocínio usado pelo aplicativo com agente. Os intervalos que registram chamadas de ferramentas ajudam você a confirmar a invocação de ferramentas, os status de chamada e as latências de solicitação.

Vários exemplos 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 intervalos de rastreamento. Para mais informações, consulte Investigar chamadas do MCP usando o Trace.

APIs que ingerem dados de rastreamento

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

  • A API oferece compatibilidade com o ecossistema OpenTelemetry de código aberto, 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 rastreamento são armazenados em um formato 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 rastreamento.

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

  • Alguns recursos, como o Application Monitoring, dependem de informações que estão disponíveis apenas quando você envia dados de rastreamento para a API Telemetry.

Para impedir que seu projeto Google Cloud armazene dados de rastreamento, 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 rastreamento para seu projeto.
  • Google Cloud responde a solicitações enviadas a um endpoint de API Cloud Trace com um código do erro.
  • O Google Cloud Observability descarta os dados de trace enviados ao endpoint de API Telemetry específico do trace. Não desative a API Telemetry, porque ela pode receber dados de registro, métricas e rastreamento.

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

Google Cloud serviços e aplicativos podem enviar dados de rastreamento ao seu 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 rastreamento que mostram:

  • O Cloud Trace é um serviço compatível com o VPC Service Controls. O nome do serviço de rastreamento é cloudtrace.googleapis.com. Para mais 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 com suporte: API Telemetry.

Para definir padrões que especifiquem a Google Cloud região onde os dados de rastreamento são armazenados e se uma chave gerenciada pelo cliente criptografa os dados, use a API Observability. Você também pode usar essa API para configurar conjuntos de dados vinculados do BigQuery, que permitem consultar dados de rastreamento usando serviços do BigQuery, e para configurar escopos de rastreamento, que permitem agregar dados de rastreamento 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 intervalos de rastreamento.

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

Retenção de rastros

Categoria Período de armazenamento
Intervalos 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, o envio de dados para ela exige que você especifique um projeto de cota e conceda à conta de serviço do aplicativo permissão para usar essa cota. Para mais informações, consulte API Telemetry: autenticação.

Preços

Para saber mais sobre os preços do Cloud Trace, consulte a página Preços do Google Cloud Observability.

A seguir