AgentCore에서 생성한 게이트웨이 관찰성 데이터

다음 섹션에서는 AgentCore에서 Amazon CloudWatch로 출력하는 게이트웨이 지표, 로그 및 스팬에 대해 설명합니다. 이러한 지표는 CloudWatch 생성형 AI 관찰성 페이지에서 사용할 수 없습니다. 게이트웨이 지표는 1분 간격으로 일괄 처리됩니다. 게이트웨이 지표 보기에 대한 자세한 내용은 Amazon Bedrock AgentCore 에이전트의 관찰성 데이터 보기를 참조하세요.

제공된 지표

Gateway는 호출 및 사용량 지표를 CloudWatch에 게시합니다. 이러한 지표를 보고 특정 지표가 임계값을 초과할 때 알림을 받도록 경보를 설정할 수도 있습니다. 자세한 내용을 알아보려면 주제를 선택합니다.

호출 지표

이러한 지표는 API 호출, 성능 및 오류에 대한 정보를 제공합니다.

이러한 지표에는 다음 차원이 사용됩니다.

사용량 지표

이러한 지표는 게이트웨이가 사용되는 방식에 대한 정보를 제공합니다.

게이트웨이 CloudWatch 지표 보기

CloudWatch 지표 보기에 대한 자세한 내용은 Amazon CloudWatch 사용 설명서의 사용 가능한 지표 보기를 참조하세요. 다음 절차에서는 게이트웨이에 대한 지표를 보는 방법을 보여줍니다.

콘솔에서 게이트웨이 지표를 보려면

CloudWatch 경보 설정

PutMetricAlarm 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 런타임, 메모리, 게이트웨이, 내장 도구 및 자격 증명 리소스에 대한 관찰성 활성화를 참조하세요.

AgentCore는 게이트웨이 리소스에 대해 다음 정보를 기록합니다.

또한 게이트웨이에서 MCP 작업이 수행될 때 Vended Logs 통합의 일부로 요청 및 응답 본문을 볼 수 있습니다. 및 span_id trace_id 필드를 사용하여 내보내는 판매된 스팬과 로그를 연결하여 이러한 로그에 대한 추가 분석을 수행할 수 있습니다. 고객 관리형 KMS 키를 사용하여 게이트웨이를 암호화하는 방법에 대한 자세한 내용은 Amazon Bedrock AgentCore Gateway의 고급 기능 및 주제를 참조하세요.

샘플 로그:

{
    "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"
}

제공된 범위

AgentCore는 사용 중인 다양한 프리미티브에서 호출을 추적하는 데 사용할 수 있는 OTEL 호환 벤딩 스팬을 지원합니다.

도구 호출을 위한 샘플 벤딩 스팬:

다른 MCP 메서드 호출의 경우 kind:SERVER 범위만 내보내집니다.

이러한 스팬은 지표를 내보내지만 특정 스팬에서 장애가 발생한 이유를 조사하기 위해 Gateway 사용자는 벤딩된 로그를 확인해야 합니다. 예를 들어 spanId 또는와 같은 다양한 필드는 이러한 스팬과 로그를 함께 연결하는 데 도움이 될 aws.request.id 수 있습니다.