É possível configurar seus aplicativos de agente que chamam servidores MCP remotos do Google Cloud para permitir que esses servidores gerem intervalos que registram o status das chamadas. Em seguida, use o Cloud Trace, que armazena e analisa intervalos que registram chamadas de ferramentas, invocações de métodos, comandos e respostas, para entender o comportamento dos seus aplicativos com agentes.
Um intervalo registra uma única função ou operação que faz parte de uma operação de ponta a ponta maior. Um trace representa uma única operação de ponta a ponta e é composto por intervalos. Portanto, um trace fornece informações sobre a sequência de chamadas de função e a latência geral, enquanto um período fornece informações de status e latência para uma função específica.
Sobre as ferramentas
Com as ferramentas, um agente pode coletar informações fora dos dados de treinamento, geralmente interagindo com APIs externas. Com os servidores MCP do Google Cloud, seus aplicativos de agente 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 registros recentes.
O Protocolo de Contexto de Modelo (MCP) é uma especificação que define uma maneira padronizada para 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 deles, consulte Produtos compatíveis.
Como o contexto de rastreamento é 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 a este:
{
"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 rastreamento:
{
"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 rastreamento (TRACE_ID).
- ID do intervalo de chamada (PARENT_SPAN_ID).
- Indica se o período de chamada fez amostragem da solicitação (SAMPLED_FLAG). Esse campo tem um valor de
01quando a amostragem é feita e00quando não é.
O campo tracestate contém informações de rastreamento específicas do fornecedor.
Limitações
O contexto de rastreamento precisa seguir o padrão W3C Trace Context, e a flag
sampledprecisa ser definida como 1.Servidores remotos do MCP do Google Cloud podem gerar um único intervalo para uma operação
tools/call, mas não geram intervalos para outros tipos de operações ou intervalos filhos para a operaçãotools/call.Os servidores MCP remotos do Google Cloud geram um intervalo somente quando a solicitação é autenticada, autorizada e passa por outras verificações internas.
Servidores MCP que oferecem suporte ao rastreamento
Esta seção lista os servidores remotos do Google e do Google Cloud MCP que oferecem suporte ao rastreamento. Também descreve como os servidores MCP autohospedados podem gerar intervalos de rastreamento.
Servidores auto-hospedados
Recomendamos instrumentar seus servidores MCP autohospedados para enviar dados de telemetria ao seu projeto Google Cloud .
Se você usa Python, a instrumentação pode gerar intervalos para operações de
tools/call. Para mais informações, consulte
Instrumentar um servidor MCP autohospedado com o OpenTelemetry.
Servidores remotos do Google e do Google Cloud MCP que oferecem suporte ao rastreamento
Os produtos a seguir têm uma integração que permite que o servidor MCP remoto gere um intervalo de rastreamento para uma operação tools/call:
Configurar seu aplicativo
É possível usar qualquer framework ou SDK que transmita o contexto de rastreamento usando o
campo _meta. Esses frameworks e SDKs incluem aqueles que
são compatíveis com as Convenções semânticas do OpenTelemetry para MCP.
Por exemplo, você pode usar o framework do Kit de Desenvolvimento de Agente (ADK). Para saber mais, consulte Instrumentar aplicativos do ADK com o OpenTelemetry.
Mostrar períodos
Para visualizar os dados de rastreamento, use o Explorador de rastreamento. Nela, você pode conferir informações agregadas sobre seus dados de trace e analisar traces e períodos individuais. Para saber mais, consulte Encontrar e analisar traces.
Para ver intervalos gravados por servidores MCP, filtre os dados de rastreamento pelo nome do intervalo. Por exemplo, alguns servidores remotos do MCP no Google Cloud podem gerar um intervalo de rastreamento 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 intervalos, use a barra de filtro e adicione um filtro de atributo para
mcp.method.name. Defina o valor do filtro como tools/call. Para informações detalhadas 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 o seguinte:
Essas amostras enviam dados de métricas e traces que seguem o formato do protocolo OpenTelemetry (OTLP) para seu projeto usando a API Telemetry. As amostras usam um exportador Google Cloud para dados de registro.
Para informações sobre como usar uma exportação direta de dados de rastreamento e enviar esses dados à API Telemetry, consulte Migrar do exportador do Trace para o endpoint OTLP.
Para ver exemplos de como configurar um aplicativo com agentes para coletar comandos e respostas, consulte Como instrumentar seus aplicativos de IA generativa.