Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Aspectos gerais do Cloud Trace

O Cloud Trace, um sistema de geração de trace distribuído para o Google Cloud, ajuda você a entender quanto tempo leva para o aplicativo processar solicitações recebidas de usuários ou outros aplicativos e quanto tempo leva para concluir operações como chamadas RPC realizadas ao lidar com as solicitações. O Trace também pode ajudar durante o desenvolvimento de um serviço, de um aplicativo de agente ou na solução de uma falha. Por exemplo, você entende como as solicitações são processadas em uma arquitetura de microsserviços complicada e como identificar quais registros analisar.

Como o Trace recebe dados de latência de Google Cloud serviços como o App Engine e de aplicativos instrumentados, ele pode ajudar você a responder às seguintes perguntas:

Quanto tempo meu aplicativo leva para lidar com uma determinada solicitação?
Por que meu aplicativo está demorando tanto para processar uma solicitação?
Por que algumas das minhas solicitações demoram mais que outras?
Qual é a latência geral das solicitações para meu aplicativo?
A latência para meu aplicativo aumentou ou diminuiu ao longo do tempo?
O que eu posso fazer para reduzir a latência do aplicativo?
Quais são as dependências do meu aplicativo?

Se você quiser saber como usar o Trace para gerenciar seus aplicativos, leia o 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:

O Trace fornece bibliotecas de cliente para instrumentar seu aplicativo para capturar informações de rastreamento. Para instruções de configuração por linguagem, consulte Instrumentar para o Trace.

Configurações com rastreamento automático

Algumas configurações resultam na captura automática de dados de trace:

Ambiente padrão do App Engine

Os aplicativos Java 8, Python 2 e PHP 5 não precisam usar as bibliotecas de cliente do Trace. Esses ambientes de execução enviam automaticamente dados de latência ao Trace para solicitações a URIs de aplicativos. As solicitações incluem dados de latência para chamadas RPC de ida e volta para os serviços do App Engine. O Trace funciona com todas as APIs administradoras do App Engine, com exceção do Cloud SQL.
Funções do Cloud Run e Cloud Run

Para solicitações HTTP recebidas e enviadas, os dados de latência são enviados automaticamente ao Trace.

APIs que ingerem dados de trace

É possível enviar dados de trace ao projeto usando a API Telemetry ou a API Cloud Trace. Recomendamos a API Telemetry pelo seguinte motivo:

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 trace são armazenados em um formato geralmente consistente com os arquivos proto definidos pelo OpenTelemetry Line Protocol. Alguns campos podem ser convertidos de um tipo de dados específico do OpenTelemetry para um tipo de dados JSON antes do armazenamento. Para saber mais sobre o formato de armazenamento, consulte Esquema para dados de trace.
Para exportação de dados de trace baseada em coletores, a instrumentação não depende de um Google Cloud-exportador específico.
Alguns recursos, como o Application Monitoring, dependem de informações que só estão disponíveis quando você envia dados de trace para a API Telemetry.

Se você quiser impedir que o Google Cloud projeto armazene dados de trace, desative a API Cloud Trace. A desativação da API Cloud Trace resulta no seguinte:

Google Cloud Os serviços não enviam dados de trace ao projeto.
Google Cloud Responde a solicitações enviadas a um endpoint 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 trace.

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.

Cloud Trace e aplicativos de agente

Para entender o comportamento dos seus aplicativos agênticos, 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 aplicativos de IA generativa.

Para saber quais servidores MCP remotos do Google Cloud oferecem suporte à geração de trace e como configurar seu aplicativo para instruir esses servidores a criar spans, consulte Investigar chamadas de MCP usando o Trace.

Como instrumentar seu aplicativo

Instrumente seu aplicativo para coletar informações específicas que ajudem a entender a performance e solucionar falhas. Vários frameworks de instrumentação de código aberto coletam dados de registro, métrica e trace e podem enviar esses dados a qualquer fornecedor, incluindo Google Cloud. Para seus aplicativos agênticos, alguns frameworks podem coletar seus comandos e respostas ou transmitir o contexto que permite 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 neutra de fornecedores e de código aberto, como o OpenTelemetry, em vez de APIs específicas do fornecedor e do produto. ou bibliotecas de cliente. 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:

Para exemplos que usam uma exportação baseada em coletores, consulte o seguinte:
- Go
- Java
- Node.js
- Python
Esses exemplos enviam dados de trace para a API Telemetry.
Para informações sobre como usar uma exportação direta de dados de trace e enviar esses dados para a API Telemetry, consulte Migrar do exportador de trace para o endpoint OTLP.
Para exemplos que mostram como configurar um aplicativo de agente para coletar comandos e respostas, consulte Como instrumentar aplicativos de IA generativa.

Para saber quais servidores MCP remotos do Google Cloud oferecem suporte à geração de trace e como configurar o aplicativo para instruir esses servidores a criar períodos, consulte Investigar chamadas de MCP usando o Trace.

Também é possível usar bibliotecas de cliente do Cloud Trace para instrumentar seu aplicativo. No entanto, 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, que o OpenTelemetry define. Para saber mais, consulte Bibliotecas de cliente do Cloud Trace.

Componentes

O Trace é um cliente de rastreamento, que coleta traces e os envia ao seu Google Cloud projeto. É possível usar o Google Cloud console para visualizar e analisar os dados coletados pelo agente. Para informações sobre o modelo de dados, consulte Traces e períodos.

Cliente de rastreamento

Se uma biblioteca do OpenTelemetry estiver disponível para sua linguagem de programação, você poderá simplificar o processo de criação e envio de dados de trace usando o OpenTelemetry. Além de ser mais simples de usar, o OpenTelemetry implementa o processamento em lote, o que pode melhorar a performance.

Se não existir uma biblioteca do OpenTelemetry, instrumente seu código importando a biblioteca do SDK do Trace e usando a API Cloud Trace. A API Cloud Trace envia dados de trace ao Google Cloud projeto.

interface de rastreamento

É possível visualizar e analisar os dados de trace quase em tempo real na interface do Trace.

Para visualizar e analisar os dados de 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 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 exibidos, adicione filtros. Essa página também permite visualizar e explorar períodos e traces individuais:
- Para informações sobre como visualizar dados de trace armazenados em vários projetos, consulte Criar e gerenciar o escopo de trace.
- Para informações sobre como filtrar e visualizar os dados de trace, consulte Encontrar e explorar traces.
Análise de observabilidade: essa página permite executar consultas que realizam uma análise agregada dos períodos usando SQL. As consultas SQL também podem unir os dados de trace e de registro. É possível visualizar os resultados da consulta em formato tabular ou com gráficos. Se você criar um conjunto de dados vinculado, poderá usar BigQuery para analisar os períodos. Para mais informações, consulte Consultar e analisar traces.

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 aqueles como o telemetry.googleapis.com serviço, que também podem ingerir dados de trace.

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