本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AgentCore 生成的网关可观测性数据
以下部分描述了向亚马逊 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)
## 提供的指标
Gateway 将调用和使用指标发布到。 CloudWatch您可以查看这些指标，还可以设置警报，在某些指标超过阈值时提醒您。要了解更多信息，请选择一个主题：
**Topics**
+ [调用指标](#gateway-metrics-invocation)
+ [使用情况指标](#gateway-metrics-usage)
+ [查看网关 CloudWatch 指标](#gateway-metrics-view-console)
+ [设置 CloudWatch 警报](#gateway-advanced-observability-alarms)
### 调用指标
这些指标提供有关 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 | 毫秒 |
### 使用情况指标
这些指标提供有关如何使用您的网关的信息。
| 指标 | 说明 | 统计信息 | 单位 |
| --- | --- | --- | --- |
| TargetType | 每种目标类型（MCP、Lambda、OpenAPI）所服务的请求总数。 | 总和 | 计数 |
### 查看网关 CloudWatch 指标
有关查看 CloudWatch 指标的更多信息，请参阅[亚马逊 CloudWatch 用户指南[中的](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html)查看可用指标](https://docs.amazonaws.cn/AmazonCloudWatch/latest/DeveloperGuide/)。以下过程向您展示如何查看网关的指标：
**在控制台中查看网关指标 **
1. 在处打开 CloudWatch 控制台[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)。
1. 在左侧导航窗格中，选择 “指标” ** 部分**下的 “**所有**指标”。
1. 在 “**浏览” 下**，从显示当前 Amazon 区域的下拉菜单中，选择要衡量指标的区域。
1. 选择 **AWS/Bedrock-AgentCore** 命名空间。
1. 选择一个维度（例如**操作**）或维度组合（例如**方法、操作、协议**）来查看其指标。
1. 要向 CloudWatch 图表添加指标，请选中该指标旁边的复选框。
### 设置 CloudWatch 警报
您可以使用 [ PutMetricAlarm ](https://docs.amazonaws.cn/AmazonCloudWatch/latest/APIReference/API_PutMetricAlarm.html) API 操作设置 CloudWatch 警报，以便在某些指标超过阈值时提醒您。例如，您可能希望在错误率超过 5% 或延迟超过 1 秒时收到通知。
以下示例向您展示如何使用 Amazon 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 主题发送通知。
## 提供的日志数据
AgentCore 提供日志，帮助您监控关键 AgentCore 网关资源进程并对其进行故障排除。要启用此日志数据，您需要创建日志目的地。
AgentCore 可以将日志输出到日 CloudWatch 志、亚马逊 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 Bedrock Gateway 的[高级功能和主题。 AgentCore ](gateway-advanced.md)
日志示例：
```
{
"resource_arn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/",
"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/",
"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"
}
```
## 提供的跨度
AgentCore 支持符合 OTEL 标准的供应商跨度，可用于跟踪正在使用的不同原语之间的调用。
工具调用的销售跨度示例：
+ `kind:SERVER`-跟踪整体执行详情、调用的工具、网关详细信息、 Amazon 请求 ID、跟踪和跨度 ID。
+ `kind:CLIENT`-涵盖调用的特定目标及其相关详细信息，例如目标类型、目标执行时间、目标执行开始和结束时间等。
对于其他 MCP 方法调用，仅发射`kind:SERVER`跨度。
虽然这些跨度会发出指标，但要调查特定跨度出现故障的原因，网关用户必须检查出售的日志。例如，`spanId`各种字段`aws.request.id`可以帮助将这些跨度和日志拼接在一起。
| 操作 | 跨度属性 | 说明 |
| --- | --- | --- |
| 清单工具 | aws.operation.name、aws.resource.arn、aws.request.id、gateway.id、aws.xray.origin、aws.resource.type、aws.region、latency\_ms、error\_type、jsonrpc.error.code、http.response.status\_code、gateway.name、url.path、overhead\_lat\_latus\_code ency\_ms | 列出连接到网关的工具 |
| 通话工具 | aws.operation.name、aws.resource.arn、aws.request.id、gateway.id、aws.xray.origin、aws.resource.type、aws.region、latency\_ms、error\_type、jsonrpc.error.code、http.response.status\_code、gateway.name、url.path、overhead\_lat\_latus\_code ency\_ms，工具名称 | 调用特定工具。发射了两个跨度：1。`kind:SERVER`它跟踪整体执行细节（成功/不成功）、调用的工具、网关详细信息、 Amazon 请求 ID、跟踪和跨度 ID。2.`kind:CLIENT`其中涵盖了调用的特定目标及其相关详细信息，例如目标类型、目标执行时间、目标执行开始和结束时间等。 |
| 搜索工具 | aws.operation.name、aws.resource.arn、aws.request.id、gateway.id、aws.xray.origin、aws.resource.type、aws.region、latency\_ms、error\_type、jsonrpc.error.code、http.response.status\_code、gateway.name、url.path、overhead\_lat\_latus\_code ency\_ms，工具名称 | 根据输入查询，搜索十个最相关的工具 |