O Cloud Trace permite analisar o comportamento e o desempenho de aplicativos agênticos que chamam servidores MCP remotos do Google Cloud. É possível instrumentar seu aplicativo para registrar comandos, respostas e invocações de métodos, enquanto os servidores MCP remotos geram períodos para chamadas de ferramentas. Um trace captura a operação de ponta a ponta para mostrar sequências de chamadas e latência geral, enquanto períodos individuais fornecem detalhes de status e tempo para funções específicas.
Sobre as ferramentas
As ferramentas permitem que um agente colete informações fora dos dados de treinamento, normalmente interagindo com APIs externas. Com os servidores MCP do Google Cloud, seus aplicativos agênticos podem chamar ferramentas que invocam métodos da API Google Cloud . Por exemplo, seu aplicativo pode chamar a ferramenta list_log_entries para buscar dados de registro recentes.
O Protocolo de Contexto de Modelo (MCP) é uma especificação que define uma maneira padronizada para os agentes de IA se comunicarem e interagirem com ferramentas, fontes de dados e recursos externos. Para uma lista completa de produtos que fornecem um servidor MCP e links para a documentação de referência, consulte Produtos compatíveis.
Como o contexto de traces é transmitido para um servidor MCP
As páginas de referência do MCP, como a documentação de
list_log_entries, fornecem um exemplo de comando curl
que pode ser usado para enviar solicitações HTTP à ferramenta. O payload JSON
enviado na solicitação é semelhante ao seguinte:
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "NAME",
"arguments": {
// provide these details according to the tool's MCP specification
}
},
"id": 1
}
O valor do campo name lista o nome da ferramenta, como list_log_entries.
O campo arguments contém as informações necessárias para que a operação
conclua a solicitação.
O padrão MCP define um campo _meta, que permite que clientes e
servidores anexem metadados às interações. Os clientes e servidores podem usar esse
campo para transmitir o contexto de traces:
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "NAME",
"arguments": {
// provide these details according to the tool's MCP specification
},
"_meta": {
"traceparent": "00-TRACE_ID-PARENT_SPAN_ID-SAMPLED_FLAG",
"tracestate": "Vendor specific information."
},
},
"id": 1
}
Os dados de _meta incluem um campo traceparent. O formato do valor desse campo é definido pelo cabeçalho traceparent do World Wide Web Consortium (W3C). O valor inclui o seguinte:
- Versão da especificação
traceparent(00). - ID do trace (TRACE_ID).
- ID do período de chamada (PARENT_SPAN_ID).
- Se o período de chamada amostrou a solicitação (SAMPLED_FLAG). Esse campo
tem um valor de
01quando amostrado e00quando não amostrado.
O campo tracestate contém informações de rastreamento específicas do fornecedor.
Limitações
O contexto de traces precisa seguir o padrão de contexto de traces do W3C, e a flag
sampledprecisa ser definida como 1.Os servidores MCP remotos do Google Cloud podem gerar um único período para uma operação
tools/call, mas não geram períodos para outros tipos de operações ou períodos filhos para a operaçãotools/call.Os servidores MCP remotos do Google Cloud geram um período somente quando a solicitação é autenticada, autorizada e passa por outras verificações internas.
Servidores MCP que oferecem suporte ao rastreamento
Nesta seção, listamos os servidores remotos do Google e do Google Cloud MCP que oferecem suporte ao rastreamento. Também descreve como os servidores MCP auto-hospedados podem gerar períodos de trace.
Servidores auto-hospedados
Recomendamos que você instrumente seus servidores MCP auto-hospedados para enviar dados de telemetria ao seu projeto do Google Cloud .
Se você usa Python, a instrumentação pode gerar períodos para operações tools/call. Para mais informações, consulte
Instrumentar um servidor MCP auto-hospedado com o OpenTelemetry.
Servidores remotos do Google e do Google Cloud MCP que oferecem suporte ao rastreamento
Os produtos a seguir contêm uma integração que permite que o servidor MCP remoto
gere um período de trace para uma operação tools/call:
Configurar seu aplicativo
É possível usar qualquer framework ou SDK que transmita o contexto de traces usando o
campo _meta. Esses frameworks e SDKs incluem aqueles que
oferecem suporte às convenções semânticas do OpenTelemetry para MCP.
Por exemplo, é possível usar o framework do Kit de Desenvolvimento de Agente (ADK). Para saber mais, consulte Instrumentar aplicativos do ADK com o OpenTelemetry.
Ver períodos
Para visualizar os dados de trace, use o Trace Explorer. Nessa página, é possível ver informações agregadas sobre os dados de trace e analisar traces e períodos individuais. Para saber mais, consulte Encontrar e explorar traces.
Para conferir os períodos gravados pelos servidores MCP, filtre os dados de trace pelo nome do período. Por exemplo, alguns servidores MCP remotos do Google Cloud podem gerar um período de trace quando
recebem uma operação tools/call. Esses períodos têm a seguinte convenção de nomenclatura:
tools/call NAME
Na expressão anterior, NAME se refere à ferramenta invocada, por
exemplo, list_keys. Essa convenção de nomenclatura é definida pelas convenções semânticas do OpenTelemetry para MCP.
Para encontrar esses períodos, use a barra de filtro e adicione um filtro de atributo para
mcp.method.name. Defina o valor do filtro como tools/call. Para mais informações sobre essas etapas, consulte Ver chamadas para servidores MCP remotos.
Amostras de instrumentação
Para recomendações de instrumentação, consulte Escolher uma abordagem de instrumentação.
As amostras de instrumentação que fornecemos usam o OpenTelemetry:
Para exemplos que usam uma exportação baseada em coletor, consulte:
Esses exemplos enviam dados de registro, métrica e trace que seguem o formato do protocolo OpenTelemetry (OTLP) para seu projeto usando a API Telemetry.
Para saber como usar uma exportação direta de dados de trace e enviá-los para a API Telemetry, consulte Migrar do exportador do Trace para o endpoint do OTLP.
Para exemplos que mostram como configurar um aplicativo agêntico para coletar comandos e respostas, consulte Observabilidade para desenvolvedores de agentes de IA.