# AgentCore 生成的网关可观测性数据
<a name="observability-gateway-metrics"></a>

以下各节描述了向 Amazon CloudWatch 输出的 AgentCore 网关指标、日志和跨度。这些指标在 CloudWatch 生成式 AI 可观测性页面上不可用。网关指标每隔一分钟进行批处理。要了解有关查看网关指标的更多信息，请参阅查[看 Amazon Bedrock AgentCore 代理的可观测性数据](observability-view.md)。

**注意**  
要为 AgentCore 网关启用服务提供的日志，您需要配置必要的 CloudWatch 资源。要了解更多信息，请参阅[为 AgentCore 运行时、内存、网关、内置工具和身份资源启用可观察性](observability-configure.md#observability-configure-cloudwatch)。

**Topics**
+ [提供的指标](#observability-gateway-metrics-provided)
+ [提供的日志数据](#observability-gateway-logs-provided)
+ [提供的跨度](#observability-gateway-vended-spans)

## 提供的指标
<a name="observability-gateway-metrics-provided"></a>

Gateway 向发布调用和使用情况指标。 CloudWatch您可以查看这些指标，也可以设置警报，以便在某些指标超过阈值时提醒您。要了解更多信息，请选择一个主题：

**Topics**
+ [调用指标](#gateway-metrics-invocation)
+ [使用情况指标](#gateway-metrics-usage)
+ [查看网关 CloudWatch 指标](#gateway-metrics-view-console)
+ [设置 CloudWatch 警报](#gateway-advanced-observability-alarms)

### 调用指标
<a name="gateway-metrics-invocation"></a>

这些指标提供有关 API 调用、性能和错误的信息。

对于这些指标，使用以下维度：
+  **操作** — API 操作的名称（例如 InvokeGateway)。
+  **协议**-协议的名称（例如 MCP)。
+  **方法** — 表示正在调用的 MCP 操作（例如 tools/list)。
+  **资源**-表示资源的标识符（例如网关 ARN）。
+  **名称**-表示工具的名称。


| 指标 | 说明 | 统计信息 | 单位 | 
| --- | --- | --- | --- | 
| Invocations | 向每个数据平面 API 发出的请求总数。无论响应状态如何，每个 API 调用都算作一次调用。 | 总和 | 计数 | 
| 节流 | 服务限制的请求数（状态码 429）。 | 总和 | 计数 | 
| SystemErrors | 失败的请求数，状态码为 5xx。 | 总和 | 计数 | 
| UserErrors | 以 4xx 状态码失败的请求数，429 除外。 | 总和 | 计数 | 
| 延迟 | 从服务收到请求到开始发送第一个响应令牌之间经过的时间。换句话说，就是初始响应时间。 | 平均值、最小值、最大值、p50、p90、p99 | 毫秒 | 
| Duration | 从收到请求到发送最终响应令牌之间的总时间。表示请求的完整端到端处理时间。 | 平均值、最小值、最大值、p50、p90、p99 | 毫秒 | 
| TargetExecutionTime | 通过 Lambda/OpenAPI /等执行目标所花费的总时间。这有助于确定目标对总延迟的贡献。 | 平均值、最小值、最大值、p50、p90、p99 | 毫秒 | 

### 使用情况指标
<a name="gateway-metrics-usage"></a>

这些指标提供有关您的网关使用情况的信息。


| 指标 | 说明 | 统计信息 | 单位 | 
| --- | --- | --- | --- | 
| TargetType | 每种目标类型（MCP、Lambda、OpenAPI）所处理的请求总数。 | 总和 | 计数 | 

### 查看网关 CloudWatch 指标
<a name="gateway-metrics-view-console"></a>

有关查看 CloudWatch 指标的更多信息，请参阅 [Amazon CloudWatch 用户指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/)中的[查看可用指标](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html)。以下过程向您展示如何查看网关的指标：

 **在控制台中查看网关指标** 

1. 打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。

1. 在左侧导航窗格中，选择 “**指标” 部分下的 “所有****指标**”。

1. 在 “**浏览**” 下，从显示当前 AWS 区域的下拉菜单中，选择您想要衡量指标的区域。

1. 选择 **AWS/Bedrock-AgentCore** 命名空间。

1. 选择一个维度（例如 **操作**）或尺寸组合（例如 **方法、操作、协议**），用于查看其指标。

1. 要将指标添加到 CloudWatch 图表中，请选中该指标旁边的复选框。

### 设置 CloudWatch 警报
<a name="gateway-advanced-observability-alarms"></a>

您可以使用 [PutMetricAlarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html)API 操作设置 CloudWatch 警报，以便在某些指标超过阈值时提醒您。例如，您可能希望在错误率超过 5% 或延迟超过 1 秒时收到通知。

以下示例说明如何使用 AWS CLI 创建错误率高的警报：

```
aws cloudwatch put-metric-alarm \
  --alarm-name "HighErrorRate" \
  --alarm-description "Alarm when error rate exceeds 5%" \
  --metric-name "SystemErrors" \
  --namespace "AWS/Bedrock-AgentCore" \
  --statistic "Sum" \
  --dimensions "Name=Resource,Value=my-gateway-arn" \
  --period 300 \
  --evaluation-periods 1 \
  --threshold 5 \
  --comparison-operator "GreaterThanThreshold" \
  --alarm-actions "arn:aws:sns:us-west-2:123456789012:my-topic"
```

当系统错误数在 5 分钟内超过 5 时，将触发此警报。当警报触发时，它将向指定的 SNS 主题发送通知。

## 提供的日志数据
<a name="observability-gateway-logs-provided"></a>

AgentCore 提供日志，可帮助您监控关键 AgentCore 网关资源进程并对其进行故障排除。要启用此日志数据，您需要创建一个日志目标。

AgentCore 可以将日志输出到日 CloudWatch 志、Amazon S3 或 Firehose 流。如果您使用 CloudWatch 日志目标，则这些日志将存储在默认日志组下`/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/{gateway_id}`或以开头的自定义日志组下`/aws/vendedlogs/`。要了解更多信息，请参阅[为 AgentCore 运行时、内存、网关、内置工具和身份资源启用可观察性](observability-configure.md#observability-configure-cloudwatch)。

AgentCore 记录网关资源的以下信息：
+ 开始和完成网关请求处理
+ 目标配置的错误消息
+ 授权标头缺失或不正确的 MCP 请求
+ 请求参数（工具、方法）不正确的 MCP 请求

在网关上执行任何 MCP 操作时，您还可以将请求和响应正文作为 Vended Logs 集成的一部分。他们可以对这些日志进行进一步分析，使用`span_id`和`trace_id`字段来连接已发送的跨度和正在发出的日志。有关使用客户管理的 KMS 密钥加密网关的更多信息，请参阅 [Amazon Bedro AgentCore ck Gateway 的高级功能和主题](gateway-advanced.md)。

日志示例：

```
{
    "resource_arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gatewayid>",
    "event_timestamp": 1759370851622,
    "body": {
        "isError": false,
        "log": "Started processing request with requestId: 1",
        "requestBody": "{id=1, jsonrpc=2.0, method=tools/call, params={name=target-quick-start-f9scus___LocationTool, arguments={location=seattle}}}",
        "id": "1"
    },
    "account_id": "123456789012",
    "request_id": "12345678-1234-1234-1234-123456789012",
    "trace_id": "160fc209c3befef4857ab1007d041db0",
    "span_id": "81346de89c725310"
}
```

包含响应正文的示例日志：

```
{
    "resource_arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/<gatewayid>",
    "event_timestamp": 1759370853807,
    "body": {
        "isError": false,
        "responseBody": "{jsonrpc=2.0, id=1, result={isError=false, content=[{type=text, text=\"good\"}]}}",
        "log": "Successfully processed request with requestId: 2",
        "id": "1"
    },
    "account_id": "123456789012",
    "request_id": "12345678-1234-1234-1234-123456789012",
    "trace_id": "160fc209c3befef4857ab1007d041db0",
    "span_id": "81346de89c725310"
}
```

## 提供的跨度
<a name="observability-gateway-vended-spans"></a>

AgentCore 支持符合 OTEL 标准的 vended span，您可以使用这些跨度来跟踪正在使用的不同基元间的调用。

工具调用的卖出跨度示例：
+  `kind:SERVER`-跟踪整体执行细节、调用的工具、网关详细信息、 AWS 请求 ID、跟踪和跨度 ID。
+  `kind:CLIENT`-涵盖调用的特定目标及其相关详细信息，例如目标类型、目标执行时间、目标执行开始和结束时间等。

对于其他 MCP 方法调用，仅发出`kind:SERVER`跨度。

当这些跨度发出指标时，要调查特定跨度发生故障的原因，Gateway 用户必须检查已出售的日志。例如，`spanId`各种字段`aws.request.id`可以帮助将这些跨度和日志拼接在一起。


| 操作 | 跨度属性 | 说明 | 
| --- | --- | --- | 
| 列表工具 | aws.operation.name、aws.resource.arn、aws.request.id、aws.account.id、gateway.id、aws.xray.origin、aws.resource.type、aws.region、latency\_ms、error\_type、js.resource.type、js.resource.type、js.resource.type、js.resource.type、js.resource.typency\_ms | 列出连接到网关的工具 | 
| 通话工具 | aws.operation.name、aws.resource.arn、aws.request.id、aws.account.id、gateway.id、aws.xray.origin、aws.resource.type、aws.region、latency\_ms、error\_type、js.resource.type、js.resource.type、js.resource.type、js.resource.type、js.resource.typency\_ms，tool.name | 调用特定的工具。会发出两个跨度：1. `kind:SERVER`它跟踪总体执行细节（成功/不成功）、调用的工具、网关详细信息、 AWS 请求 ID、跟踪和跨度 ID。2. `kind:CLIENT`其中涵盖了被调用的特定目标及其相关细节，例如目标类型、目标执行时间、目标执行开始和结束时间等。 | 
| 搜索工具 | aws.operation.name、aws.resource.arn、aws.request.id、aws.account.id、gateway.id、aws.xray.origin、aws.resource.type、aws.region、latency\_ms、error\_type、js.resource.type、js.resource.type、js.resource.type、js.resource.type、js.resource.typency\_ms，tool.name | 根据输入查询，搜索十种最相关的工具 |