MCP-Aufrufe mit Trace untersuchen

Sie können Ihre agentenbasierten Anwendungen, die Remote-Google Cloud-MCP-Server aufrufen, so konfigurieren, dass diese Server Spans generieren, in denen der Status der Aufrufe aufgezeichnet wird. Anschließend können Sie Cloud Trace verwenden, um Spans zu speichern und zu analysieren, in denen Toolaufrufe, Methodenaufrufe sowie Prompts und Antworten aufgezeichnet werden. So können Sie das Verhalten Ihrer agentenbasierten Anwendungen besser nachvollziehen.

Ein Span zeichnet eine einzelne Funktion oder einen einzelnen Vorgang auf, der Teil eines größeren End-to-End-Vorgangs ist. Ein Trace stellt einen einzelnen End-to-End-Vorgang dar und besteht aus Spans. Ein Trace enthält Informationen zur Reihenfolge der aufgerufenen Funktionen und zur Gesamtlatenz, während ein Span Status- und Latenzinformationen für eine bestimmte Funktion enthält.

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 agentenbasierten 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 Möglichkeit für KI-Agenten definiert, mit externen Tools, Datenquellen und Ressourcen zu kommunizieren und zu interagieren. Eine vollständige Liste der Produkte die einen MCP-Server bereitstellen, und Links zur zugehörigen Referenzdokumentation finden Sie unter Unterstützte Produkte.

Trace-Kontext an einen MCP-Server übergeben

Auf MCP-Referenzseiten wie der Dokumentation für list_log_entries finden Sie ein Beispiel für einen curl command 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 Toolnamen, 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 ein Feld traceparent. Das Format des Werts dieses Felds wird durch den World Wide Web Consortium (W3C) traceparent Header definiert. Der Wert enthält Folgendes:

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

Das Feld tracestate enthält anbieterspezifische Trace-Informationen.

Beschränkungen

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

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

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

MCP-Server, die Tracing unterstützen

In diesem Abschnitt werden die Remote-Google- und Google Cloud -MCP-Server 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 Telemetriedaten an Ihr Google Cloud Projekt gesendet werden. 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-Google- und Google Cloud -MCP-Server, 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 MCP-Referenz für Cloud Logging
Cloud Monitoring MCP-Referenz für Cloud Monitoring
Maps Grounding Lite MCP-Referenz für Maps Grounding Lite
GKE MCP-Referenz für GKE
Cloud Run MCP-Referenz für Cloud Run
Compute Engine MCP-Referenz für Compute Engine
Google Security Operations MCP-Referenz für Google SecOps
AlloyDB for PostgreSQL MCP-Referenz für AlloyDB for PostgreSQL
Agent Search MCP-Referenz für Agent Search
Cloud SQL
BigQuery MCP-Referenz für BigQuery
Personalized Service Health MCP-Referenz für Personalized Service Health
Cloud Billing MCP-Referenz für Cloud Billing
Richtlinien-Fehlerbehebung MCP-Referenz für die Richtlinien-Fehlerbehebung

Anwendung konfigurieren

Sie können jedes Framework oder SDK verwenden, das den Trace-Kontext über das _meta Feld übergibt. Dazu gehören Frameworks und SDKs, die die OpenTelemetry Semantic Conventions 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 anzusehen. Auf dieser Seite können Sie aggregierte Informationen zu Ihren Trace-Daten ansehen und einzelne Traces und Spans untersuchen. Weitere Informationen finden Sie unter Traces suchen und untersuchen.

Wenn Sie Spans ansehen möchten, die von MCP-Servern geschrieben wurden, filtern Sie Ihre Trace-Daten nach dem Spannamen. Einige Remote-Google Cloud-MCP-Server 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 Namens konvention wird durch die OpenTelemetry Semantic Conventions für MCP definiert.

Verwenden Sie die Filterleiste, um diese Spans zu finden, und fügen Sie einen Attributfilter für mcp.method.name hinzu. Setzen Sie den Wert des Filters auf tools/call. 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.

In den von uns bereitgestellten Instrumentierungsbeispielen wird OpenTelemetry verwendet:

  • Beispiele für einen auf Collector basierenden Export finden Sie unter:

    In diesen Beispielen werden Messwert- und Trace-Daten im OpenTelemetry Protocol-Format (OTLP) mit der Telemetry API an Ihr Projekt gesendet. In den Beispielen wird ein Google Cloud Exporter für Logdaten verwendet.

  • Informationen zur Verwendung eines direkten Exports von Trace-Daten und zum Senden dieser Daten an die Telemetry API finden Sie unter Vom Trace-Exporter zum OTLP-Endpunkt migrieren.

  • Beispiele, in denen gezeigt wird, wie Sie eine agentenbasierte Anwendung so konfigurieren, dass Prompts und Antworten erfasst werden, finden Sie unter Generative KI-Anwendungen instrumentieren.