Amazon Bedrock AgentCore 리소스에 관찰성 추가

Amazon Bedrock AgentCore는 AgentCore 런타임, 메모리, 게이트웨이, 내장 도구 및 자격 증명 리소스 유형에 대한 리소스 성능을 모니터링하기 위한 여러 기본 제공 지표를 제공합니다. 이 기본 데이터는 Amazon CloudWatch에서 사용할 수 있습니다. CloudWatch 콘솔에서 관찰성 데이터의 전체 범위를 보거나 에이전트에 대한 사용자 지정 런타임 지표를 출력하려면 AWS Distro for Open Telemetry(ADOT) SDK를 사용하여 코드를 계측해야 합니다.

CloudWatch에서 관찰성 대시보드를 보려면 Amazon CloudWatch GenAi 관찰성 페이지를 엽니다.

CloudWatch 콘솔 생성형 AI 관찰성 페이지 및 CloudWatch Logs에서 관찰성 지표를 볼 수 있도록 리소스를 구성하는 방법에 대해 자세히 알아보려면 다음 섹션을 참조하세요.

AgentCore 관찰성 활성화

AgentCore 서비스에서 생성된 지표, 범위 및 트레이스를 보려면 먼저 일회성 설정을 완료하여 Amazon CloudWatch 트랜잭션 검색을 켜야 합니다. 메모리 리소스에 대한 서비스 제공 스팬을 보려면 메모리를 생성할 때 추적도 활성화해야 합니다. 자세한 내용은 AgentCore 런타임, 메모리, 게이트웨이, 내장 도구 및 자격 증명 리소스에 대한 관찰성 활성화를 참조하세요.

다음 섹션에서는 이러한 설정 작업을 수행하고 에이전트 코드에서 관찰성을 활성화하는 방법을 설명합니다.

CloudWatch 트랜잭션 검색 활성화

CloudWatch 콘솔을 사용하거나 AWS 명령줄 인터페이스(AWS CLI) 또는 SDK 중 하나를 통해 API를 사용하여 CloudWatch 트랜잭션 검색을 활성화할 수 있습니다. AWS SDKs

다음 절차 중 하나를 사용하여 트랜잭션 검색을 활성화합니다.

Amazon Bedrock AgentCore 런타임에서 호스팅되는 에이전트의 범위 대상

Amazon Bedrock AgentCore의 기능인 AgentCore 런타임을 사용하면 에이전트의 로그와 동일한 Amazon CloudWatch 로그 그룹에 범위를 전달하도록 에이전트를 구성할 수 있습니다. 이 구성을 사용하면 스팬이 공유 spans 로그 그룹 /aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>대신의 aws/spans 로그 스트림으로 이동합니다. 스팬, 구조화된 로그 및 표준 출력을 하나의 에이전트당 로그 그룹에 함께 유지하고, 액세스 제어 및 암호화 범위를 개별 에이전트로 지정하고, 단일 위치에서 원격 측정을 내보낼 수 있습니다.

지원되는 AWS 리전에서 새로 생성된 에이전트는 에이전트의 로그 그룹을 기본 범위 대상으로 사용합니다. 리전이 통합 스팬 대상을 지원하기 전에 생성된 에이전트는 공유 aws/spans 로그 그룹을 기본값으로 유지합니다.

에이전트 런타임에서 UNIFIED_TRACES_DESTINATION_ENABLED 환경 변수를 사용하여 개별 에이전트의 기본값을 재정의할 수 있습니다.

AgentCore가 에이전트의 로그 그룹에 범위를 전달하려면 다음이 true여야 합니다.

스팬 대상을 변경해도 기존 스팬 데이터는 이동하지 않습니다. AgentCore가 이미 전달한 범위는 원래 로그 그룹에 남아 있습니다.

AgentCore 호스팅 에이전트에 대한 에이전트 코드의 관찰성 활성화

서비스 생성 지표 외에도 AgentCore를 사용하면 스팬 및 트레이스 데이터와 에이전트 코드에서 내보낸 사용자 지정 지표를 수집할 수도 있습니다.

지원되는 타사 계측 라이브러리와 함께 Strands , LangChain 또는 CrewAI와 같은 에이전트 프레임워크를 사용하는 경우 프레임워크 자체에는 OTEL 및 GenAI 의미 체계 규칙이 기본적으로 지원되며와 같은 자동 계측 패키지로 opentelemetry-instrument-langchain 계측할 수도 있습니다. 사용자 지정 추적기를 정의하여 생성형 AI 의미 체계 규칙 원격 측정 및 스팬을 전송할 수도 있습니다. AgentCore는 에이전트 프레임워크에서 다음 계측 라이브러리 사용을 지원합니다.

CloudWatch 콘솔 생성형 AI 관찰성 페이지와 Amazon CloudWatch에서이 데이터를 보려면 에이전트 코드에 AWS Distro for Open Telemetry(ADOT) SDK를 추가해야 합니다.

ADOT 지원을 추가하고 AgentCore 관찰성을 활성화하려면 다음 절차의 단계를 따릅니다.

AgentCore 에이전트에 관찰성 추가

AgentCore 외부에서 호스팅되는 에이전트에 대한 관찰성 활성화

AgentCore 런타임 외부에서 호스팅되는 에이전트에 대한 관찰성을 활성화하려면 먼저 이전 섹션의 단계에 따라 CloudWatch 트랜잭션 검색을 활성화하고 ADOT SDK를 코드에 추가합니다.

AWS Lambda에서 에이전트를 호스팅하는 경우 AWS Distro AWS for OpenTelemetry 웹 사이트에서 Lambda Layer for OpenTelemetry를 사용합니다. 함수에 계층을 추가한 다음 AWS_LAMBDA_EXEC_WRAPPER 환경 변수를 로 설정합니다/opt/otel-instrument. 그러면 계층이 함수를 자동 계측합니다. 이 접근 방식을 사용하면 aws-opentelemetry-distro 패키지를 추가하거나 앞서 설명한 opentelemetry-instrument 명령을 실행할 필요가 없습니다.

AgentCore 런타임 외부에서 실행되는 에이전트의 경우 환경 변수에 포함하는 에이전트 로그 그룹도 생성해야 합니다.

AWS 환경 변수를 구성한 다음 다음과 같이 Open Telemetry 환경 변수를 설정합니다.

AWS 환경 변수

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>

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

<agent-name>를 에이전트의 이름으로 바꾸고를 에이전트의 고유 식별자<agent-id>로 바꿉니다.

세션 ID 지원

세션 ID를 전파하려면 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

AgentCore 런타임, 메모리, 게이트웨이, 내장 도구 및 자격 증명 리소스에 대한 관찰성 활성화

AgentCore 런타임 리소스(에이전트)를 생성할 때 기본적으로 AgentCore 런타임은 서비스 제공 로그에 대한 CloudWatch 로그 그룹을 생성합니다. 그러나 메모리, 게이트웨이 및 내장 도구 리소스의 경우 AgentCore는 로그 대상을 자동으로 구성하지 않습니다.

메모리 및 게이트웨이 리소스의 경우 콘솔에서 또는 AWS SDK를 사용하여 로그 대상을 구성할 수 있습니다. 콘솔을 사용하여 CloudWatch Logs 대상을 구성하는 경우 메모리 및 게이트웨이 리소스의 기본 로그 그룹 이름은 형식입니다. 여기서 /aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}는 memory 또는 {resource-type}입니다gateway.

메모리 및 게이트웨이 로그의 경우 AgentCore 콘솔을 사용하여 Amazon S3 로그 또는 Firehose 스트림 로그에서 로그 대상을 구성할 수도 있습니다. Amazon S3 또는 Firehose에 로그를 저장하는 방법에 대한 자세한 내용은 Amazon S3의 객체 업로드, 다운로드 및 작업 및 Amazon Data Firehose 전송 스트림 생성을 참조하세요.

메모리 및 게이트웨이 리소스에 대한 AgentCore의 로그 데이터 출력에 대한 자세한 내용은 제공된 로그 데이터(메모리) 또는 제공된 로그 데이터(게이트웨이)를 참조하세요.

기본 제공 도구 리소스의 경우 AgentCore 서비스는 기본적으로 로그를 제공하지 않지만 코드에서 자체 로그를 출력할 수 있습니다. 자체 로그 출력을 제공하는 경우이 데이터를 저장하도록 로그 대상을 수동으로 구성해야 합니다.

AgentCore가 각 리소스 유형에 대해 기본적으로 제공하는 관찰성 데이터를 확인하려면 Amazon Bedrock AgentCore에서 생성한 관찰성 데이터를 참조하세요.

콘솔을 사용하여 로그 대상 구성

AgentCore 콘솔에서 메모리 또는 게이트웨이 로그의 로그 대상을 구성하려면 다음 절차를 사용합니다.

콘솔을 사용하여 CloudWatch로의 추적 전송 구성

이 섹션에서는 CloudWatch로 트레이스 전송을 활성화하여 요청을 시각화하고, 성능 병목 현상을 식별하고, 오류를 해결하고, 성능을 최적화할 수 있도록 애플리케이션을 통한 상호 작용 흐름을 추적하는 방법을 설명합니다.

AWS SDK를 사용하여 CloudWatch 리소스 구성

로그 및 추적에 대한 전송 소스를 구성하려면(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)

사용자 지정 헤더를 사용하여 AgentCore 런타임 관찰성 향상

추가 HTTP 헤더로 에이전트를 호출하여 향상된 관찰성 옵션을 제공할 수 있습니다. 다음 예제에서는 AgentCore 런타임에서 호스팅되는 에이전트에 대한 선택적 추가 헤더 요청을 포함한 호출을 보여줍니다.

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"}',
    )

에이전트를 호출할 때 다음 선택적 헤더를 포함하여 관찰성과 추적 기능을 향상시킬 수 있습니다.

사용자 지정 헤더를 사용하여 AgentCore 내장 도구 관찰성 향상

추가 HTTP 헤더를 사용하여 기본 제공 도구를 호출하여 향상된 관찰성 옵션을 제공할 수 있습니다. 다음 기본 제공 도구 APIs를 포함하여 관찰성과 추적 기능을 향상시킬 수 있습니다.

다음 APIs 지원합니다.

사용자 지정 헤더를 사용하여 AgentCore 자격 증명 관찰성 향상

추가 HTTP 헤더를 사용하여 ID 리소스를 호출하여 향상된 관찰성 옵션을 제공할 수 있습니다. 다음 자격 증명 APIs를 포함하여 관찰성과 추적 기능을 향상시킬 수 있습니다.

다음 APIs 지원합니다.

관찰성 모범 사례

AgentCore에서 에이전트에 대한 관찰성을 구현할 때는 다음 모범 사례를 고려하세요.

다른 관찰성 플랫폼 사용

AgentCore 런타임에서 호스팅되는 에이전트를 다른 관찰성 플랫폼과 통합하여 원격 측정 출력을 캡처하고 보려면 다음 환경 변수를 설정합니다.

DISABLE_ADOT_OBSERVABILITY=true

이 변수를 로 설정하면 AgentCore 런타임의 기본 ADOT 환경 변수가 설정 true 해제되어 기본 ADOT 구성이 설정되지 않습니다.