View a markdown version of this page

Pengaturan dan pengiriman telemetri - Batu Dasar Amazon AgentCore
Menyiapkan observabilitasMode pengiriman telemetriApa yang dibaca layanan dari rentangReferensiAgen sampel

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Pengaturan dan pengiriman telemetri

Agen Anda memancarkan rentang yang digunakan Amazon Bedrock AgentCore Evaluations untuk merekonstruksi setiap sesi. Untuk cara AgentCore merepresentasikan sesi, pelacakan, dan rentang, lihat Mem ahami observabilitas untuk sumber daya agen di. AgentCore

Untuk menilai sesi, layanan membutuhkan konten percakapan: permintaan model, penyelesaian model, dan input dan output alat. Di mana konten itu berada tergantung pada bagaimana agen Anda memberikan telemetri, dan itulah yang dijelaskan halaman ini.

Topik

Menyiapkan observabilitas

Instrumentasi agen Anda adalah salah satu bagian dari pembuatan telemetri yang dapat dibaca oleh layanan evaluasi. Agen Anda juga harus mengaktifkan pengamatan, sehingga ia mengekspor telemetri-nya ke Amazon. CloudWatch Selesaikan langkah-langkah berikut:

  1. Aktifkan Pencarian CloudWatch Transaksi Amazon. Evaluasi membutuhkannya dalam kedua mode pengiriman. Lihat Meng aktifkan AgentCore observabilitas.

  2. Aktifkan observabilitas untuk agen Anda, berdasarkan tempat Anda menghostingnya:

  3. Periksa mode pengiriman mana yang digunakan agen Anda, sehingga Anda tahu di mana telemetri Anda mendarat. Agen yang Anda buat pada atau setelah 20 Juli 2026 menggunakan telemetri terpadu secara default, dan agen yang Anda buat sebelum tanggal tersebut menggunakan telemetri terpisah. Telemetri terpadu membutuhkan ADOT versi 0.18.0 atau yang lebih baru (). aws-opentelemetry-distro>=0.18.0 Versi sebelumnya mengirim rentang ke grup aws/spans log bersama.

    Untuk agen pada AgentCore Runtime, Anda beralih mode dengan variabel UNIFIED_TRACES_DESTINATION_ENABLED lingkungan: setel ke true untuk telemetri terpadu, atau false untuk telemetri terpisah. Untuk variabel lingkungan, izin IAM, dan prosedur lengkap untuk setiap opsi hosting, lihat Tujuan rentang untuk agen yang dihosting di runtime Amazon Bedrock AgentCore .

Mengubah mode pengiriman tidak memindahkan telemetri yang AgentCore sudah dikirim. Rentang yang lebih lama tetap berada di grup log tempat mereka ditulis, sehingga layanan masih mengevaluasi sesi yang Anda rekam sebelum perubahan.

Mode pengiriman telemetri

AgentCore memberikan telemetri agen Anda dalam salah satu dari dua mode:

  • Telemetri terpadu (disarankan) menyatukan semuanya. Atribut yang membawa muatan model dan permintaan alat serta tanggapan tetap pada rentang, dan semua telemetri agen Anda masuk ke satu grup log.

  • Telemetri terpisah memisahkan keduanya. AWS Distro for OpenTelemetry (ADOT) memindahkan atribut tersebut dari rentang ke catatan terpisah, yang pergi ke grup log yang berbeda dari rentang.

AgentCore Evaluasi membaca kedua mode. Anda tidak memilih di antara mereka dalam layanan evaluasi, dan evaluator yang sama memberi Anda hasil yang sama dengan cara apa pun. Kami merekomendasikan telemetri terpadu, yang tersedia di semua Wilayah AWS komersial di mana AgentCore Runtime tersedia.

Telemetri terpadu (disarankan)

Dengan telemetri terpadu, semua telemetri agen Anda masuk ke satu grup log. Rentang masuk ke aliran spans log di grup log itu, di sebelah log agen sendiri dan keluaran konsol. Rentang menyimpan atribut yang membawa muatan model dan permintaan serta tanggapan alat, sehingga layanan membaca semua yang dibutuhkan dari rentang itu sendiri.

Telemetri terpadu: ADOT mengirimkan setiap rentang dengan kontennya ke satu grup log

Grup log mana yang memegang rentang tergantung di mana Anda meng-host agen:

  • Di Amazon Bedrock AgentCore Runtime: grup log agen,/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>. AgentCore mengatur ini untuk Anda.

  • Dihosting di luar AgentCore Runtime: grup log yang Anda beri nama dalam variabel OTEL_EXPORTER_OTLP_TRACES_HEADERS lingkungan.

Menyimpan rentang dan log di satu tempat membantu melampaui evaluasi. Anda dapat melihat jejak dan log bersama-sama, Anda dapat menulis kebijakan AWS Identitas dan Manajemen Akses (IAM) dan mengatur enkripsi kunci yang dikelola pelanggan untuk satu agen, dan Anda dapat mengekspor semua yang dihasilkan agen dengan berlangganan satu grup log.

Telemetri terpisah

Dengan telemetri terpisah, ADOT menghilangkan muatan besar dari rentang. Saat mengekspor setiap rentang, ia menarik atribut yang membawa muatan model dan permintaan dan respons alat, dan mengirimkannya sebagai catatan peristiwa terpisah, meninggalkan rentang dengan metadata dan atributnya yang lebih kecil. Catatan peristiwa hanya ada dalam mode ini, dan mereka mengikuti konven OpenTelemetry si peristiwa.

Setiap catatan peristiwa menautkan kembali ke rentangnya melalui spanId berbagi traceId dan, dan konten berada di catatanbody, misalnya di body.input.messages danbody.output.messages.

Telemetri terpisah: ADOT mengirimkan rentang ke aws/spans dan konten percakapan ke grup log agen sebagai catatan peristiwa

Kedua jenis rekaman kemudian pergi ke tempat yang berbeda:

  • Rentang masuk ke grup aws/spans log bersama. CloudWatch membuat grup log ini saat Anda mengaktifkan Pencarian Transaksi.

  • Catatan peristiwa masuk ke grup log terpisah. Pada AgentCore Runtime, itu adalah grup log agen, di aliran otel-rt-logs log, yang AgentCore disiapkan untuk Anda. Di luar AgentCore Runtime, itu adalah grup log yang Anda beri nama dalam variabel OTEL_EXPORTER_OTLP_LOGS_HEADERS lingkungan.

Untuk mengevaluasi sesi, layanan membaca rentang dari aws/spans dan mencocokkannya dengan catatan acara mereka.

Apa yang dibaca layanan dari rentang

Untuk setiap rentang dalam sesi, layanan melakukan hal berikut:

  1. Mencari tahu rentang seperti apa itu, berdasarkan atribut yang ditetapkan kerangka kerja. Rentang dapat berupa rentang agen invoke (menjalankan agen tingkat atas), rentang alat eksekusi (panggilan alat tunggal), atau rentang inferensi (panggilan model tunggal).

  2. Membaca nilai yang dibutuhkan, seperti prompt pengguna, respons agen, dan input dan output alat. Misalnya, prompt pengguna berasal dari pesan peran pengguna dalam input agen, dan respons agen berasal dari pesan asisten peran dalam output agen.

Atribut yang mengidentifikasi rentang selalu tetap pada rentang, di kedua mode pengiriman. Hanya konten percakapan yang bergerak. Tempat konten itu berada dalam rentang juga tergantung pada pustaka instrumentasi Anda: sebagian besar pustaka merekamnya sebagai atribut rentang, dan beberapa melampirkannya ke rentang sebagai peristiwa. Untuk setiap pustaka, halaman per-kerangka kerja mencantumkan atribut pengenal, katakanlah di mana konten berada, dan menampilkan rentang contoh untuk kedua mode.

Referensi

AgentCore Evaluasi dibangun berdasarkan OpenTelemetry spesifikasi berikut:

Agen sampel

Contoh berikut menunjukkan cara instrumen agen Strands yang dihosting di luar Amazon Bedrock AgentCore Runtime. Setiap contoh mengekspor telemetri ke Amazon CloudWatch menggunakan ADOT. Mereka fokus pada pengaturan observabilitas daripada API evaluasi. Contohnya menggunakan Strands, tetapi pola hosting dan telemetri-ekspor yang sama berlaku untuk kerangka kerja lain yang didukung, seperti. LangGraph