本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 亚马逊的可观察性 CloudWatch
<a name="payments-observability"></a>

AgentCore 支付支持通过亚马逊实现的可观察性 CloudWatch，因此您可以监控支付集成并排除故障。
+  **亚马逊 CloudWatch**是 Amazon 监控和可观察性服务。它从您的 Amazon 资源中收集和跟踪指标、日志和跟踪，使您可以了解应用程序性能。
+  **已售日志**是 Amazon 服务代表您直接发布到您的 CloudWatch 日志组的日志。与您自己检测的应用程序日志不同，出售的日志由服务自动生成。您可以配置将它们交付到哪里。
+  **跨度**代表请求中的工作单元（例如，API 调用及其下游操作）。使用 span 来跟踪系统中的请求流量，并确定延迟瓶颈或故障。

完成以下设置过程后，任何数据平面 API 调用（例如`CreatePaymentInstrument`）都会在配置的日志组中生成 CloudWatch 日志和跟踪数据。

## 先决条件
<a name="payments-observability-prerequisites"></a>
+ 将**CloudWatch 日志组**作为传送目标（例如，`/bedrock-agentcore/payments/my-logs`）。如果您没有，请使用控制台或 CLI 创建一个。
+ 您的** PaymentManager资源 ARN **。

创建日志组：

**Example**  
打开 CloudWatch 控制台，转到**日志 > 日志组**，然后选择**创建日志组**。输入一个类似的名称`/bedrock-agentcore/payments/my-logs`，然后选择您的首选保留期。

```
aws logs create-log-group --log-group-name /bedrock-agentcore/payments/my-logs
```

## IAM 权限
<a name="payments-observability-iam"></a>

您的 IAM 用户或角色必须具有以下权限才能创建日志和跨越交付资源：

```
{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "CloudWatchLogsVendedDelivery",
            "Effect": "Allow",
            "Action": [
                "logs:CreateDelivery",
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DeleteDelivery",
                "logs:DeleteDeliveryDestination",
                "logs:DeleteDeliverySource",
                "logs:DeleteLogGroup",
                "logs:DeleteResourcePolicy",
                "logs:DescribeLogGroups",
                "logs:DescribeResourcePolicies",
                "logs:GetDelivery",
                "logs:GetDeliveryDestination",
                "logs:GetDeliverySource",
                "logs:PutDeliveryDestination",
                "logs:PutDeliverySource",
                "logs:PutLogEvents",
                "logs:PutResourcePolicy",
                "logs:PutRetentionPolicy"
            ],
            "Resource": "*"
        },
        {
            "Sid": "XRayApplicationSignalsCloudTrail",
            "Effect": "Allow",
            "Action": [
                "xray:GetTraceSegmentDestination",
                "xray:ListResourcePolicies",
                "xray:PutResourcePolicy",
                "xray:PutTelemetryRecords",
                "xray:PutTraceSegments",
                "xray:UpdateTraceSegmentDestination",
                "application-signals:StartDiscovery",
                "cloudtrail:CreateServiceLinkedChannel"
            ],
            "Resource": "*"
        },
        {
            "Sid": "CreateServiceLinkedRoleForAppSignals",
            "Effect": "Allow",
            "Action": "iam:CreateServiceLinkedRole",
            "Resource": "arn:*:iam::*:role/aws-service-role/application-signals.cloudwatch.amazonaws.com/AWSServiceRoleForCloudWatchApplicationSignals"
        },
        {
            "Sid": "BedrockAgentCoreVendedLogDelivery",
            "Effect": "Allow",
            "Action": "bedrock-agentcore:AllowVendedLogDeliveryForResource",
            "Resource": "*"
        }
    ]
}
```

## Vended logs（已出售日志）
<a name="payments-observability-vended-logs"></a>

出售的日志在您配置的日志组中显示为应用程序日志。这些信息是由 AgentCore 支付服务为每次数据平面 API 调用自动生成的。

## 已售跨度
<a name="payments-observability-vended-spans"></a>

Vended span 是单个请求的跟踪记录。使用它们来可视化流入的请求流 Amazon X-Ray。每个跨度代表一个工作单元（例如，API 调用及其下游操作），使您能够识别延迟瓶颈或故障。

### 跨度名称
<a name="_span_names"></a>

AgentCore 付款每次数据平面 API 调用都会产生一个跨度。跨度名称遵循以下模式`Bedrock.AgentCore.Payments.<Operation>`：


| 跨度名称 | 说明 | 
| --- | --- | 
|  `Bedrock.AgentCore.Payments.ProcessPayment`  | 处理付款交易 | 
|  `Bedrock.AgentCore.Payments.CreatePaymentInstrument`  | 创建付款工具 | 
|  `Bedrock.AgentCore.Payments.GetPaymentInstrument`  | 检索付款工具 | 
|  `Bedrock.AgentCore.Payments.ListPaymentInstruments`  | 列出付款工具 | 
|  `Bedrock.AgentCore.Payments.DeletePaymentInstrument`  | 删除付款工具 | 
|  `Bedrock.AgentCore.Payments.GetPaymentInstrumentBalance`  | 获取乐器平衡 | 
|  `Bedrock.AgentCore.Payments.CreatePaymentSession`  | 创建付款会话 | 
|  `Bedrock.AgentCore.Payments.GetPaymentSession`  | 检索付款会话 | 
|  `Bedrock.AgentCore.Payments.ListPaymentSessions`  | 列出付款会话 | 
|  `Bedrock.AgentCore.Payments.DeletePaymentSession`  | 删除付款会话 | 

### 跨度属性
<a name="_span_attributes"></a>

每个跨度都包含以下用于筛选和分析的属性 Amazon X-Ray：


| 属性 | 说明 | 
| --- | --- | 
|  `aws.payments.payment_manager_id`  | 此请求的付款经理 ID | 
|  `aws.payments.payment_connector_id`  | 支付连接器 ID（如果适用） | 
|  `aws.payments.payment_instrument_id`  | 支付工具 ID（如果适用） | 
|  `aws.payments.payment_session_id`  | 付款会话 ID（如果适用） | 
|  `aws.payments.spend_amount`  | 付款金额（ProcessPayment 仅限） | 
|  `aws.payments.spend_currency`  | 付款货币（ProcessPayment 仅限） | 
|  `aws.payments.session_remaining_budget`  | 付款后的剩余会话预算（ProcessPayment 仅限） | 
|  `aws.payments.total_budget_amount`  | 会话总预算（ProcessPayment 仅限） | 
|  `aws.payments.merchant`  | 交易的商家地址（PayTo）（ProcessPayment 仅限） | 
|  `aws.payments.payment_agent_name`  | 代理名称（如果通过`X-Amzn-Bedrock-AgentCore-Payments-Agent-Name`标题提供） | 
|  `aws.payments.token_fetch_latency_ms`  | 从 Ident AgentCore ity 检索凭证令牌的延迟（ProcessPayment 仅限） | 

每个跨度中还包含标准 Amazon 属性：
+  `aws.region`— 该 Amazon 地区
+  `aws.account.id`— 来电者的账户 ID
+  `aws.resource.arn`— PaymentManager ARN
+  `aws.request_id`— 请求 ID
+  `http.response.status_code`— HTTP 响应状态码

## 已售指标
<a name="payments-observability-metrics"></a>

AgentCore 付款将以下指标发布到您的亚马逊 CloudWatch 命名空间。使用它们来构建仪表板、设置警报和监控支付状况。


| 指标 | 单位 | 说明 | 
| --- | --- | --- | 
|  `OperationSuccess`  | 计数 | 成功的 API 调用次数 | 
|  `OperationFailure`  | 计数 | 失败的 API 调用次数 | 
|  `OperationLatency`  | 毫秒 | End-to-end 每次 API 调用的延迟 | 
|  `SpendAmount`  | 无 | 已处理的付款金额（ProcessPayment 仅限） | 
|  `Throttles`  | 计数 | 受限制的请求数 | 
|  `UserErrors`  | 计数 | 客户端验证错误的数量 | 
|  `ActiveSessions`  | 计数 | 活跃的付款会话数 | 
|  `PaymentRequestCount`  | 计数 | 付款请求总数 | 
|  `PaymentSuccessCount`  | 计数 | 成功的付款交易 | 
|  `PaymentFailureCount`  | 计数 | 付款交易失败 | 
|  `PaymentLatency`  | 毫秒 | 付款处理延迟 | 

### 指标维度
<a name="_metric_dimensions"></a>

发布的指标采用以下维度进行筛选：
+  **操作 ** — API 操作名称（始终存在）
+  **PaymentManagerId**— 付款经理 ID（如果有）
+  **PaymentConnectorId**— 支付连接器 ID（如果可用）
+  **AgentName**— 代理名称（通过标题提供时）
+  **货币 ** — 付款货币（用于 SpendAmount 指标）

## 启用可观察性
<a name="payments-observability-enable"></a>

**Example**  
在亚马逊 Bedrock AgentCore 控制台的付款管理器详情页面上：  

1. 导航到**日志传送和跟踪**部分。

1. 将日志传送到您的 CloudWatch 日志组。

1. 启用跟踪以查看跨度。 Amazon X-Ray
支付管理器详情页面上的**可观察性**部分提供实时指标，包括会话数、API 调用、交易成功率和错误率。

```
# Step 1: Allow vended log delivery for your Payment Manager
aws bedrock-agentcore allow-vended-log-delivery-for-resource \
    --resource-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager"

# Step 2: Create a delivery source
aws logs put-delivery-source \
    --name "payments-logs" \
    --resource-arn "arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager" \
    --log-type "APPLICATION_LOGS"

# Step 3: Create a delivery destination
aws logs put-delivery-destination \
    --name "payments-log-destination" \
    --delivery-destination-configuration '{"destinationResourceArn": "arn:aws:logs:us-west-2:123456789012:log-group:/bedrock-agentcore/payments/my-logs"}'

# Step 4: Create the delivery
aws logs create-delivery \
    --delivery-source-name "payments-logs" \
    --delivery-destination-arn "arn:aws:logs:us-west-2:123456789012:delivery-destination:payments-log-destination"
```

```
import boto3

# Allow vended log delivery for your Payment Manager
agentcore_client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
agentcore_client.allow_vended_log_delivery_for_resource(
    resourceArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager"
)

# Configure CloudWatch Logs delivery
logs_client = boto3.client("logs", region_name="us-west-2")

# Create delivery source
logs_client.put_delivery_source(
    name="payments-logs",
    resourceArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:payment-manager/my-manager",
    logType="APPLICATION_LOGS"
)

# Create delivery destination
logs_client.put_delivery_destination(
    name="payments-log-destination",
    deliveryDestinationConfiguration={
        "destinationResourceArn": "arn:aws:logs:us-west-2:123456789012:log-group:/bedrock-agentcore/payments/my-logs"
    }
)

# Create the delivery
logs_client.create_delivery(
    deliverySourceName="payments-logs",
    deliveryDestinationArn="arn:aws:logs:us-west-2:123456789012:delivery-destination:payments-log-destination"
)
```

有关 AgentCore 可观测性的更多信息，请参阅可观[AgentCore 测](observability.md)性。有关网关特定的指标和跨度，请参阅[AgentCore 生成的网关可观测性数据。](observability-gateway-metrics.md)