Tambahkan observabilitas ke sumber daya Amazon Bedrock AgentCore Anda

Amazon Bedrock AgentCore menyediakan sejumlah metrik bawaan untuk memantau kinerja sumber daya untuk AgentCore runtime, memori, gateway, alat bawaan, dan jenis sumber daya identitas. Data default ini tersedia di Amazon CloudWatch. Untuk melihat berbagai data observabilitas di CloudWatch konsol, atau untuk menampilkan metrik runtime kustom untuk agen, Anda perlu menginstruksikan kode Anda menggunakan AWS Distro for Open Telemetry (ADOT) SDK.

Untuk melihat dasbor observabilitas di CloudWatch, buka halaman Amazon CloudWatch GenAi Observability.

Lihat bagian berikut untuk mempelajari lebih lanjut tentang mengonfigurasi sumber daya Anda untuk melihat metrik observabilitas di halaman observabilitas AI generatif CloudWatch konsol dan di Log. CloudWatch

Mengaktifkan observabilitas AgentCore

Untuk melihat metrik, rentang, dan jejak yang dihasilkan oleh AgentCore layanan, pertama-tama Anda harus menyelesaikan penyiapan satu kali untuk mengaktifkan Pencarian Transaksi Amazon CloudWatch . Untuk melihat rentang yang disediakan layanan untuk sumber daya memori, Anda juga perlu mengaktifkan penelusuran saat membuat memori. Lihat Mengaktifkan observabilitas untuk AgentCore runtime, memori, gateway, alat bawaan, dan sumber daya identitas untuk mempelajari lebih lanjut.

Bagian berikut menjelaskan cara melakukan tindakan penyiapan ini dan untuk mengaktifkan observabilitas dalam kode agen Anda.

Mengaktifkan Pencarian CloudWatch Transaksi

Anda dapat mengaktifkan CloudWatch Transaction Search baik dengan menggunakan CloudWatch konsol, atau dengan menggunakan API melalui AWS Command Line Interface (AWS CLI) atau salah satu SDK AWS .

Gunakan salah satu prosedur berikut untuk mengaktifkan Pencarian Transaksi.

Rentang tujuan untuk agen yang dihosting di runtime Amazon Bedrock AgentCore

Dengan AgentCore runtime, kemampuan Amazon Bedrock AgentCore, Anda dapat mengonfigurasi agen untuk mengirimkan rentangnya ke grup CloudWatch log Amazon yang sama dengan log agen. Dengan konfigurasi ini, bentang masuk ke aliran spans log/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>, bukan grup aws/spans log bersama. Anda dapat menyimpan bentang, log terstruktur, dan output standar bersama-sama dalam satu grup log per-agen, kontrol akses cakupan dan enkripsi ke agen individu, dan mengekspor telemetri dari satu lokasi.

Di AWS Wilayah yang didukung, agen yang baru dibuat menggunakan grup log agen sebagai tujuan rentang default. Agen yang dibuat sebelum Wilayah mendukung tujuan rentang terpadu menjaga grup aws/spans log bersama sebagai defaultnya.

Anda dapat mengganti default untuk agen individual dengan variabel UNIFIED_TRACES_DESTINATION_ENABLED lingkungan pada runtime agen Anda:

AgentCore Untuk mengirimkan bentang ke grup log agen, berikut ini harus benar:

Mengubah tujuan rentang tidak memindahkan data rentang yang ada. Rentang yang AgentCore sudah dikirimkan tetap berada di grup log asli mereka.

Mengaktifkan observabilitas dalam kode agen untuk agen AgentCore-hosted

Selain metrik yang dihasilkan layanan, AgentCore Anda juga dapat mengumpulkan rentang dan melacak data serta metrik khusus yang dipancarkan dari kode agen Anda.

Saat Anda menggunakan kerangka kerja agen seperti Strands, LangChain, atau CreWAI dengan pustaka instrumentasi pihak ketiga yang didukung, kerangka kerja itu sendiri dilengkapi dengan dukungan bawaan untuk konvensi semantik OTEL dan GenAI, dan juga dapat diinstrumentasi dengan paket instrumentasi otomatis seperti. opentelemetry-instrument-langchain Dimungkinkan juga untuk mengirim telemetri dan bentang konvensi semantik AI Generatif dengan mendefinisikan pelacak khusus. AgentCore mendukung penggunaan pustaka instrumentasi berikut dalam kerangka agen Anda:

Untuk melihat data ini di halaman observabilitas AI generatif CloudWatch konsol dan di Amazon CloudWatch, Anda perlu menambahkan SDK AWS Distro for Open Telemetry (ADOT) ke kode agen Anda.

Untuk menambahkan dukungan ADOT dan mengaktifkan AgentCore observabilitas, ikuti langkah-langkah dalam prosedur berikut.

Tambahkan observabilitas ke agen Anda AgentCore

Mengaktifkan observabilitas untuk agen yang dihosting di luar AgentCore

Untuk mengaktifkan observabilitas agen yang dihosting di luar AgentCore runtime, pertama-tama ikuti langkah-langkah di bagian sebelumnya untuk mengaktifkan Penelusuran CloudWatch Transaksi dan tambahkan SDK ADOT ke kode Anda.

Jika Anda meng-host agen Anda di AWS Lambda, gunakan Lapisan AWS Lambda untuk di Distro untuk OpenTelemetry situs web. AWS OpenTelemetry Tambahkan layer ke fungsi Anda, dan kemudian atur variabel AWS_LAMBDA_EXEC_WRAPPER lingkungan ke/opt/otel-instrument. Lapisan kemudian mengotomatiskan fungsi Anda. Dengan pendekatan ini, Anda tidak perlu menambahkan aws-opentelemetry-distro paket atau menjalankan opentelemetry-instrument perintah yang dijelaskan sebelumnya.

Untuk agen yang berjalan di luar AgentCore runtime, Anda juga perlu membuat grup log agen yang Anda sertakan dalam variabel lingkungan Anda.

Konfigurasikan variabel AWS lingkungan Anda, lalu atur variabel lingkungan Telemetri Terbuka Anda seperti yang ditunjukkan pada berikut ini.

AWS variabel lingkungan

AWS_ACCOUNT_ID=<account id>
AWS_DEFAULT_REGION=<default region>
AWS_REGION=<region>
AWS_ACCESS_KEY_ID=<access key id>
AWS_SECRET_ACCESS_KEY=<secret key>

Variabel lingkungan OTEL

AGENT_OBSERVABILITY_ENABLED=true
OTEL_PYTHON_DISTRO=aws_distro
OTEL_PYTHON_CONFIGURATOR=aws_configurator # required for ADOT Python only
OTEL_RESOURCE_ATTRIBUTES=service.name=<agent-name>,aws.log.group.names=/aws/bedrock-agentcore/runtimes/<agent-id>,cloud.resource_id=<AgentEndpointArn:AgentEndpointName> # endpoint is optional
OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=runtime-logs,x-aws-metric-namespace=bedrock-agentcore
OTEL_EXPORTER_OTLP_TRACES_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/<agent-id>,x-aws-log-stream=spans # (Optional) Directs spans to your log group instead of the aws/spans log group. Requires ADOT version 0.18.0 or later.
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_TRACES_EXPORTER=otlp
OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false # AWS Lambda Layer for OpenTelemetry only: disables Application Signals
OTEL_LOGS_EXPORTER=otlp # AWS Lambda Layer for OpenTelemetry only: exports logs over OTLP
OTEL_METRICS_EXPORTER=awsemf # AWS Lambda Layer for OpenTelemetry only: exports metrics as CloudWatch EMF

Ganti <agent-name> dengan nama agen Anda dan <agent-id> dengan pengenal unik untuk agen Anda.

Dukungan ID Sesi

Untuk menyebarkan ID sesi, Anda perlu memanggil menggunakan pengenal sesi di bagasi OTEL:

from opentelemetry import baggage

ctx = baggage.set_baggage("session.id", session_id) # Set the session.id in baggage
attach(ctx) # Attach the context to make it active token

Mengaktifkan observabilitas untuk AgentCore runtime, memori, gateway, alat bawaan, dan sumber daya identitas

Saat Anda membuat sumber daya AgentCore runtime (agen), secara default, AgentCore runtime akan membuat grup CloudWatch log untuk log yang disediakan layanan. Namun, untuk memori, gateway, dan sumber daya alat bawaan, AgentCore tidak mengonfigurasi tujuan log untuk Anda secara otomatis.

Untuk sumber daya memori dan gateway, Anda dapat mengonfigurasi tujuan log baik di konsol atau dengan menggunakan AWS SDK. Jika Anda menggunakan konsol untuk mengonfigurasi tujuan CloudWatch Log, nama grup log default untuk sumber daya memori dan gateway memiliki formulir/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}, di mana {resource-type} salah satu memory ataugateway.

Untuk log memori dan gateway, Anda juga dapat mengonfigurasi tujuan log di log Amazon S3 atau log aliran Firehose menggunakan konsol. AgentCore Untuk mempelajari lebih lanjut tentang menyimpan log di Amazon S3 atau Firehose, lihat Mengunggah, mengunduh, dan bekerja dengan objek di Amazon S3 dan Membuat aliran pengiriman Amazon Data Firehose.

Untuk mempelajari lebih lanjut tentang keluaran data log oleh AgentCore untuk sumber daya memori dan gateway, lihat Data log yang disediakan (memori) atau Data log yang disediakan (gateway).

Untuk sumber daya alat bawaan, AgentCore layanan tidak menyediakan log secara default, tetapi Anda dapat menampilkan log Anda sendiri dari kode Anda. Jika Anda menyediakan output log Anda sendiri, Anda perlu mengonfigurasi tujuan log secara manual untuk menyimpan data ini.

Untuk melihat data observabilitas apa yang AgentCore disediakan secara default untuk setiap jenis sumber daya, lihat data observabilitas yang AgentCore dihasilkan Amazon Bedrock.

Konfigurasikan tujuan log menggunakan konsol

Untuk mengonfigurasi tujuan log untuk log memori atau gateway di AgentCore konsol, gunakan prosedur berikut.

Konfigurasikan pengiriman penelusuran untuk CloudWatch menggunakan konsol

Bagian ini menjelaskan cara mengaktifkan pengiriman jejak CloudWatch untuk melacak aliran interaksi melalui aplikasi Anda yang memungkinkan Anda memvisualisasikan permintaan, mengidentifikasi kemacetan kinerja, memecahkan masalah kesalahan, dan mengoptimalkan kinerja.

Konfigurasikan CloudWatch sumber daya menggunakan AWS SDK

Untuk mengonfigurasi sumber pengiriman untuk log dan jejak (SDK)

import boto3

def enable_observability_for_resource(resource_arn, resource_id, account_id, region='us-east-1'):
    """
    Enable observability for a Bedrock AgentCore resource (e.g., Memory Store)
    """
    logs_client = boto3.client('logs', region_name=region)

    # Step 0: Create new log group for vended log delivery
    log_group_name = f'/aws/vendedlogs/bedrock-agentcore/{resource_id}'
    logs_client.create_log_group(logGroupName=log_group_name)
    log_group_arn = f'arn:aws:logs:{region}:{account_id}:log-group:{log_group_name}'

    # Step 1: Create delivery source for logs
    logs_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-logs-source",
        logType="APPLICATION_LOGS",
        resourceArn=resource_arn
    )

    # Step 2: Create delivery source for traces
    traces_source_response = logs_client.put_delivery_source(
        name=f"{resource_id}-traces-source",
        logType="TRACES",
        resourceArn=resource_arn
    )

    # Step 3: Create delivery destinations
    logs_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-logs-destination",
        deliveryDestinationType='CWL',
        deliveryDestinationConfiguration={
            'destinationResourceArn': log_group_arn,
        }
    )

    # Traces required
    traces_destination_response = logs_client.put_delivery_destination(
        name=f"{resource_id}-traces-destination",
        deliveryDestinationType='XRAY'
    )

    # Step 4: Create deliveries (connect sources to destinations)
    logs_delivery = logs_client.create_delivery(
        deliverySourceName=logs_source_response['deliverySource']['name'],
        deliveryDestinationArn=logs_destination_response['deliveryDestination']['arn']
    )

    # Traces required
    traces_delivery = logs_client.create_delivery(
        deliverySourceName=traces_source_response['deliverySource']['name'],
        deliveryDestinationArn=traces_destination_response['deliveryDestination']['arn']
    )

    print(f"Observability enabled for {resource_id}")
    return {
        'logs_delivery_id': logs_delivery['id'],
        'traces_delivery_id': traces_delivery['id']
    }

# Usage example
resource_arn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:memory/my-memory-id"
resource_id = "my-memory-id"
account_id = "123456789012"

delivery_ids = enable_observability_for_resource(resource_arn, resource_id, account_id)

Peningkatan observabilitas AgentCore runtime dengan header khusus

Anda dapat memanggil agen Anda dengan header HTTP tambahan untuk memberikan opsi observabilitas yang disempurnakan. Contoh berikut menunjukkan pemanggilan termasuk permintaan header tambahan opsional untuk agen yang dihosting di runtime. AgentCore

Contoh pemanggilan Boto3

def invoke_agent(agent_id, payload, session_id=None):
    client = boto3.client("bedrock-agentcore", region="us-west-2")
    response = client.invoke_agent_runtime(
        agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test_agent_boto2-nIg2xk3VSR",
        runtimeSessionId="12345678-1234-5678-9abc-123456789012",
        payload='{"query": "Plan a weekend in Seattle"}',
    )

Anda dapat menyertakan header opsional berikut saat memanggil agen Anda untuk meningkatkan kemampuan observabilitas dan penelusuran:

Peningkatan kemampuan observasi alat AgentCore bawaan dengan header khusus

Anda dapat memanggil Built-in Alat Anda dengan header HTTP tambahan untuk memberikan opsi observabilitas yang disempurnakan. Anda dapat menyertakan header opsional berikut saat mengintegrasikan API Build-in Alat berikut untuk meningkatkan kemampuan observabilitas dan penelusuran:

API berikut mendukung header khusus:

Peningkatan observabilitas AgentCore identitas dengan header khusus

Anda dapat memanggil sumber daya identitas Anda dengan header HTTP tambahan untuk menyediakan opsi observabilitas yang disempurnakan. Anda dapat menyertakan header opsional berikut saat mengintegrasikan API identitas berikut untuk meningkatkan kemampuan observabilitas dan penelusuran:

API berikut mendukung header khusus:

Praktik terbaik observabilitas

Pertimbangkan praktik terbaik berikut saat menerapkan observabilitas untuk agen di AgentCore:

Menggunakan platform observabilitas lainnya

Untuk mengintegrasikan agen yang dihosting di AgentCore runtime dengan platform observabilitas lainnya untuk menangkap dan melihat output telemetri, tetapkan variabel lingkungan berikut:

DISABLE_ADOT_OBSERVABILITY=true

Menyetel variabel ini untuk true menghapus variabel lingkungan ADOT default AgentCore runtime, memastikan bahwa tidak ada konfigurasi ADOT default yang disetel.