Menyelidiki panggilan MCP menggunakan Trace

Cloud Trace mengumpulkan dan menampilkan data, seperti panggilan alat, pemanggilan metode, serta perintah dan respons, untuk membantu Anda memahami perilaku aplikasi agentic. Dokumen ini menjelaskan cara mengonfigurasi aplikasi agentic yang memanggil server MCP Google Cloud jarak jauh agar server ini dapat membuat rentang yang mencatat status panggilan.

Rentang mencatat satu fungsi atau operasi yang merupakan bagian dari operasi end-to-end yang lebih besar. Trace mewakili satu operasi end-to-end dan terdiri dari rentang. Oleh karena itu, trace memberikan informasi tentang urutan fungsi yang dipanggil dan latensi keseluruhan, sedangkan rentang memberikan informasi status dan latensi untuk fungsi tertentu.

Tentang alat

Alat memungkinkan agen mengumpulkan informasi di luar data pelatihannya, biasanya dengan berinteraksi dengan API eksternal. Dengan server MCP Google Cloud, aplikasi agentic Anda dapat memanggil alat yang memanggil Google Cloud metode API. Misalnya, aplikasi Anda dapat memanggil alat list_log_entries untuk mengambil data log terbaru.

Model Context Protocol (MCP) adalah spesifikasi yang menentukan cara standar bagi agen AI untuk berkomunikasi dan berinteraksi dengan alat, sumber data, dan resource eksternal. Untuk mengetahui daftar lengkap produk yang menyediakan server MCP dan link ke dokumentasi referensinya, lihat Produk yang didukung.

Cara meneruskan konteks trace ke server MCP

Halaman referensi MCP, seperti dokumentasi untuk list_log_entries, memberikan contoh curl command yang dapat Anda gunakan untuk mengirim permintaan HTTP ke alat. Payload JSON yang dikirim dalam permintaan mirip dengan berikut:

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

Nilai kolom name mencantumkan nama alat, seperti list_log_entries. Kolom arguments berisi informasi yang diperlukan oleh operasi untuk menyelesaikan permintaan.

Standar MCP menentukan _metakolom, yang memungkinkan klien dan server melampirkan metadata ke interaksi mereka. Klien dan server dapat menggunakan kolom ini untuk meneruskan konteks trace:

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

Data _meta mencakup kolom traceparent. Format nilai kolom ini ditentukan oleh World Wide Web Consortium (W3C) traceparent header. Nilai ini mencakup hal berikut:

  • Versi spesifikasi traceparent (00).
  • ID trace (TRACE_ID).
  • ID rentang panggilan (PARENT_SPAN_ID).
  • Menentukan apakah rentang panggilan mengambil sampel permintaan (SAMPLED_FLAG). Kolom ini memiliki nilai 01 jika diambil sampelnya dan 00 jika tidak diambil sampelnya.

Kolom tracestate berisi informasi pelacakan khusus vendor.

Batasan

  • Konteks trace harus mengikuti standar Konteks Trace W3C, dan flag sampled harus ditetapkan ke 1.

  • Server MCP Google Cloud jarak jauh dapat membuat satu rentang untuk operasi tools/call, tetapi tidak membuat rentang untuk jenis operasi lain atau rentang turunan untuk operasi tools/call.

  • Server MCP Google Cloud jarak jauh hanya membuat rentang saat permintaan diautentikasi, diotorisasi, dan lulus pemeriksaan internal lainnya.

Server MCP yang mendukung pelacakan

Bagian ini mencantumkan server Google dan Google Cloud MCP jarak jauh yang mendukung pelacakan. Bagian ini juga menjelaskan cara server MCP yang dihosting sendiri dapat membuat rentang trace.

Server yang dihosting sendiri

Sebaiknya instrumentasikan server MCP yang dihosting sendiri untuk mengirim data telemetri ke project Anda Google Cloud . Jika Anda menggunakan Python, instrumentasi dapat membuat rentang untuk operasi tools/call. Untuk mengetahui informasi selengkapnya, lihat Menginstrumentasikan server MCP yang dihosting sendiri dengan OpenTelemetry.

Server MCP Google dan jarak jauh yang mendukung pelacakan Google Cloud

Produk berikut berisi integrasi yang memungkinkan server MCP jarak jauhnya membuat rentang trace untuk operasi tools/call:

Produk Referensi
Cloud Logging Referensi MCP Cloud Logging
Cloud Monitoring Referensi MCP Cloud Monitoring
Maps Grounding Lite Referensi MCP Maps Grounding Lite
GKE Referensi MCP GKE
Cloud Run Referensi MCP Cloud Run
Compute Engine Referensi MCP Compute Engine
Google Security Operations Referensi MCP Google SecOps
AlloyDB untuk PostgreSQL Referensi MCP AlloyDB untuk PostgreSQL
Agent Search Referensi MCP Agent Search

Cara mengonfigurasi aplikasi

Anda dapat menggunakan framework atau SDK apa pun yang meneruskan konteks trace menggunakan _meta kolom. Framework dan SDK ini mencakup yang mendukung Konvensi Semantik OpenTelemetry untuk MCP.

Misalnya, Anda dapat menggunakan framework Agent Development Kit (ADK). Untuk mempelajari lebih lanjut, lihat Menginstrumentasikan aplikasi ADK dengan OpenTelemetry.

Cara melihat rentang

Untuk melihat data trace, gunakan Trace Explorer. Halaman ini memungkinkan Anda melihat informasi gabungan tentang data trace dan menjelajahi trace dan rentang individual. Untuk mempelajari lebih lanjut, lihat Menemukan dan menjelajahi trace.

Untuk melihat rentang yang ditulis oleh server MCP, filter data trace menurut nama rentang. Misalnya, beberapa server MCP Google Cloud jarak jauh dapat membuat rentang trace saat menerima operasi tools/call. Rentang ini memiliki konvensi penamaan berikut:

tools/call NAME

Dalam ekspresi sebelumnya, NAME mengacu pada endpoint yang dipanggil. Misalnya, ini mungkin sesuatu yang mirip dengan list_keys. Konvensi penamaan ini ditentukan oleh Konvensi Semantik OpenTelemetry untuk MCP.

Untuk menemukan rentang ini, gunakan panel filter dan tambahkan filter atribut untuk mcp.method.name. Tetapkan nilai filter ke tools/call.

Contoh instrumentasi

Untuk rekomendasi instrumentasi, lihat Memilih pendekatan instrumentasi.

Contoh instrumentasi yang kami berikan menggunakan OpenTelemetry: