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 berbasis agen Anda. Dokumen ini menjelaskan cara mengonfigurasi aplikasi agentik 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, rekaman aktivitas 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 metode API. Google Cloud 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 pelacakan ke server MCP

Halaman referensi MCP, seperti dokumentasi untuk list_log_entries, memberikan contoh perintah curl 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 kolom _meta, yang memungkinkan klien dan server melampirkan metadata ke interaksi mereka. Klien dan server dapat menggunakan kolom ini untuk meneruskan konteks rekaman aktivitas:

{
  "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 header traceparent World Wide Web Consortium (W3C). Nilai mencakup berikut ini:

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

Kolom tracestate berisi informasi pelacakan khusus vendor.

Batasan

  • Konteks rekaman aktivitas harus mengikuti standar Konteks Rekaman Aktivitas W3C, dan flag sampled harus disetel ke 1.

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

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

Server Google dan Google Cloud MCP jarak jauh yang mendukung pelacakan

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

Cara mengonfigurasi aplikasi Anda

Anda dapat menggunakan framework atau SDK apa pun yang meneruskan konteks rekaman aktivitas menggunakan kolom _meta. 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 Melengkapi aplikasi ADK dengan OpenTelemetry.

Cara melihat rentang

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

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

tools/call NAME

Dalam ekspresi sebelumnya, NAME merujuk 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 kolom 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:

  • Untuk sampel yang menggunakan ekspor berbasis pengumpul, lihat artikel berikut:

    Contoh ini mengirimkan data rekaman aktivitas ke Telemetry API.

  • Untuk mengetahui informasi tentang cara menggunakan ekspor langsung data rekaman aktivitas dan mengirimkan data tersebut ke Telemetry API, lihat Bermigrasi dari eksportir Trace ke endpoint OTLP.

  • Untuk sampel yang menunjukkan cara mengonfigurasi aplikasi berbasis agen untuk mengumpulkan perintah dan respons, lihat Cara menginstrumentasi aplikasi AI generatif Anda.

  • Untuk mempelajari server MCP Google Cloud jarak jauh mana yang mendukung pembuatan rekaman aktivitas, dan untuk mempelajari cara mengonfigurasi aplikasi Anda agar menginstruksikan server ini untuk membuat rentang, lihat Menyelidiki panggilan MCP menggunakan Trace.