MCP-Aufrufe mit Trace untersuchen

Cloud Trace erfasst und zeigt Daten wie Tool-Aufrufe, Methodenaufrufe sowie Prompts und Antworten an, damit Sie das Verhalten Ihrer Agent-basierten Anwendungen besser nachvollziehen können. In diesem Dokument wird beschrieben, wie Sie eine agentenbasierte Anwendung konfigurieren, die Remote-Google Cloud-MCP-Server aufruft, damit diese Server Spans generieren können, in denen der Status der Aufrufe aufgezeichnet wird.

In einem Span wird eine einzelne Funktion oder ein einzelner Vorgang aufgezeichnet, 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 Google Cloud MCP-Servern können Ihre Agentenanwendungen Tools aufrufen, die Google Cloud API-Methoden aufrufen. Ihre Anwendung kann beispielsweise das Tool list_log_entries aufrufen, um aktuelle Protokolldaten abzurufen.

Das Model Context Protocol (MCP) ist eine Spezifikation, die eine standardisierte Methode für die Kommunikation und Interaktion von KI-Agenten mit externen Tools, Datenquellen und Ressourcen definiert. Eine vollständige Liste der Produkte, die einen MCP-Server bereitstellen, sowie Links zur zugehörigen Referenzdokumentation finden Sie unter Unterstützte Produkte.

Weitergabe des Trace-Kontexts an einen MCP-Server

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 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 vom World Wide Web Consortium (W3C) im traceparent-Header definiert. Der Wert umfasst Folgendes:

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

Das Feld tracestate enthält anbieterspezifische Informationen zur Sendungsverfolgung.

Beschränkungen

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

  • Auf Remote-Google Cloud-MCP-Servern kann ein einzelner Span für einen tools/call-Vorgang generiert werden. Es werden jedoch keine Spans für andere Arten von Vorgängen oder untergeordnete Spans für den tools/call-Vorgang generiert.

  • Auf Remote-Google Cloud-MCP-Servern wird nur dann ein Span generiert, wenn die Anfrage authentifiziert und autorisiert wurde und andere interne Prüfungen bestanden hat.

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:

Anwendung konfigurieren

Sie können jedes Framework oder SDK verwenden, das den Trace-Kontext über das Feld _meta übergibt. Diese Frameworks und SDKs umfassen solche, die die OpenTelemetry Semantic Conventions for 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 sich zusammengefasste Informationen zu Ihren Trace-Daten ansehen und einzelne Traces und Spans untersuchen. Weitere Informationen finden Sie unter Traces finden und ansehen.

Wenn Sie Spans ansehen möchten, die von MCP-Servern geschrieben wurden, filtern Sie Ihre Trace-Daten nach dem Spannen-Namen. 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 den aufgerufenen Endpunkt. Das könnte beispielsweise so aussehen: list_keys. Diese Namenskonvention wird durch die OpenTelemetry Semantic Conventions for MCP definiert.

Verwenden Sie die Filterleiste und fügen Sie einen Attributfilter für mcp.method.name hinzu, um diese Zeiträume zu finden. Legen Sie den Wert des Filters auf tools/call fest.

Instrumentierungsbeispiele

Empfehlungen zur Instrumentierung finden Sie unter Instrumentierungsansatz auswählen.

In den von uns bereitgestellten Instrumentierungsbeispielen wird OpenTelemetry verwendet: