MCP-Aufrufe mit Trace untersuchen

Mit Cloud Trace können Sie das Verhalten und die Leistung von agentischen Anwendungen analysieren, die Remote-MCP-Server von Google Cloud aufrufen. Sie können Ihre Anwendung so instrumentieren, dass Prompts, Antworten und Methodenaufrufe aufgezeichnet werden, während Remote-MCP-Server Spans für Toolaufrufe generieren. Ein Trace erfasst den gesamten Vorgang, um Aufrufsequenzen und die Gesamtlatenz anzuzeigen, während einzelne Spans Status- und Zeitdetails für bestimmte Funktionen liefern.

Tools

Mit Tools kann ein Agent Informationen außerhalb seiner Trainingsdaten erfassen, in der Regel durch Interaktion mit externen APIs. Mit Google Cloud-MCP-Servern können Ihre agentischen Anwendungen Tools aufrufen, die Google Cloud -API-Methoden aufrufen. Ihre Anwendung kann beispielsweise das Tool list_log_entries aufrufen, um aktuelle Logdaten abzurufen.

Das Model Context Protocol (MCP) ist eine Spezifikation, die eine standardisierte Methode für KI-Agenten definiert, um mit externen Tools, Datenquellen und Ressourcen zu kommunizieren und zu interagieren. Eine vollständige Liste der Produkte, die einen MCP-Server bereitstellen, sowie Links zu ihrer Referenzdokumentation finden Sie unter Unterstützte Produkte.

Wie der Trace-Kontext an einen MCP-Server übergeben wird

Auf den MCP-Referenzseiten, z. B. in der Dokumentation für list_log_entries, finden Sie einen Beispielbefehl curl, mit dem Sie HTTP-Anfragen an das Tool senden können. Die in der Anfrage gesendete JSON-Nutzlast sieht in etwa so aus:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "NAME",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "id": 1
}

Der Wert des Felds name enthält den Namen des Tools, z. B. list_log_entries. Das Feld arguments enthält die Informationen, die für den Vorgang erforderlich sind, um die Anfrage abzuschließen.

Der MCP-Standard definiert ein _meta-Feld, mit dem Clients und Server Metadaten an ihre Interaktionen anhängen können. Clients und Server können dieses Feld verwenden, um den Trace-Kontext zu übergeben:

{
  "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
}

Die _meta-Daten enthalten das Feld traceparent. Das Format des Werts dieses Felds wird durch den traceparent-Header des World Wide Web Consortium (W3C) definiert. Der Wert umfasst Folgendes:

  • Version der traceparent-Spezifikation (00).
  • ID des Trace (TRACE_ID).
  • ID des aufrufenden Span (PARENT_SPAN_ID).
  • Gibt an, ob der aufrufende Span die Anfrage (SAMPLED_FLAG) erfasst hat. Dieses Feld hat den Wert 01, wenn die Anfrage erfasst wurde, und 00, wenn sie nicht erfasst wurde.

Das Feld tracestate enthält anbieterspezifische Tracing-Informationen.

Beschränkungen

  • Der Trace-Kontext muss dem W3C-Trace-Kontext-Standard entsprechen und das Flag sampled muss auf 1 gesetzt sein.

  • Remote-MCP-Server von Google Cloud können einen einzelnen Span für einen tools/call-Vorgang generieren, aber keine Spans für andere Vorgangstypen oder untergeordnete Spans für den tools/call-Vorgang.

  • Remote-MCP-Server von Google Cloud generieren nur dann einen Span, wenn die Anfrage authentifiziert und autorisiert ist und andere interne Prüfungen besteht.

MCP-Server, die Tracing unterstützen

In diesem Abschnitt werden die Remote-MCP-Server von Google und Google Cloud aufgeführt, die Tracing unterstützen. Außerdem wird beschrieben, wie Ihre selbst gehosteten MCP-Server Trace-Spans generieren können.

Selbst gehostete Server

Wir empfehlen, Ihre selbst gehosteten MCP-Server so zu instrumentieren, dass sie Telemetriedaten an Ihr Google Cloud -Projekt senden. Wenn Sie Python verwenden, kann die Instrumentierung Spans für tools/call-Vorgänge generieren. Weitere Informationen finden Sie unter Selbst gehosteten MCP-Server mit OpenTelemetry instrumentieren.

Remote-MCP-Server von Google und Google Cloud , die Tracing unterstützen

Die folgenden Produkte enthalten eine Integration, mit der ihr Remote-MCP-Server einen Trace-Span für einen tools/call-Vorgang generieren kann:

Produkt Referenz
Cloud Logging Cloud Logging MCP-Referenz
Cloud Monitoring Cloud Monitoring-MCP-Referenz
Maps Grounding Lite Maps Grounding Lite MCP-Referenz
GKE GKE-MCP-Referenz
Cloud Run Cloud Run-MCP-Referenz
Compute Engine Compute Engine-MCP-Referenz
Google Security Operations Google SecOps MCP-Referenz
AlloyDB for PostgreSQL AlloyDB for PostgreSQL MCP-Referenz
Agentensuche MCP-Referenz für die Agentensuche
Cloud SQL
BigQuery BigQuery MCP-Referenz
Personalized Service Health MCP-Referenz für Personalized Service Health
Cloud Billing Cloud Billing-MCP-Referenz
Policy Troubleshooter MCP-Referenz für Policy Troubleshooter
Managed Service for Apache Airflow Managed Service for Apache Airflow MCP-Referenz
Datastream Datastream-MCP-Referenz
Policy Analyzer Policy Analyzer MCP-Referenz
Einheitliche Wartung MCP-Referenz für die einheitliche Wartung
Identity and Access Management Identity and Access Management MCP-Referenz
Organisationsrichtliniendienst MCP-Referenz für den Organisationsrichtliniendienst
Spanner Spanner-MCP-Referenz
Security Command Center Security Command Center MCP-Referenz

Anwendung konfigurieren

Sie können jedes Framework oder SDK verwenden, das den Trace-Kontext über das Feld _meta übergibt. Dazu gehören Frameworks und SDKs, die die semantischen OpenTelemetry-Konventionen für MCP unterstützen.

Sie können beispielsweise das Agent Development Kit (ADK)-Framework verwenden. Weitere Informationen finden Sie unter ADK-Anwendungen mit OpenTelemetry instrumentieren.

Spans ansehen

Verwenden Sie den Trace Explorer, um Ihre Trace-Daten aufzurufen. Auf dieser Seite können Sie zusammengefasste Informationen zu Ihren Trace-Daten aufrufen und einzelne Traces und Spans untersuchen. Weitere Informationen finden Sie unter Traces finden und ansehen.

Wenn Sie von MCP-Servern geschriebene Spans ansehen möchten, filtern Sie Ihre Trace-Daten nach dem Span-Namen. Einige Remote-MCP-Server von Google Cloud können beispielsweise einen Trace-Span generieren, wenn sie einen tools/call-Vorgang empfangen. Diese Spans haben die folgende Namenskonvention:

tools/call NAME

Im vorherigen Ausdruck bezieht sich NAME auf das aufgerufene Tool, z. B. list_keys. Diese Namenskonvention wird durch die semantischen OpenTelemetry-Konventionen für MCP definiert.

Verwenden Sie die Filterleiste und fügen Sie einen Attributfilter für mcp.method.name hinzu, um diese Spans zu finden. Legen Sie den Wert des Filters auf tools/call fest. Ausführliche Informationen zu diesen Schritten finden Sie unter Aufrufe an Remote-MCP-Server ansehen.

Instrumentierungsbeispiele

Empfehlungen zur Instrumentierung finden Sie unter Instrumentierungsansatz auswählen.

Die von uns bereitgestellten Instrumentierungsbeispiele verwenden OpenTelemetry: