# AgentCore에서 생성한 게이트웨이 관찰성 데이터
다음 섹션에서는 AgentCore에서 Amazon CloudWatch로 출력하는 게이트웨이 지표, 로그 및 스팬에 대해 설명합니다. 이러한 지표는 CloudWatch 생성형 AI 관찰성 페이지에서 사용할 수 없습니다. 게이트웨이 지표는 1분 간격으로 일괄 처리됩니다. 게이트웨이 지표 보기에 대한 자세한 내용은 [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 작업(예: 도구/목록)을 나타냅니다.
+ **리소스** - 리소스의 식별자(예: 게이트웨이 ARN)를 나타냅니다.
+ **이름** - 도구의 이름을 나타냅니다.
| 지표 | 설명 | 통계 | 단위 |
| --- | --- | --- | --- |
| Invocations | 각 데이터 영역 API에 대한 총 요청 수입니다. 각 API 호출은 응답 상태에 관계없이 하나의 호출로 계산됩니다. | Sum | 개수 |
| 제한 | 서비스에서 제한한 요청 수(상태 코드 429)입니다. | Sum | 개수 |
| SystemErrors | 5xx 상태 코드로 실패한 요청 수입니다. | Sum | 개수 |
| UserErrors | 429를 제외한 4xx 상태 코드로 실패한 요청 수입니다. | Sum | 개수 |
| Latency | 서비스가 요청을 수신하는 시점과 첫 번째 응답 토큰 전송을 시작하는 시점 사이의 경과 시간입니다. 즉, 초기 응답 시간입니다. | 평균, 최소, 최대, p50, p90, p99 | 밀리초 |
| 지속 시간 | 요청 수신과 최종 응답 토큰 전송 사이에 경과된 총 시간입니다. 요청의 전체 end-to-end 처리 시간을 나타냅니다. | 평균, 최소, 최대, p50, p90, p99 | 밀리초 |
| TargetExecutionTime | Lambda / OpenAPI / 등을 통해 대상을 실행하는 데 걸린 총 시간입니다. 이렇게 하면 총 지연 시간에 대한 대상의 기여도를 결정하는 데 도움이 됩니다. | 평균, 최소, 최대, p50, p90, p99 | 밀리초 |
### 사용량 지표
이러한 지표는 게이트웨이가 사용되는 방식에 대한 정보를 제공합니다.
| 지표 | 설명 | 통계 | 단위 |
| --- | --- | --- | --- |
| TargetType | 각 대상 유형(MCP, Lambda, OpenAPI)에서 처리하는 총 요청 수입니다. | Sum | 개수 |
### 게이트웨이 CloudWatch 지표 보기
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 경보 설정
[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 주제에 알림을 보냅니다.
## 제공된 로그 데이터
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 요청(도구, 메서드)
또한 게이트웨이에서 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/",
"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` - 전체 실행 세부 정보, 호출된 도구, 게이트웨이 세부 정보, 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, 오버헤드\_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, 오버헤드\_latency\_ms, tool.name | 특정 도구를 호출합니다. 1. 전체 실행 세부 정보(성공/비성공), 호출된 도구, 게이트웨이 세부 정보, 요청 ID, 추적 및 스팬 ID를 추적`kind:SERVER`하는 두 개의 스팬 AWS 이 구현됩니다. 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, 오버헤드\_latency\_ms, tool.name | 입력 쿼리를 고려하여 가장 관련성이 높은 도구 10개 검색 |