將可觀測性新增至 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) 或其中一個 AWS SDKs 使用 API 來啟用 CloudWatch 交易搜尋。

使用下列其中一個程序來啟用交易搜尋。

Amazon Bedrock AgentCore 執行時間中託管之代理程式的範圍目的地

透過 AgentCore 執行期，Amazon Bedrock 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 開發套件新增至您的程式碼。

如果您在 AWS Lambda 上託管代理程式，請使用 AWS Distro AWS for OpenTelemetry 網站上的 Lambda Layer for OpenTelemetry。將 layer 新增至函數，然後將AWS_LAMBDA_EXEC_WRAPPER環境變數設定為 /opt/otel-instrument。然後， layer 會自動檢測您的函數。使用此方法，您不需要新增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} ，其中 {resource-type}為 memory或 gateway。

對於記憶體和閘道日誌，您也可以使用 AgentCore 主控台在 Amazon S3 日誌或 Firehose 串流日誌中設定日誌目的地。若要進一步了解如何在 Amazon S3 或 Firehose 中存放日誌，請參閱上傳、下載和使用 Amazon S3 中的物件，以及建立 Amazon Data Firehose 交付串流。

若要進一步了解 AgentCore for memory and Gateway 資源的日誌資料輸出，請參閱提供日誌資料 （記憶體） 或提供日誌資料 （閘道）。

對於內建工具資源，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 標頭叫用身分資源，以提供增強的可觀測性選項。您可以在整合下列身分 APIs 時包含下列選用標頭，以增強可觀測性和追蹤功能：

下列 APIs支援自訂標頭：

可觀測性最佳實務

在 AgentCore 中實作代理程式的可觀測性時，請考慮下列最佳實務：

使用其他可觀測性平台

若要將 AgentCore 執行期中託管的代理程式與其他可觀測性平台整合，以擷取和檢視遙測輸出，請設定下列環境變數：

DISABLE_ADOT_OBSERVABILITY=true

將此變數設定為 會true取消設定 AgentCore 執行期的預設 ADOT 環境變數，確保未設定任何預設 ADOT 組態。