为您的 Amazon Bed AgentCore rock 资源增加可观察性

Amazon Bedrock AgentCore 提供了许多内置指标，用于监控 AgentCore 运行时、内存、网关、内置工具和身份资源类型的资源性能。此默认数据在 Amazon 中可用 CloudWatch。要在 CloudWatch 控制台中查看全方位的可观测性数据，或者要为代理输出自定义运行时指标，您需要使用 AWS Distro for Open Telemetry (ADOT) SDK 来检测您的代码。

要在中查看可观测性控制面板 CloudWatch，请打开 Amazon CloudWatch GenAi 可观测性页面。

请参阅以下章节，详细了解如何配置资源以在 CloudWatch 控制台生成的 AI 可观测性页面和日志中查看可观察性指标。 CloudWatch

启用可 AgentCore 观测性

要查看该 AgentCore 服务生成的指标、跨度和跟踪，您首先需要完成一次性设置以打开 Amazon CloudWatch 交易搜索。要查看服务提供的内存资源跨度，还需要在创建内存时启用跟踪。要了解更多信息，请参阅为 AgentCore 运行时、内存、网关、内置工具和身份资源启用可观察性。

以下各节介绍如何执行这些设置操作以及在代理代码中启用可观察性。

启用 CloudWatch 交易搜索

您可以使用 CloudWatch 控制台启用 CloudWatch 交易搜索，也可以通过 AWS 命令行界面 (AWS CLI) 或其中一个 AWS 软件开发工具包使用 API。

使用以下过程之一启用 “交易搜索”。

托管在 Amazon Bedrock AgentCore 运行时中的代理的跨度目的地

借助 AgentCore 运行时（Amazon Bedrock 的一项功能） AgentCore，您可以将代理配置为将其跨度传输到与代理 CloudWatch 日志相同的亚马逊日志组。使用此配置，span 会转到中的spans日志流/aws/bedrock-agentcore/runtimes/<agent_id>-<endpoint_name>，而不是共享aws/spans日志组。您可以将跨度、结构化日志和标准输出一起保存在每个代理的一个日志组中，将访问控制和加密范围限定到单个代理，并从单个位置导出遥测数据。

在支持的 AWS 区域中，新创建的代理使用代理的日志组作为默认跨度目标。在区域支持统一跨度目标之前创建的代理会将共享aws/spans日志组保留为默认值。

您可以在代理运行时使用UNIFIED_TRACES_DESTINATION_ENABLED环境变量覆盖单个代理的默认值：

AgentCore 要将跨度传送到代理的日志组，必须满足以下条件：

更改跨度目标不会移动现有跨度数据。 AgentCore 已交付的 Span 仍保留在其原始日志组中。

在代理代码中为 AgentCore-hosted 代理启用可观察性

除了服务生成的指标外， AgentCore 您还可以收集跨度和跟踪数据以及代理代码发出的自定义指标。

当您将代理框架（例如 Strands 或 Crew aI）与支持的第三方插桩库一起使用时，框架本身内置了对 OTEL 和 GenAI 语义约定的支持，也可以使用自动插桩包对其进行检测，例如。LangChainopentelemetry-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 上托管代理，请使用发行版网站 OpenTelemetry上的 AWS Lambda 层。 AWS 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 日志目标，则内存和网关资源的默认日志组名称的格式{resource-type}为/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}，其中为memory或gateway。

对于内存和网关日志，您还可以使用控制台在 Amazon S3 日志或 Firehose 流日志中配置日志目标。 AgentCore 要了解有关在 Amazon S3 或 Firehose 中存储日志的更多信息，请参阅在 Amazon S3 中上传、下载和使用对象以及创建亚马逊数据 Firehose 传输流。

要了解有关内存和网关资源输出的 AgentCore 日志数据的更多信息，请参阅提供的日志数据（内存）或提供的日志数据（网关）。

对于内置工具资源，该 AgentCore 服务默认不提供日志，但您可以从代码中输出自己的日志。如果您提供自己的日志输出，则需要手动配置日志目标来存储这些数据。

要查看可观测性数据默认 AgentCore 为每种资源类型提供了什么，请参阅 Amazon Bedrock AgentCore 生成的可观测性数据。

使用控制台配置日志目标

要在 AgentCore 控制台中配置内存或网关日志的日志目标，请使用以下步骤。

CloudWatch 使用控制台将跟踪交付配置为

本节介绍如何启用跟踪交付， CloudWatch 以跟踪应用程序中的交互流，从而使您能够直观呈现请求、识别性能瓶颈、排除错误并优化性能。

使用配置 CloudWatch 资源 AWS SDK

为日志和跟踪配置传送源 (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 标头调用 T Built-in ools，以提供增强的可观察性选项。在集成以下 T Build-in ools API 时，您可以添加以下可选标头，以增强可观察性和跟踪功能：

以下 API 支持自定义标头：

使用自定义标头增强 AgentCore 身份可观察性

您可以使用其他 HTTP 标头调用您的身份资源，以提供增强的可观察性选项。在集成以下身份 API 时，您可以添加以下可选标头，以增强可观察性和跟踪功能：

以下 API 支持自定义标头：

可观测性最佳实践

在实现代理的可观察性时，请考虑以下最佳实践： AgentCore

使用其他可观测性平台

要将 AgentCore 运行时托管的代理与其他可观测性平台集成以捕获和查看遥测输出，请设置以下环境变量：

DISABLE_ADOT_OBSERVABILITY=true

将此变量设置为true取消设置 AgentCore 运行时的默认 ADOT 环境变量，确保未设置任何默认 ADOT 配置。