# AgentCore 產生的閘道可觀測性資料
<a name="observability-gateway-metrics"></a>

下列各節說明 AgentCore 對 Amazon CloudWatch 的閘道指標、日誌和範圍輸出。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)。
+  **Protocol** – 通訊協定的名稱 （例如 MCP)。
+  **方法** – 代表要叫用的 MCP 操作 （例如工具/清單）。
+  **資源** – 代表資源的識別符 （例如閘道 ARN)。
+  **名稱** – 代表工具的名稱。


| 指標 | 說明 | 統計資料 | 單位 | 
| --- | --- | --- | --- | 
| 調用 | 對每個資料平面 API 提出的請求總數。無論回應狀態為何，每個 API 呼叫都會計為一個叫用。 | 總和 | 計數 | 
| 限流 | 服務調節的請求數 （狀態碼 429)。 | 總和 | 計數 | 
| SystemErrors | 使用 5xx 狀態碼失敗的請求數量。 | 總和 | 計數 | 
| UserErrors | 使用 4xx 狀態碼失敗的請求數量，但 429 除外。 | 總和 | 計數 | 
| 延遲 | 從服務收到請求到開始傳送第一個回應字符所經過的時間。換句話說，初始回應時間。 | 平均值、最小值、最大值、p50、p90、p99 | 毫秒 | 
| 持續時間 | 從接收請求到傳送最終回應字符所經過的總時間。代表請求的完整end-to-end處理時間。 | 平均值、最小值、最大值、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. 透過 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 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 秒時收到通知。

下列範例說明如何使用 CLI AWS 建立高錯誤率的警示：

```
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 Logs、Amazon S3 或 Firehose 串流。如果您使用 CloudWatch Logs 目的地，這些日誌會存放在預設日誌群組下`/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/{gateway_id}`或以 `/aws/vendedlogs/` 開頭的自訂日誌群組下。請參閱[啟用 AgentCore 執行期、記憶體、閘道、內建工具和身分資源的可觀測性](observability-configure.md#observability-configure-cloudwatch)，以進一步了解。

AgentCore 會記錄閘道資源的下列資訊：
+ 閘道請求處理的開始和完成
+ 目標組態的錯誤訊息
+ 缺少授權標頭或授權標頭不正確的 MCP 請求
+ 具有不正確請求參數的 MCP 請求 （工具、方法）

在 Gateway 上執行任何 MCP 操作時，您也可以在 Vended Logs 整合中查看請求和回應內文。他們可以使用這些 `span_id`和 `trace_id` 欄位，進一步分析這些日誌，以連接所發出的已佈建跨度和日誌。如需使用客戶受管 KMS 金鑰加密閘道的詳細資訊，請參閱 [Amazon Bedrock AgentCore 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 合規的付費範圍，您可以使用這些範圍來追蹤使用中不同基本概念的調用。

用於工具調用的範例已佈建跨度：
+  `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， jsonrpc.error.code， http.method， http.response.status\_code， gateway.name， url.path， overhead\_latency\_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， jsonrpc.error.code， http.method， http.response.status\_code， gateway.name， url.path， overhead\_latency\_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， jsonrpc.error.code， http.method， http.response.status\_code， gateway.name， url.path， overhead\_latency\_ms， tool.name | 為輸入查詢搜尋十種最相關的工具 |