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. Dort werden Spans gespeichert und analysiert, in denen Tool-Aufrufe, Methodenaufrufe sowie Prompts und Antworten aufgezeichnet werden. So können Sie das Verhalten Ihrer Agent-basierten Anwendungen besser nachvollziehen.
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
Tools ermöglichen es einem Agent, Informationen außerhalb seiner Trainingsdaten zu sammeln, in der Regel durch die 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 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.
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 JSON-Nutzlast, die in der Anfrage gesendet wird, 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 der aufrufende Bereich die Anfrage erfasst hat (SAMPLED_FLAG). Dieses Feld hat den Wert
01, wenn die Anfrage erfasst wurde, und00, 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 dentools/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.
MCP-Server, die das 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 konfigurieren, 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 das 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 – Referenz für MCP |
| GKE | GKE MCP-Referenz |
| Cloud Run | Cloud Run-MCP-Referenz |
| Compute Engine | Compute Engine – Referenz für MCP |
| Google Security Operations | Google SecOps MCP-Referenz |
| AlloyDB for PostgreSQL | Referenz zu AlloyDB for PostgreSQL MCP |
| Agent Search | Agent Search MCP-Referenz |
| Cloud SQL | |
| BigQuery | Referenz zu BigQuery MCP |
| Personalized Service Health | Referenz für Personalized Service Health MCP |
| Cloud Billing | Cloud Billing MCP-Referenz |
| Richtlinien-Fehlerbehebung | Referenz zum Policy Troubleshooter für MCP |
| Managed Service for Apache Airflow | Referenz für Managed Service for Apache Airflow MCP |
| Datastream | Datastream MCP reference |
| Policy Analyzer | Policy Analyzer – MCP-Referenz |
| Einheitliche Wartung | Referenz für Einheitliche Wartung MCP |
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) 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 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 das aufgerufene Tool, z. B. 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. 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 den Collector-basierten Export finden Sie unter:
In diesen Beispielen werden Messwert- und Trace-Daten, die dem OpenTelemetry Protocol (OTLP) entsprechen, mithilfe der Telemetry API an Ihr Projekt gesendet. In den Beispielen wird ein Google Cloud Exporter für Log-Daten 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 für die Konfiguration einer agentischen Anwendung zum Erfassen von Prompts und Antworten finden Sie unter Generative KI-Anwendungen instrumentieren.