本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 为您的亚马逊 Bedro AgentCore ck 资源添加可观察性 Amazon Bedrock AgentCore 提供了许多内置指标，用于监控 AgentCore 运行时、内存、网关、内置工具和身份资源类型的资源性能。此默认数据可在亚马逊上找到 CloudWatch。要在 CloudWatch 控制台中查看全部可观测性数据，或输出代理的自定义运行时指标，您需要使用开放遥测 Amazon 发行版 (ADOT) SDK 对代码进行检测。 要在中查看可观测性控制面板 CloudWatch，请打开[亚马逊 CloudWatch GenAi 可观测性页面](https://console.amazonaws.cn/cloudwatch/home#gen-ai-observability)。 请参阅以下部分，详细了解如何配置资源以在 CloudWatch 控制台生成式 AI 可观测性页面和日志中查看可观测性指标。 CloudWatch **提示** 在运行 AgentCore 时之外运行的代理也支持使用 ADOT SDK 输出自定义指标。要了解如何为这些代理启用可观察性，请参阅为外部托管的代理[启用可观察性。 AgentCore ](#observability-configure-3p) **Topics** + [启用可 AgentCore 观察性](#observability-configure-builtin) + [在代理代码中为 AgentCore-hosted 代理启用可观察性](#observability-configure-custom) + [为托管在外部的代理启用可观察性 AgentCore](#observability-configure-3p) + [为 AgentCore 运行时、内存、网关、内置工具和身份资源启用可观察性](#observability-configure-cloudwatch) + [使用自定义 AgentCore 标头增强运行时可观察性](#observability-configure-invoke) + [使用自定义标头增强 AgentCore 内置工具的可观察性](#observability-configure-built-in) + [使用自定义标头增强 AgentCore 身份可观察性](#observability-configure-identity) + [可观测性最佳实践](#observability-configure-best-practice) + [使用其他可观测性平台](#observability-configure-3p-platforms) ## 启用可 AgentCore 观察性 要查看该 AgentCore 服务生成的指标、跨度和跟踪，您首先需要完成一次性设置才能开启亚马逊 CloudWatch 交易搜索。要查看服务提供的内存资源跨度，还需要在创建内存时启用跟踪。要了解更多信息，请参阅为 AgentCore 运行时、内存、网关、内置工具和身份资源[启用](#observability-configure-cloudwatch)可观察性。 以下各节介绍如何执行这些设置操作以及如何在代理代码中启用可观察性。 ### 启用 CloudWatch 交易搜索 您可以使用 CloudWatch 控制台启用 CloudWatch 交易搜索，也可以通过 Amazon 命令行接口 (Amazon CLI) 或其中一个 Amazon 软件开发工具包使用 API 来启用事务搜索。 使用以下过程之一启用事务搜索。 **Example** 1. ===== 在控制台中 CloudWatch 启用 CloudWatch 交易搜索 1. 打开 [CloudWatch 控制台](https://console.amazonaws.cn/cloudwatch)。 1. 在导航窗格中，展开**应用程序信号 (APM)，**然后选择**交易搜索**。 1. 选择**启用 Transaction Search**。 1. 选中该复选框以结构化日志形式收录跨度。 1. 选择**保存**。 1. ===== 使用 API 启用 CloudWatch 交易搜索 1. 使用 Amazon CLI 或 Amazon SDK 启用事务搜索时，首先通过添加基于资源的策略来配置必要的权限以在 CloudWatch 日志中提取跨度。[ PutResourcePolicy ](https://docs.amazonaws.cn/xray/latest/api/API_PutResourcePolicy.html) 以下 Amazon CLI 命令添加了资源策略，该策略 Amazon X-Ray 授予向 CloudWatch 日志发送跟踪的权限。 ``` aws logs put-resource-policy --policy-name MyResourcePolicy --policy-document '{ "Version": "2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:partition:logs:region:account-id:log-group:aws/spans:*", "arn:partition:logs:region:account-id:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:partition:logs:region:account-id:*" }, "StringEquals": { "aws:SourceAccount": "account-id" } } } ]}' ``` 为清楚起见，此命令中的内联 JSON 策略在以下示例中进行了扩展： ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "TransactionSearchXRayAccess", "Effect": "Allow", "Principal": { "Service": "xray.amazonaws.com" }, "Action": "logs:PutLogEvents", "Resource": [ "arn:aws:logs:us-east-1:123456789012:log-group:aws/spans:*", "arn:aws:logs:us-east-1:123456789012:log-group:/aws/application-signals/data:*" ], "Condition": { "ArnLike": { "aws:SourceArn": "arn:aws:xray:us-east-1:123456789012:*" }, "StringEquals": { "aws:SourceAccount": "123456789012" } } } ] } ``` 1. 使用配置追踪分段的目的地[UpdateTraceSegmentDestination](https://docs.amazonaws.cn/xray/latest/api/API_UpdateTraceSegmentDestination.html)。 要使用 Amazon CLI，请运行以下命令。 ``` aws xray update-trace-segment-destination --destination CloudWatchLogs ``` 1. （可选）使用配置所需的采样百分比[UpdateIndexingRule](https://docs.amazonaws.cn/xray/latest/api/API_UpdateIndexingRule.html)。 要使用 Amazon CLI，请运行以下命令。 ``` aws xray update-indexing-rule --name "Default" --rule '{"Probabilistic": {"DesiredSamplingPercentage": number}}' ``` ### 亚马逊 Bedrock AgentCore 运行时中托管的代理的跨度目的地 **提示** 现在，您可以将代理的所有遥测数据（跨度、结构化日志和标准输出）整合到每个代理的单个日志组中。 借 AgentCore 助 Amazon Bedrock 的运行时功能 AgentCore，您可以配置代理将其跨度传送到与代理 CloudWatch 日志相同的亚马逊日志组。使用此配置，跨度将转到`spans`日志流中`/aws/bedrock-agentcore/runtimes/-`，而不是共享`aws/spans`日志组。您可以将跨度、结构化日志和标准输出一起保存在一个每个代理的日志组中，将访问控制和加密范围限制为单个代理，并从单个位置导出遥测数据。 在支持的 Amazon 区域中，新创建的代理使用代理的日志组作为默认跨度目标。在区域支持统一 span 目标之前创建的代理会将共享`aws/spans`日志组保留为其默认值。 您可以在代理运行时使用`UNIFIED_TRACES_DESTINATION_ENABLED`环境变量覆盖单个代理的默认值： + 要选择加入使用共享`aws/spans`日志组的现有代理，请设置`UNIFIED_TRACES_DESTINATION_ENABLED=true`。 AgentCore 然后将代理的跨度传送到其自己的日志组。 + 要选择退出默认使用自己的日志组的代理，请设置`UNIFIED_TRACES_DESTINATION_ENABLED=false`。 AgentCore 然后将代理的跨度传送到共享`aws/spans`日志组。 AgentCore 要将跨度传送到代理的日志组，必须满足以下条件： + 在您的账户中启用 CloudWatch 交易搜索并将追踪区段发送到亚马逊 CloudWatch 日志。如果没有事务搜索，就 AgentCore 无法将跨度传送到代理的日志组。有关更多信息，请参阅[启用 CloudWatch 事务搜索](#observability-configure-builtin-cw)。 + 将对代理日志组的`logs:PutResourcePolicy`操作授予代理的执行角色。 AgentCore 使用此权限允许 Amazon X-Ray 向日志组传送跨度。有关更多信息，请参阅在运行 AgentCore 时运行代理的[执行角色](runtime-permissions.md#runtime-permissions-execution)。 + 该代理使用 ADOT 版本 0.18.0 或更高版本 ()。`aws-opentelemetry-distro>=0.18.0`早期版本会忽略跨度目标配置，并将跨度传送到共享`aws/spans`日志组。 更改跨度目标不会移动现有的跨度数据。 AgentCore 已经交付的 Span 仍保留在其原始日志组中。 ## 在代理代码中为 AgentCore-hosted 代理启用可观察性 除了服务生成的指标外， AgentCore 您还可以收集跨度和跟踪数据以及代理代码发出的自定义指标。 当您将 [ Strand ](https://strandsagents.com/latest/) s或 [ CreWAI等代理框架](https://www.crewai.com/)与支持的第三方工具库一起使用时，该框架本身内置了对OTEL和GenAI语义约定的支持，也可以使用诸如以下的自动仪器包进行检测。[ LangChain ](https://www.langchain.com/agents) `opentelemetry-instrument-langchain`还可以[通过定义自定义跟踪器来发送生成式 AI 语义约定[遥测](https://opentelemetry.io/docs/specs/semconv/gen-ai/)和](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/)跨度。 AgentCore 支持在代理框架中使用以下仪器库： + [OpenInference](https://github.com/Arize-ai/openinference) + [开度测量 ](https://github.com/traceloop/openllmetry) + [OpenLit](https://github.com/openlit/openlit) + [Traceloop ](https://www.traceloop.com/docs/introduction) 要在 CloudWatch 控制台生成式 AI 可观测性页面和亚马逊中查看这些数据 CloudWatch，您需要将开放遥测 Amazon 发行版 (ADOT) SDK 添加到代理代码中。 **注意** 使用 AgentCore，您还可以查看未在运行 AgentCore 时运行的代理的指标。需要额外的设置步骤来配置非AgentCore 代理的遥测输出。要了解更多信息，请参阅为外部托管的代理[启用可观察性中的说明。 AgentCore ](#observability-configure-3p) 要添加 ADOT 支持并启用 AgentCore 可观察性，请按照以下过程中的步骤操作。 **为您的 AgentCore 代理添加可观察性 ** 1. 确保将您的框架配置为发出跟踪。例如，在 Strands 框架中，必须将跟踪器对象配置为指示 Strands 发出开放遥测 (OTEL) 日志。 1. 将 ADOT SDK 和 boto3 添加到代理的依赖项中。对于 Python，将以下内容添加到您的`requirements.txt`文件中： ``` aws-opentelemetry-distro>=0.18.0 boto3 ``` 或者，你可以直接安装依赖项： ``` pip install aws-opentelemetry-distro>=0.18.0 boto3 ``` 1. 使用 OpenTelemetry 自动插桩命令执行代理代码： ``` opentelemetry-instrument python my_agent.py ``` 这种自动检测方法会自动将 SDK 添加到 Python 路径中。您可能已经在使用这种方法作为标准 OpenTelemetry 实现的一部分。 对于容器化环境（例如 docker），添加以下命令： ``` CMD ["opentelemetry-instrument", "python", "main.py"] ``` 使用 ADOT 时，为了正确传播会话 ID，请在请求标头`X-Amzn-Bedrock-AgentCore-Runtime-Session-Id`中定义。然后，ADOT 在下游标头中正确设置会话\_id。 要传播跟踪 ID，请使用`traceId=`设置的参数调用 AgentCore 运行时。 你还可以使用额外的标头来调用代理，以获得额外的可观察性选项。要了解更多信息，请参阅使用自定义标头[使用自定义 AgentCore 标头增强运行时可观察性](#observability-configure-invoke)增强 AgentCore 运行时可观察性。 ## 为托管在外部的代理启用可观察性 AgentCore 要为 AgentCore 运行时之外托管的代理启用可观察性，请首先按照前几节中的步骤启用 CloudWatch 交易搜索并将 ADOT SDK 添加到您的代码中。 如果您在 Amazon Lambda 上托管代理，请在 Amazon 发行版 OpenTelemetry[网站上使用 ](https://aws-otel.github.io/docs/getting-started/lambda)Amazon Lambda 层。 OpenTelemetry 将该层添加到您的函数，然后将`AWS_LAMBDA_EXEC_WRAPPER`环境变量设置为`/opt/otel-instrument`。然后，该层会自动整理您的函数。使用这种方法，您无需添加`aws-opentelemetry-distro`软件包或运行前面描述的`opentelemetry-instrument`命令。 **不支持 ADOT Collector 以实现代理可观察性** 代理可观察性不支持 ADOT 收集器。要从 AgentCore 运行时之外托管的代理发送遥测数据，必须使用 ADOT SDK 或 Amazon Lambda 层。 OpenTelemetry 对于在运行时之外 AgentCore 运行的代理，您还需要创建一个代理日志组，将其包含在环境变量中。 配置您的 Amazon 环境变量，然后设置 Open Telemetry 环境变量，如下所示。 Amazon 环境变量 ``` AWS_ACCOUNT_ID= AWS_DEFAULT_REGION= AWS_REGION= AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= ``` 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=,aws.log.group.names=/aws/bedrock-agentcore/runtimes/,cloud.resource_id= # endpoint is optional OTEL_EXPORTER_OTLP_LOGS_HEADERS=x-aws-log-group=/aws/bedrock-agentcore/runtimes/,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/,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 ``` ``替换为您的代理人的姓名``和代理人的唯一标识符。 **注意** 如果您设置将跨度传送`OTEL_EXPORTER_OTLP_TRACES_HEADERS`到自己的日志组，则还必须添加 Amazon L CloudWatch ogs 资源策略。该策略必须允许 X-Ray (`xray.amazonaws.com`) 调用`logs:PutLogEvents`该日志组。使用[启用 CloudWatch 事务搜索中所示的相同策略](#observability-configure-builtin-cw)，并输入日志组的 ARN。`Resource`没有此策略，就 X-Ray 无法将跨度传送到您的日志组。 **注意** （可选）对于 Strands 和 CrewAI 以外的代理框架：您可能需要添加额外的 SDK 和代码来发送生成式 AI 语义约定遥测和跨度。 LangChain AgentCore 可观察性是 Amazon Bedrock 的一项功能 AgentCore，支持在代理框架中使用以下仪器库：\* \* [ Openll ](https://github.com/traceloop/openllmetry) metry \* [ OpenInference ](https://github.com/Arize-ai/openinference) \* Traceloop [ OpenLit ](https://github.com/openlit/openlit) [https://www.traceloop.com/docs/introduction](https://www.traceloop.com/docs/introduction) ### 会话 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 不会自动为您配置日志目的地。 对于内存和网关资源，您可以在控制台中或使用 Amazon SDK 配置日志目的地。如果您使用控制台配置 CloudWatch 日志目标，则内存和网关资源的默认日志组名称的格式`/aws/vendedlogs/bedrock-agentcore/{resource-type}/APPLICATION_LOGS/{resource-id}``{resource-type}`为`memory`或`gateway`。 对于内存和网关日志，您还可以使用 AgentCore 控制台在 Amazon S3 日志或 Firehose 流日志中配置日志目的地。要了解有关在 Amazon S3 或 Firehose 中存储日志的更多信息，请参阅在 Amazon S3 中[上传、下载和处理对象](https://docs.amazonaws.cn/AmazonS3/latest/userguide/uploading-downloading-objects.html)和[创建亚马逊数据 Firehose 传输流。](https://docs.amazonaws.cn/firehose/latest/dev/basic-create.html) 要详细了解内存和网关资源输出的 AgentCore 日志数据，请参阅[提供的日志数据（内存）](observability-memory-metrics.md#memory_logs_summary)或[提供的日志数据（网关）](observability-gateway-metrics.md#observability-gateway-logs-provided)。 对于内置工具资源，该 AgentCore 服务默认不提供日志，但您可以从代码中输出自己的日志。如果您提供自己的日志输出，则需要手动配置日志目标以存储这些数据。 要查看每种资源类型默认 AgentCore 提供的可观测性数据，请参阅 [ Amazon Bedrock AgentCore 生成的可观测性数据。](observability-service-provided.md) ### 使用控制台配置日志目的地 要在 AgentCore 控制台中配置内存或网关日志的日志目的地，请使用以下步骤。 **Example** 1. ===== 为内存资源配置日志传输（控制台） 1. 在 AgentCore 控制台中打开 [ “](https://console.amazonaws.cn/bedrock-agentcore/memory)内存” 页面。 1. 在 “**内存**” 窗格中，选择要为其配置日志目标的内存。 1. 向下滚动到**日志传送**窗格并选择**添加**。 1. 从下拉列表中，选择要添加的日志目标的类型（CloudWatch 日志组、Amazon S3 存储桶或 Amazon Data Firehose）。 1. 对于**日志类型**，选择 ** APPLICATION\_ ** LOGS。 1. 对于 Amazon S3 和 Firehose 目的地，输入**配送目的地 AR ** N。对于 CloudWatch 日志，**目标日志组**已使用默认值填充。 1. （可选）对于 CloudWatch 日志目的地，要更改默认日志组，请在**目标日志组下输入新的日志组名称或选择现有日志组**。 1. （可选）要更改在每条日志记录中捕获的字段或日志的输出格式，请展开**其他设置-可选**，并将**字段选择**、**输出格式**和**字段分隔符修改**为所需的配置。 1. 选择**添加**。 1. ===== 为网关资源配置日志传输（控制台） 1. 在 AgentCore 控制台中打开[网关](https://console.amazonaws.cn/bedrock-agentcore/toolsAndGateways)页面。 1. 在**网关**窗格中，选择要为其配置日志目标的网关。 1. 向下滚动到**日志传送**窗格并选择**添加**。 1. 从下拉列表中，选择要添加的日志目标的类型（CloudWatch 日志组、Amazon S3 存储桶或 Amazon Data Firehose）。 1. 对于 Amazon S3 和 Firehose 目的地，输入**配送目的地 AR ** N。对于 CloudWatch 日志，**目标日志组**已使用默认值填充。 1. （可选）对于 CloudWatch 日志目的地，要更改默认日志组，请在**目标日志组下输入新的日志组名称或选择现有日志组**。 1. （可选）要更改在每条日志记录中捕获的字段或日志的输出格式，请展开**其他设置-可选**，并将**字段选择**、**输出格式**和**字段分隔符修改**为所需的配置。 1. 选择**添加**。 1. ===== 为代理运行时资源配置日志传输（控制台） 1. 在 AgentCore 控制台中打开 “[代理运行时](https://console.amazonaws.cn/bedrock-agentcore/agents)” 页面。 1. 在**运行时代理**窗格中，选择要为其配置日志目标的运行时代理。 1. 向下滚动到**日志传输**窗格，然后从**添加**下拉列表中选择**日志目标 ** ——亚马逊 CloudWatch 日志、亚马逊 S3 或 Amazon Data Firehose。 1. 配置以下日志传输详细信息，然后选择 “**添加”**： + 对于**日志类型**，选择 ** APPLICATION\_ ** LOGS。 + 如果使用 Amazon Log CloudWatch s 作为日志目标，请指定目标日志组。 + 如果使用 Amazon S3 作为日志记录目标，请指定目标 Amazon S3 存储桶。 + 如果使用 Amazon Data Firehose 作为记录目的地，请指定目标传输流。 1. 验证日志传送状态是否设置为**交付处于活动状态**。 1. ===== 为内置工具资源配置日志传输（控制台） 1. 在 AgentCore 控制台中打开[Built-in 工具](https://console.amazonaws.cn/bedrock-agentcore/builtInTools)页面。 1. 在**Built-in 工具**窗格中，在**代码解释器工具**或**浏览器工具**选项卡中，选择要为其配置日志目标的代码解释器工具或浏览器工具。 1. 向下滚动到**日志传输**窗格，然后从**添加**下拉列表中选择**日志目标 ** ——亚马逊 CloudWatch 日志、亚马逊 S3 或 Amazon Data Firehose。 1. 配置以下日志传输详细信息，然后选择 “**添加”**： + 对于**日志类型**，选择 ** APPLICATION\_ ** LOGS。 + 如果使用 Amazon Log CloudWatch s 作为日志目标，请指定目标日志组。 + 如果使用 Amazon S3 作为日志记录目标，请指定目标 Amazon S3 存储桶。 + 如果使用 Amazon Data Firehose 作为记录目的地，请指定目标传输流。 1. 验证日志传送状态是否设置为**交付处于活动状态**。 1. WorkloadIdentity 日志传送启用在相关的资源级别上处理，包括代理运行时或代理网关资源。 **为关联资源配置 WorkloadIdentity 日志传输（控制台）** 1. 在 AgentCore 控制台中打开 “[网关” ](https://console.amazonaws.cn/bedrock-agentcore/toolsAndGateways) 或 “[代理运行时” ](https://console.amazonaws.cn/bedrock-agentcore/agents) 页面，然后选择要启用 WorkloadIdentity 日志记录的代理或网关。 1. 在**身份**选项卡中，向下滚动到**日志传输**窗格，然后从**添加**下拉列表中选择**日志记录目标 ** ——亚马逊 CloudWatch 日志、亚马逊 S3 或 Amazon Data Firehose。 1. 配置以下日志传输详细信息，然后选择 “**添加”**： + 对于**日志类型**，选择 ** APPLICATION\_ ** LOGS。 + 如果使用 Amazon Log CloudWatch s 作为日志目标，请指定目标日志组。 + 如果使用 Amazon S3 作为日志记录目标，请指定目标 Amazon S3 存储桶。 + 如果使用 Amazon Data Firehose 作为记录目的地，请指定目标传输流。 1. 验证日志传送状态是否设置为**交付处于活动状态**。 ### CloudWatch 使用控制台将跟踪交付配置为 本节介绍如何启用跟踪交付 CloudWatch 以跟踪应用程序中的交互流程，从而使您能够可视化请求、识别性能瓶颈、排除错误和优化性能。 **Example** 1. ===== 配置内存资源跟踪（控制台） 1. 在 AgentCore 控制台中打开 [ “](https://console.amazonaws.cn/bedrock-agentcore/memory)内存” 页面。 1. 在 “**内存**” 窗格中，选择要启用跟踪的内存资源。 1. 在 ** “**跟踪” 窗格中，选择 “**编辑”**，将控件切换为 “**启用”**，然后选择 “**保存” **。 1. ===== 为运行时资源配置跟踪（控制台） 1. 在 AgentCore 控制台中打开[代理运行时](https://console.amazonaws.cn/bedrock-agentcore/agents)页面。 1. 在**运行时代理**窗格中，选择要为其启用跟踪的代理。 1. 在 ** “**跟踪” 窗格中，选择 “**编辑”**，将控件切换为 “**启用”**，然后选择 “**保存” **。 AgentCore 启用对选定代理的跟踪。跨度出现在代理的日志组 (`/aws/bedrock-agentcore/runtimes/-`) 中，或者出现在使用共享跨度目标的代理的`aws/spans`日志组中。有关更多信息，请参阅 Amazon Bedrock AgentCore 运行时[中托管的代理的](#observability-configure-unified-traces)跨度目标。 **为运行时资源配置 WorkloadIdentity 跟踪（控制台）** 1. 在 AgentCore 控制台中打开[代理运行时](https://console.amazonaws.cn/bedrock-agentcore/agents)页面。 1. 在 “**运行时代理” ** 窗格中，选择 ** “**身份” 选项卡，然后选择要启用 WorkloadIdentity 跟踪的代理。 1. 在 ** “**跟踪” 窗格中，选择 “**编辑”**，将控件切换为 “**启用”**，然后选择 “**保存” **。 WorkloadIdentity 将为所选代理启用跟踪，`aws/spans`日志组中将提供跨度。 1. ===== 为内置工具（控制台）配置跟踪 1. 在 AgentCore 控制台中打开[Built-in 工具](https://console.amazonaws.cn/bedrock-agentcore/builtInTools)页面。 1. 在**Built-in 工具**窗格中，在**代码解释器工具**或**浏览器工具**选项卡中，选择要启用跟踪的代码解释器工具或浏览器工具。 1. 在 ** “**跟踪” 窗格中，选择 “**编辑”**，将控件切换为 “**启用”**，然后选择 “**保存” **。 将为选定的代码解释器或浏览器工具启用跟踪，`aws/spans`日志组中将提供跨度。 1. ===== 为网关资源配置跟踪（控制台） 1. 在 AgentCore 控制台中打开[网关](https://console.amazonaws.cn/bedrock-agentcore/toolsAndGateways)页面。 1. 在**网关**窗格中，选择要启用跟踪的网关。 1. 在 ** “**跟踪” 窗格中，选择 “**编辑”**，将控件切换为 “**启用”**，然后选择 “**保存” **。 将为所选网关启用跟踪，`aws/spans`日志组中将提供跨度。 **为网关资源配置 WorkloadIdentity 跟踪（控制台）** 1. 在 AgentCore 控制台中打开[网关](https://console.amazonaws.cn/bedrock-agentcore/toolsAndGateways)页面。 1. 在 “**网关**” 窗格中，选择 ** “**身份” 选项卡，然后选择要启用 WorkloadIdentity 跟踪的网关。 1. 在 ** “**跟踪” 窗格中，选择 “**编辑”**，将控件切换为 “**启用”**，然后选择 “**保存” **。 WorkloadIdentity 将为所选网关启用跟踪，`aws/spans`日志组中将提供跨度。 **注意** 必须先[启用](#observability-configure-builtin-cw)CloudWatch 事务搜索，然后才能启用跟踪。 1. ===== 为身份资源配置跟踪（控制台） 1. 在 AgentCore 控制台中打开 [ “](https://console.amazonaws.cn/bedrock-agentcore/identity)身份” 页面。 1. 在 “**身份**” 窗格中，选择要启用跟踪的 OAuth 客户端或 API 密钥。 1. 在 ** “**跟踪” 窗格中，选择 “**编辑”**，将控件切换为 “**启用”**，然后选择 “**保存” **。 ### 使用配置 CloudWatch 资源 Amazon SDK **为日志和跟踪配置传送源 (SDK) ** + 运行以下 Python 代码 CloudWatch 来配置内存、网关和内置工具资源。请注意，传输源和跟踪目标仅适用于内存和网关资源。 ``` 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"}', ) ``` 在调用代理以增强可观察性和跟踪能力时，可以包含以下可选标头： | 标题 | 说明 | 示例值 | 技术解释 | | --- | --- | --- | --- | | X-Amzn-Trace-Id | 用于跟踪请求的跟踪 ID（X-Ray 格式） | root=1-5759e988-bd862e3fe1be46a994272793；parent=53995c3f42cd8ad8；sampled=1 | 用于跨 Amazon 服务的分布式跟踪。包含根 ID（请求来源）、父 ID（以前的服务）和用于跟踪的抽样决策。Sampling=1 表示 100% 采样。父级也是 X-Ray Trace 格式。如果未提供，OTEL 将自动生成跟踪 ID。 | | traceparent | W3C 标准跟踪标头 | 00-4bf92f3577b34da6a3ce929d0e0e0e0e0e4736-00f067a0ba902ba902b7-01 | W3C 格式，包括版本、跟踪 ID、父 ID 和标志。使用现代跟踪系统时，需要进行跨服务跟踪关联。 | | X-Amzn-Bedrock-AgentCore-Runtime-Session-Id | AgentCore 会话标识符 | a1b2c3d4-5678-90ab-cdef-exampleAAAAA | 标识 AgentCore 系统中的用户会话。帮助进行基于会话的分析和故障排除。 | | mcp 会话 ID | MCP 会话标识符 | mcp-a1b2c3d4-5678-90ab-cdef-exampleAAAAA | 识别托管云平台中的会话。支持对整个 MCP 生态系统的操作进行跟踪。 | | 追踪状态 | 其他跟踪状态信息 | congo=t61rc E，rojo=00f067aa0ba902b7 WkgMz | Vendor-specific 追踪信息。除了 traceparent 中的内容外，还为追踪系统提供了其他背景信息。 | | 行李 | 分布式跟踪的上下文传播 | userid=Alice，服务器区域=US-East-1 | Key-value 配对，跨服务边界传播用户定义的属性，以进行上下文记录和分析。 | ## 使用自定义标头增强 AgentCore 内置工具的可观察性 您可以使用其他 HTTP 标头来调用您的 Built-in 工具，以提供增强的可观察性选项。在集成以下 T Build-in ools API 时，您可以添加以下可选标头以增强可观察性和跟踪能力： 以下 API 支持自定义标头： + StartCodeInterpreterSession + InvokeCodeInterpreter + StopCodeInterpreterSession + StartBrowserSession + StopBrowserSession | 标题 | 说明 | 示例值 | 技术解释 | | --- | --- | --- | --- | | X-Amzn-Trace-Id | 用于跟踪请求的跟踪 ID（X-Ray 格式） | root=1-5759e988-bd862e3fe1be46a994272793；parent=53995c3f42cd8ad8；sampled=1 | 用于跨 Amazon 服务的分布式跟踪。包含根 ID（请求来源）、父 ID（以前的服务）和用于跟踪的抽样决策。Sampling=1 表示 100% 采样。父级也是 X-Ray Trace 格式。如果未提供，OTEL 将自动生成跟踪 ID。 | | traceparent | W3C 标准跟踪标头 | 00-4bf92f3577b34da6a3ce929d0e0e0e0e0e4736-00f067a0ba902ba902b7-01 | W3C 格式，包括版本、跟踪 ID、父 ID 和标志。使用现代跟踪系统时，需要进行跨服务跟踪关联。 | ## 使用自定义标头增强 AgentCore 身份可观察性 您可以使用其他 HTTP 标头来调用您的身份资源，以提供增强的可观察性选项。在集成以下身份 API 时，您可以添加以下可选标头以增强可观察性和跟踪能力： 以下 API 支持自定义标头： + GetWorkloadAccessToken + GetWorkloadAccessTokenForJWT + GetWorkloadAccessTokenForUserId + GetResourceOauth2Token + GetResourceAPIKey | 标题 | 说明 | 示例值 | 技术解释 | | --- | --- | --- | --- | | X-Amzn-Trace-Id | 用于跟踪请求的跟踪 ID（X-Ray 格式） | root=1-5759e988-bd862e3fe1be46a994272793；parent=53995c3f42cd8ad8；sampled=1 | 用于跨 Amazon 服务的分布式跟踪。包含根 ID（请求来源）、父 ID（以前的服务）和用于跟踪的抽样决策。Sampling=1 表示 100% 采样。父级也是 X-Ray Trace 格式。如果未提供，OTEL 将自动生成跟踪 ID。 | ## 可观测性最佳实践 在中实现代理的可观察性时，请考虑以下最佳实践： AgentCore + 使用一致的会话 ID-尽可能为相关请求重复使用相同的会话 ID，以保持交互之间的上下文。 + 实现分布式跟踪-使用提供的标头在应用程序组件之间启用端到端跟踪。 + 添加自定义属性-使用自定义属性增强您的跟踪和指标，为故障排除和分析提供更多背景信息。 + 监控资源使用情况-注意内存使用量指标以优化代理的性能。 + 设置警报-配置 CloudWatch 警报以帮助在潜在问题影响用户之前通知您。 ## 使用其他可观测性平台 要将 AgentCore 运行时中托管的代理与其他可观测性平台集成以捕获和查看遥测输出，请设置以下环境变量： ``` DISABLE_ADOT_OBSERVABILITY=true ``` 将此变量设置为`true`取消设置 AgentCore 运行时的默认 ADOT 环境变量，从而确保未设置任何默认 ADOT 配置。