MCP-Aufrufe mit Trace untersuchen

Cloud Trace erfasst und zeigt Daten wie Toolaufrufe, Methodenaufrufe sowie Eingabeaufforderungen und Antworten an, damit Sie das Verhalten Ihrer Agentenanwendungen besser verstehen. In diesem Dokument wird beschrieben, wie Sie eine Agentenanwendung konfigurieren, die Remote-MCP-Server (Model Context Protocol) von Google Cloud aufruft, damit diese Server Spans generieren können, in denen der Status der Aufrufe erfasst wird.

Ein Span erfasst eine einzelne Funktion oder einen einzelnen Vorgang, 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 daher 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 MCP-Servern von Google Cloud können Ihre Agentenanwendungen 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-Befehl , 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-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 bestanden hat.

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

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

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) 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-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 den aufgerufenen Endpunkt. Das kann beispielsweise list_keys sein. Diese Namens konvention wird durch die OpenTelemetry Semantic Conventions 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. Setzen Sie den Wert des Filters auf tools/call.

Instrumentierungsbeispiele

Empfehlungen zur Instrumentierung finden Sie unter Instrumentierungsansatz auswählen.

In den von uns bereitgestellten Instrumentierungsbeispielen wird OpenTelemetry verwendet:

  • Beispiele für den Collector-basierten Export finden Sie unter:

    Diese Beispiele senden Trace-Daten an die Telemetry API.

  • 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, die zeigen, wie Sie eine Agentenanwendung konfigurieren, um Eingabeaufforderungen und Antworten zu erfassen, finden Sie unter Generative KI-Anwendungen instrumentieren.

  • Informationen dazu, welche Remote-MCP-Server von Google Cloud die Trace-Generierung unterstützen und wie Sie Ihre Anwendung so konfigurieren, dass diese Server Spans erstellen, finden Sie unter MCP-Aufrufe mit Trace untersuchen.