Aspectos gerais do Cloud Trace

O Cloud Trace é um sistema de rastreamento distribuído para Google Cloud que acompanha 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 Google Cloud serviços e aplicativos instrumentados, o Trace ajuda a entender como as solicitações são processadas em uma arquitetura de microsserviços e a identificar registros relevantes.

O Trace ajuda você a responder perguntas como estas:

  • Quanto tempo seu aplicativo leva para lidar com uma determinada solicitação?
  • Por que uma solicitação leva muito tempo para ser concluída?
  • Por que algumas solicitações levam mais tempo do que outras?
  • Qual é a latência geral das solicitações para seu aplicativo?
  • A latência do aplicativo aumentou ou diminuiu ao longo do tempo?
  • Como você pode reduzir a latência do aplicativo?
  • Quais são as dependências do seu aplicativo?

Para informações sobre como usar traces e registros juntos para análise da causa raiz, consulte a postagem do blog Solução de problemas de aplicativos distribuídos: uso de traces e registros juntos para análise da causa raiz.

Para informações sobre como criar um perfil do aplicativo, consulte Cloud Profiler.

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 seu Google Cloud projeto. Em seguida, é possível usar o Google Cloud console para visualizar e analisar os 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 período do aplicativo e os exporta para seu Google Cloud projeto. Dependendo do 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 visualizar e analisar os dados do período, use as páginas Explorador de traces e Análise de observabilidade no Google Cloud console:

  • Explorador de traces: mostra informações agregadas sobre os dados de rastreamento 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 exibidos, adicione filtros. Também é possível visualizar e explorar períodos e traces individuais:

  • Análise de observabilidade: fornece uma interface de consulta SQL. As consultas podem unir os dados de rastreamento e registro, e é possível visualizar os resultados da consulta como uma tabela ou um gráfico. É possível usar o BigQuery para analisar os dados de rastreamento 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 dados de rastreamento automaticamente:

  • Ambiente padrão do App Engine

    • Os ambientes de execução de primeira geração interceptam e enviam automaticamente períodos de rastreamento para o Cloud Trace. Para mais informações, consulte Visão geral dos serviços agrupados 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 recebidas e enviadas, os dados de latência são enviados automaticamente para o Trace.

Instrumentar um aplicativo

Instrumente o aplicativo para coletar informações específicas que ajudem a entender o desempenho e resolver falhas. Vários frameworks de instrumentação de código aberto coletam dados de registro, métrica e rastreamento e podem enviar esses dados a qualquer fornecedor, incluindo Google Cloud. Para aplicativos de agente, alguns frameworks podem coletar comandos e respostas ou transmitir um contexto que permita o rastreamento de algumas chamadas de servidores MCP remotos do Google Cloud.

Para instrumentar seu aplicativo, recomendamos que você use uma estrutura de instrumentação de código aberto e neutra de 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.

Os exemplos de instrumentação que fornecemos usam OpenTelemetry:

Embora seja possível usar bibliotecas de cliente do Cloud Trace para instrumentar seu aplicativo, recomendamos o uso de 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 para o Cloud Trace.

Cloud Trace e aplicativos de agente

Para entender o comportamento dos aplicativos de agente, configure-os para coletar comandos e respostas ou para gerar períodos quando eles chamam 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 da ferramenta, 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. Esses exemplos 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 rastreamento. Para mais informações, consulte Investigar chamadas de 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 geralmente são mais generosos do que os limites d a API Cloud Trace, que é uma API proprietária Google Cloud .

  • 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 exportação de dados de rastreamento baseada em coletor, a instrumentação não depende de um Google Cloud-exportador específico.

  • 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 Google Cloud projeto armazene dados de rastreamento, desative a API Cloud Trace. A desativação da API Cloud Trace tem os seguintes efeitos:

  • Google Cloud serviços 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 de 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étrica e rastreamento.

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

Suporte do VPC Service Controls

O Trace é um serviço compatível com o VPC Service Controls. O nome do serviço Trace é cloudtrace.googleapis.com. Todas as restrições do VPC Service Controls criadas para o serviço Trace se aplicam apenas a esse serviço. Essas restrições não se aplicam a outros serviços, incluindo serviços como o telemetry.googleapis.com serviço, que também podem ingerir dados de rastreamento.

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

Cloud Trace e residência de dados

Se você estiver usando 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 rastreamento.

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

Retenção de rastreamento

Categoria Período de armazenamento
Períodos armazenados no _Trace bucket 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 permissão à conta de serviço do aplicativo 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 de preços do Google Cloud Observability.

A seguir