AWS bedrock-agentcore documentation change
Summary
Expanded observability documentation to include identity resources, added detailed logging/tracing configuration steps for runtime/built-in tools/identity resources, and introduced enhanced observability headers for built-in tools and identity APIs
Security assessment
The changes add documentation for monitoring identity resources and WorkloadIdentity tracing, which improves security observability capabilities. However, there is no evidence these changes address a specific security vulnerability or incident. The additions primarily enhance monitoring features rather than patching weaknesses.
Diff
diff --git a/bedrock-agentcore/latest/devguide/observability-configure.md b/bedrock-agentcore/latest/devguide/observability-configure.md index 4eed6853d..0ee7c4f51 100644 --- a//bedrock-agentcore/latest/devguide/observability-configure.md +++ b//bedrock-agentcore/latest/devguide/observability-configure.md @@ -5,3 +5 @@ -Enabling AgentCore runtime observabilityEnabling observability in agent code for AgentCore-hosted agentsConfigure Observability for agents hosted outside of the AgentCore runtimeEnable observability for AgentCore memory, gateway, and built-in tool resourcesEnhanced AgentCore observability with custom headersObservability best practicesUsing other observability platforms - -Amazon Bedrock AgentCore is in preview release and is subject to change. +Enabling AgentCore observabilityEnabling observability in agent code for AgentCore-hosted agentsEnabling observability for agents hosted outside of AgentCoreEnabling observability for AgentCore runtime, memory, gateway, built-in tools, and identity resourcesEnhanced AgentCore runtime observability with custom headersEnhanced AgentCore built-in tools observability with custom headersEnhanced AgentCore identity observability with custom headersObservability best practicesUsing other observability platforms @@ -11 +9 @@ Amazon Bedrock AgentCore is in preview release and is subject to change. -Amazon Bedrock AgentCore provides a number of built-in metrics to monitor the performance of resources for the AgentCore runtime, memory, gateway, and built-in tool resource types. This default data is available in Amazon CloudWatch. To view the full range of observability data in the CloudWatch console, or to output custom runtime metrics for agents, you need to instrument your code using the AWS Distro for Open Telemetry (ADOT) SDK. +Amazon Bedrock AgentCore provides a number of built-in metrics to monitor the performance of resources for the AgentCore runtime, memory, gateway, built-in tools, and identity resource types. This default data is available in Amazon CloudWatch. To view the full range of observability data in the CloudWatch console, or to output custom runtime metrics for agents, you need to instrument your code using the AWS Distro for Open Telemetry (ADOT) SDK. @@ -19 +17,19 @@ See the following sections to learn more about configuring your resources to vie -Use of the ADOT SDK to output custom metrics is also supported for agents running outside the AgentCore runtime. To learn how to enable observability for these agents, see Configure Observability for agents hosted outside of the AgentCore runtime. +Use of the ADOT SDK to output custom metrics is also supported for agents running outside the AgentCore runtime. To learn how to enable observability for these agents, see Enabling observability for agents hosted outside of AgentCore. + +###### Topics + + * Enabling AgentCore observability + + * Enabling observability in agent code for AgentCore-hosted agents + + * Enabling observability for agents hosted outside of AgentCore + + * Enabling observability for AgentCore runtime, memory, gateway, built-in tools, and identity resources + + * Enhanced AgentCore runtime observability with custom headers + + * Enhanced AgentCore built-in tools observability with custom headers + + * Enhanced AgentCore identity observability with custom headers + + * Observability best practices @@ -21 +37 @@ Use of the ADOT SDK to output custom metrics is also supported for agents runnin -## Enabling AgentCore runtime observability + * Using other observability platforms @@ -23 +39,6 @@ Use of the ADOT SDK to output custom metrics is also supported for agents runnin -To view metrics, spans, and traces generated by the AgentCore service, you first need to complete a one-time setup to turn on Amazon CloudWatch Transaction Search. To view service-provided spans for memory resources, you also need to enable tracing when you create a memory. See Enable observability for AgentCore memory, gateway, and built-in tool resources to learn more. + + + +## Enabling AgentCore observability + +To view metrics, spans, and traces generated by the AgentCore service, you first need to complete a one-time setup to turn on Amazon CloudWatch Transaction Search. To view service-provided spans for memory resources, you also need to enable tracing when you create a memory. See Enabling observability for AgentCore runtime, memory, gateway, built-in tools, and identity resources to learn more. @@ -46,3 +67 @@ CloudWatch console - 5. (Optional) Change the percentage of spans you want to be indexed as trace summaries by entering a value under **X-Ray trace indexing**. By default, 1% of spans are indexed as trace summaries for free, but you can alter the percentage to generate more trace summaries for end-to-end transaction analysis. - - 6. Choose **Save**. + 5. Choose **Save**. @@ -133 +152 @@ To view this data in the CloudWatch console generative AI observability page and -With AgentCore, you can also view metrics for agents that aren't running in the AgentCore runtime. Additional setup steps are required to configure telemetry outputs for non-AgentCore agents. See the instructions in Configure Observability for agents hosted outside of the AgentCore runtime to learn more. +With AgentCore, you can also view metrics for agents that aren't running in the AgentCore runtime. Additional setup steps are required to configure telemetry outputs for non-AgentCore agents. See the instructions in Enabling observability for agents hosted outside of AgentCore to learn more. @@ -164 +183 @@ To propoagate a trace ID, invoke the AgentCore runtime with the parameter `trace -You can also invoke your agent with additional headers for additional observability options. See Enhanced AgentCore observability with custom headers to learn more. +You can also invoke your agent with additional headers for additional observability options. See Enhanced AgentCore runtime observability with custom headers to learn more. @@ -169 +188 @@ You can also invoke your agent with additional headers for additional observabil -## Configure Observability for agents hosted outside of the AgentCore runtime +## Enabling observability for agents hosted outside of AgentCore @@ -199,0 +219,17 @@ Replace `<agent-name>` with your agent's name and `<agent-id>` with a unique ide +###### Note + +(Optional) For Agent Frameworks other than Strands, LangChain, CrewAI: + +You may need to add an additional SDK and code to send Generative AI semantic conventions telemetry and spans. CloudWatch AgentCore Observability supports use of the following instrumentation libraries in your agent framework: + + * [OpenInference](https://github.com/Arize-ai/openinference) + + * [Openllmetry](https://github.com/traceloop/openllmetry) + + * [OpenLit](https://github.com/openlit/openlit) + + * [Traceloop](https://www.traceloop.com/docs/introduction) + + + + @@ -210 +246 @@ To propagate session ID, you need to invoke using session identifier in the OTEL -## Enable observability for AgentCore memory, gateway, and built-in tool resources +## Enabling observability for AgentCore runtime, memory, gateway, built-in tools, and identity resources @@ -222 +258 @@ For built-in tool resources, the AgentCore service doesn't provide logs by defau -To see what observability data AgentCore provides by default for each resource type, see [Amazon Bedrock AgentCore provided observability metrics](./observability-service-provided.html). +To see what observability data AgentCore provides by default for each resource type, see [Amazon Bedrock AgentCore generated observability data](./observability-service-provided.html). @@ -277,0 +314,78 @@ Gateway +Runtime + + +###### To configure log delivery for agent runtime resources (console) + + 1. Open the [Agent Runtime](https://console.aws.amazon.com/bedrock-agentcore/agents) page in the AgentCore console. + + 2. In the **Runtime agents** pane, select the runtime agent for which you want to configure a log destination. + + 3. Scroll down to the **Log delivery** pane and from the **Add** drop-down, choose the **Logging destination** \- either Amazon CloudWatch Logs, Amazon S3, or Amazon Data Firehose. + + 4. Configure the following log delivery details and then choose **Add** : + + * For **Log type** , choose **APPLICATION_LOGS**. + + * If using Amazon CloudWatch Logs as the logging destination, specify the destination log group. + + * If using Amazon S3 as the logging destination, specify the destination Amazon S3 bucket. + + * If using Amazon Data Firehose as the logging destination, specify a destination delivery stream. + + 5. Verify that the log delivery status is set to **Delivery active**. + + + + +Built-in tools + + +###### To configure log delivery for built-in tools resources (console) + + 1. Open the [Built-in tools](https://console.aws.amazon.com/bedrock-agentcore/builtInTools) page in the AgentCore console. + + 2. In the **Built-in tools** pane, either in the **Code interperter tools** or the **Browser tools** tab, select the code interpreter tool or browser tool for which you want to configure a log destination. + + 3. Scroll down to the **Log delivery** pane and from the **Add** drop-down, choose the **Logging destination** \- either Amazon CloudWatch Logs, Amazon S3, or Amazon Data Firehose. + + 4. Configure the following log delivery details and then choose **Add** : + + * For **Log type** , choose **APPLICATION_LOGS**. + + * If using Amazon CloudWatch Logs as the logging destination, specify the destination log group. + + * If using Amazon S3 as the logging destination, specify the destination Amazon S3 bucket. + + * If using Amazon Data Firehose as the logging destination, specify a destination delivery stream. + + 5. Verify that the log delivery status is set to **Delivery active**. + + + + +Identity + + +WorkloadIdentity log delivery enablement is handled at the associated resource level, including agent runtime or agent gateway resources. + +###### To configure WorkloadIdentity log delivery for associated resources (console) + + 1. Open either the [Gateway](https://console.aws.amazon.com/bedrock-agentcore/toolsAndGateways) or the [Agent Runtime](https://console.aws.amazon.com/bedrock-agentcore/agents) page in the AgentCore console and select an agent or a gateway for which you want to enable WorkloadIdentity logging. + + 2. In the **Identity** tab, scroll down to the **Log delivery** pane and from the **Add** drop-down, choose the **Logging destination** \- either Amazon CloudWatch Logs, Amazon S3, or Amazon Data Firehose. + + 3. Configure the following log delivery details and then choose **Add** : + + * For **Log type** , choose **APPLICATION_LOGS**. + + * If using Amazon CloudWatch Logs as the logging destination, specify the destination log group. + + * If using Amazon S3 as the logging destination, specify the destination Amazon S3 bucket. + + * If using Amazon Data Firehose as the logging destination, specify a destination delivery stream. + + 4. Verify that the log delivery status is set to **Delivery active**. + + + + @@ -296 +410,43 @@ Memory -###### Note +Runtime + + +###### To configure tracing for runtime resources (console) + + 1. Open the [Agents runtime](https://console.aws.amazon.com/bedrock-agentcore/agents) page in the AgentCore console. + + 2. In the **Runtime agents** pane, select the agent for which you want to enable tracing. + + 3. In the **Tracing** pane, choose **Edit** , toggle the widget to **Enable** , and then choose **Save**. + +Tracing will be enabled for the selected agent and spans will be available in the `aws/spans` log group. + + + + +###### To configure WorkloadIdentity tracing for runtime resources (console) + + 1. Open the [Agents runtime](https://console.aws.amazon.com/bedrock-agentcore/agents) page in the AgentCore console. + + 2. In the **Runtime agents** pane, choose the **Identity** tab, and then select the agent for which you want to enable WorkloadIdentity tracing. + + 3. In the **Tracing** pane, choose **Edit** , toggle the widget to **Enable** , and then choose **Save**. + +WorkloadIdentity tracing will be enabled for the selected agent and spans will be available in the `aws/spans` log group. + + + + +Built-in tools + + +###### To configure tracing for built-in tools (console) + + 1. Open the [Built-in tools](https://console.aws.amazon.com/bedrock-agentcore/builtInTools) page in the AgentCore console. + + 2. In the **Built-in tools** pane, either in the **Code interperter tools** or the **Browser tools** tab, select the code interpreter tool or browser tool for which you want to enable tracing.