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

Tambahkan observabilitas ke sumber daya Amazon Bed AgentCore rock 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 rangkaian lengkap data pengamatan di CloudWatch konsol, atau untuk menampilkan metrik runtime khusus untuk agen, Anda perlu instrumen kode menggunakan AWS Distro for Open Telemetry (ADOT) SDK.

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

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

Mengaktifkan AgentCore observabilitas

Untuk melihat metrik, rentang, dan jejak yang dihasilkan oleh AgentCore layanan, Anda harus terlebih dahulu menyelesaikan pengaturan satu kali untuk mengaktifkan Pencarian CloudWatch Transaksi Amazon. Untuk melihat rentang yang disediakan layanan untuk sumber daya memori, Anda juga perlu mengaktifkan pelacakan 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 mengaktifkan pengamatan dalam kode agen Anda.

Mengaktifkan CloudWatch Pencarian Transaksi

Anda dapat mengaktifkan CloudWatch Pencarian Transaksi 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.

Tujuan rentang 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, rentang masuk ke aliran spans log/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>, bukan grup aws/spans log bersama. Anda dapat menyimpan rentang, log terstruktur, dan output standar bersama-sama dalam satu grup log per agen, kontrol akses lingkup dan enkripsi ke agen individual, dan mengekspor telemetri dari satu lokasi.

Di Wil AWS ayah 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 rentang ke grup log agen, berikut ini harus benar:

Mengubah tujuan rentang tidak memindahkan data rentang yang ada. Rentang yang AgentCore sudah dikirim tetap berada di grup log aslinya.

Mengaktifkan observabilitas dalam kode agen untuk AgentCore-hosted agen

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

Saat Anda menggunakan kerangka kerja agen seperti Str ands, 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 diinstrumentasikan dengan paket instrumentasi otomatis seperti. opentelemetry-instrument-langchain Dimungkinkan juga untuk mengirim telemetri dan rentang konvensi semantik AI Generatif dengan mendefinisikan pelacak khusus. AgentCore mendukung penggunaan pustaka instrumentasi berikut dalam kerangka agen Anda:

Untuk melihat data ini di halaman pengamatan AI generatif CloudWatch konsol dan di Amazon CloudWatch, Anda perlu menambahkan AWS Distro for Open Telemetry (ADOT) SDK 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 untuk agen yang dihosting di luar AgentCore runtime, pertama-tama ikuti langkah-langkah di bagian sebelumnya untuk mengaktifkan Pencarian CloudWatch Transaksi dan menambahkan SDK ADOT ke kode Anda.

Jika Anda meng-host agen Anda di AWS Lambda, gunakan AWS Lambda Layer untuk OpenTelemetry di AWS Distro for situs web. OpenTelemetry Tambahkan layer ke fungsi Anda, dan kemudian atur variabel AWS_LAMBDA_EXEC_WRAPPER lingkungan ke/opt/otel-instrument. Lapisan kemudian secara otomatis menginstrumentasikan 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 di bawah 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
AWS_GENAI_CONTENT_EXTRACTION_OPT_OUT=true # Keeps model payloads and tool request/response data on spans. Requires ADOT >=0.18.0.
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 pengidentifikasi 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 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 memori dan sumber daya 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 AgentCore konsol. Untuk mempelajari lebih lanjut tentang menyimpan log di Amazon S3 atau Firehose, lihat Meng unggah, 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 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 mengkonfigurasi tujuan log secara manual untuk menyimpan data ini.

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

Konfigurasikan tujuan log menggunakan konsol

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

Konfigurasikan penelusuran pengiriman 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 hambatan kinerja, memecahkan masalah kesalahan, dan mengoptimalkan kinerja.

Konfigur CloudWatch asikan sumber daya menggunakan AWS SDK

Untuk mengonfigurasi sumber pengiriman untuk log dan pelacakan (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 AgentCore pengamatan runtime dengan header khusus

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

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 pengamatan dan pelacakan:

Peningkatan AgentCore pengamatan alat bawaan dengan header khusus

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

API berikut mendukung header khusus:

Peningkatan AgentCore pengamatan identitas dengan header khusus

Anda dapat memanggil sumber daya identitas Anda dengan header HTTP tambahan untuk memberikan opsi pengamatan yang ditingkatkan. Anda dapat menyertakan header opsional berikut saat mengintegrasikan API identitas berikut untuk meningkatkan kemampuan pengamatan dan pelacakan:

API berikut mendukung header khusus:

Praktik terbaik pengamatan

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

Menggunakan platform observabilitas lainnya

Untuk mengintegrasikan agen yang dihosting dalam AgentCore runtime dengan platform observabilitas lain untuk menangkap dan melihat keluaran telemetri, atur variabel lingkungan berikut:

DISABLE_ADOT_OBSERVABILITY=true

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