게이트웨이 규칙과의 상호 작용 스태킹 시맨틱 항목 일치 및 특이도 평가 순서 서비스 관리형 제한과의 상호 작용 제한된 응답 전파 타이밍 적용 정확도 및 최종 일관성 Fail-open 동작 OpenTelemetry 스팬을 사용한 추적

속도 제한 적용

이 주제에서는 다른 게이트웨이 기능과의 상호 작용, 제한된 응답 형식 및 관찰성을 포함하여 게이트웨이가 런타임 시 속도 제한을 평가하고 적용하는 방법을 설명합니다.

게이트웨이 규칙과의 상호 작용

게이트웨이는 게이트웨이 규칙보다 먼저 속도 제한을 평가합니다. 속도 제한이 요청을 제한하는 경우 요청은 규칙 평가 단계에 도달하지 않습니다.

스태킹 시맨틱

요청에 여러 속도 제한이 적용되는 경우 게이트웨이는 AND 로직을 사용합니다. 요청을 진행하려면 모든 속도 제한이 통과해야 합니다. 단일 속도 제한이 요청을 거부하면 게이트웨이가 요청을 제한합니다.

항목 일치 및 특이도

속도 제한에 항목이 여러 개 있는 경우 게이트웨이는 확인된 차원 값에 가장 구체적인 일치하는 항목을 선택합니다.

정확한 값 일치가 * 항목보다 우선합니다.
* 값은 "이 차원의 모든 값에이 속도를 적용"을 의미하며 기본 항목 역할을 합니다.
다중 차원 속도 제한의 경우 게이트웨이는 프로그레시브 후행 폴백을 사용합니다. 먼저 완전히 정확히 일치를 시도한 다음 일치 항목이 발견될 때까지 후행 차원을 한 번에 * 하나로 바꿉니다.

다음 예제에서는 확인된 값이 일 dimensionKeys: ["targetName", "toolName"] 때 항목이 속도 제한과 일치하는 방법을 보여줍니다. ["my-target", "readData"]

입력 차원	일치 여부	이유
`{"targetName": "my-target", "toolName": "readData"}`	예(먼저 확인)	두 차원이 정확히 일치합니다. 가장 구체적입니다.
`{"targetName": "my-target", "toolName": "*"}`	예(초)	첫 번째 차원과 두 번째 차원`*`이 정확히 일치합니다.
`{"targetName": "", "toolName": ""}`	예(마지막으로 확인됨)	기본 항목입니다. 최소로 구체적입니다.

일치하는 첫 번째 항목이 성공합니다. 일치하는 항목이 없는 경우(*기본값이 없는 경우) 해당 요청에 대한 속도 제한을 건너뜁니다.

평가 순서

게이트웨이는 다음 순서로 속도 제한을 평가합니다.

게이트웨이는 더 많은 차원 키를 먼저 사용하여 속도 제한을 평가합니다(보다 구체적인 제한이 우선함).
동일한 차원 수 내에서 게이트웨이는 먼저 더 엄격한(낮은) 속도로 속도 제한을 평가합니다.
첫 번째 거부 시 평가 단락 - 게이트웨이는 나머지 속도 제한을 평가하지 않습니다.

서비스 관리형 제한과의 상호 작용

게이트웨이는 고객 정의 속도 제한과 서비스 관리형 제한을 모두 적용합니다. 모든 요청에 대한 유효 비율은 다음 두 가지의 최소값입니다.

게이트웨이는 먼저 고객 정의 속도 제한을 평가합니다.
요청이 고객 제한을 통과하면 서비스 관리형 제한이 평가됩니다.
두 소스 중 하나에서 거부하면 제한이 발생합니다.

제한된 응답

요청이 제한되면 게이트웨이는 응답 본문의 retryAfter 값을 포함하는 프로토콜별 오류 응답을 반환합니다.

HTTP 프로토콜:


{
    "error": "Rate limit exceeded",
    "success": false,
    "limitKey": "rl-abc123/targetName=my-target",
    "metric": "requests",
    "retryAfter": 1
}

MCP 프로토콜(JSON-RPC):


{
    "jsonrpc": "2.0",
    "id": "request-1",
    "error": {
        "code": -32003,
        "message": "Rate limit exceeded",
        "data": {
            "limitKey": "rl-abc123/targetName=my-target",
            "metric": "requests",
            "retryAfter": 1
        }
    }
}

OpenAI 호환 프로토콜:


{
    "error": {
        "message": "Rate limit exceeded",
        "type": "rate_limit_error",
        "code": "429",
        "limitKey": "rl-abc123/qualifiedModelId=anthropic.claude-3-sonnet",
        "metric": "tokens",
        "retryAfter": 60
    }
}

Anthropic 호환 프로토콜:


{
    "type": "error",
    "error": {
        "type": "rate_limit_error",
        "message": "Rate limit exceeded",
        "limitKey": "rl-abc123/qualifiedModelId=anthropic.claude-3-sonnet",
        "metric": "tokens",
        "retryAfter": 60
    }
}

retryAfter 필드는 호출자가 재시도하기 전에 기다려야 하는 초 수를 나타냅니다. 클라이언트 측 재시도 로직에서이 값을 직접 사용합니다.

전파 타이밍

속도 제한 변경(생성, 업데이트, 삭제)은 30초 이내에 데이터 영역으로 전파됩니다. 전파 중:

전파가 완료될 때까지 새 속도 제한이 적용되지 않습니다.
업데이트된 속도 제한은 업데이트가 전파될 때까지 이전 구성을 계속 적용합니다.
삭제된 속도 제한은 삭제가 전파될 때까지 계속 적용됩니다.

적용 정확도 및 최종 일관성

속도 제한 적용은 정확한 것이 아니라 최종적으로 일관됩니다. 적용 정확도는 제한이 트래픽을 수신하기 시작한 순간에 근사치이며 트래픽이 계속됨에 따라 개선됩니다. 따라서 관찰하는 정확도는 트래픽 패턴에 따라 달라집니다.

다음과 같은 동작이 예상됩니다.

콜드 제한은 처음에 과도하게 허용됩니다. 콜드 제한은 새로 생성되거나 최근 트래픽이 없는 제한입니다. 초기 기간 동안 게이트웨이는 적용이 수렴되기 전에 초과 허용(구성된 속도보다 많은 요청 허용)할 수 있습니다. 한도가 연속 트래픽에 도달하면 정확도가 향상되고 관찰된 스로틀 속도가 구성된 속도에 가깝게 안정화됩니다.
지속적인 트래픽은 정확하게 적용되지만 짧은 버스트는 적용되지 않을 수 있습니다. 콜드 제한에 대한 짧은 버스트는 제한 없이 통과할 수 있습니다. 제한이 워밍업될 때 정확도가 향상되므로 지속적인 트래픽과 동일한 전송 속도가 적용됩니다. 적용을 관찰하거나 시연하려면 짧은 버스트가 아닌 몇 분 동안 지속적인 트래픽을 제한으로 보냅니다. 예를 들어 초당 요청 수가 4개로 제한되면 게이트웨이가 처음 1초 동안 5번째 요청을 조절하지 않을 수 있습니다. 초당 5개의 요청을 지속적으로 전송하면 제한이 워밍업된 후 추가 요청이 계속 조절됩니다.
매우 낮은 속도는 정확도가 떨어집니다. 초당 약 1개의 요청(예: 작은 requests-per-minute 수 제한)보다 낮은 속도는 정확하게 적용하기 더 어렵고 변동성이 더 큽니다. 정확한 적용이 중요한 경우 더 높은 속도를 선호하고 매우 낮은 제한을 대략적인 것으로 취급합니다.
토큰 제한은 더 느리게 수렴됩니다. Token-per-minute 제한은 모델이 응답한 후에만 추적된 사용량 합계를 업데이트(조정)합니다. 몇 초 또는 몇 분 동안 진행 중인 요청은 완료될 때까지 예산에 대한 예상 비용만 보유합니다. 이렇게 하면 게이트웨이가 요청 제한을 기준으로 요청을 과도하게 허용할 수 있는 기간이 확장됩니다. 자세한 내용은 토큰 속도 제한 FAQ를 참조하세요.

공정한 사용 및 백엔드 보호에 대한 제한을 설계합니다. 즉, 임계값을 초과하는 즉시 정확한 요청 수를 차단하지 않고 지속적인 기간 동안 버스트를 부드럽게 하고 시끄러운 이웃으로부터 대상을 보호합니다. 속도 제한은 정확한 요청 게이트가 아닙니다. 다음 섹션에 설명된 대로 속도 제한도 보안 경계가 아닙니다.

Fail-open 동작

게이트웨이는 속도 제한 평가에 페일 오픈 시맨틱을 사용합니다. 다음 표에서는 속도 제한 시스템에서 오류가 발생할 때의 동작을 설명합니다.

시나리오	결정	이론적 근거
속도 제한 서비스 제한 시간	허용	가용성이 적용보다 우선합니다.
요청에서 해결할 수 없는 차원 키	건너뛰기(허용)	이 요청 유형에는 속도 제한이 적용되지 않습니다.
속도 제한 캐시 새로 고침 실패	오래된 데이터로 재시도	캐시가 복구될 때까지 마지막으로 알려진 구성이 사용됩니다.

중요

페일 오픈 동작으로 인해 보안 경계로서 속도 제한에만 의존하지 마십시오. 트래픽 관리 및 서비스 품질에 속도 제한을 사용하고 보안 적용에 인증, 권한 부여 및 WAF 규칙을 사용합니다.

OpenTelemetry 스팬을 사용한 추적

게이트웨이는 고객 속도 제한이 평가되는 모든 요청에 대해 서버 스팬에서 OpenTelemetry(OTEL) 스팬 속성을 내보냅니다. 디버깅 및 모니터링에 이러한 속성을 사용합니다.

속성	설명	예제
`aws.agentcore.gateway.throttle.customer.decision`	이 요청에 대한 적용 결정입니다.	`allowed` 또는 `throttled`
`aws.agentcore.gateway.throttle.customer.limit_key`	요청을 거부한 속도 제한`rateLimitId`의 입니다. 결정이 인 경우에만 표시됩니다`throttled`.	`per-target-rps`
`aws.agentcore.gateway.throttle.customer.metric`	소진된 지표 유형입니다. 결정이 인 경우에만 표시됩니다`throttled`.	`requests`
`aws.agentcore.gateway.throttle.customer.matched_entry`	스로틀을 트리거한 항목의 쉼표로 구분된 확인 차원 값입니다. 결정이 인 경우에만 표시됩니다`throttled`.	`my-target,alice`
`aws.agentcore.gateway.throttle.customer.evaluated`	이 요청에 대해 확인된 모든 속도 제한 버킷의 정렬된 목록입니다. 각 항목에는 속도 제한 ID, 지표 및 확인된 차원 값이 표시됩니다. `allowed` 및 `throttled` 결정 모두에 적용됩니다.	`["per-target-rps:requests:my-target", "per-caller-rpm:requests:alice"]`

evaluated 속성은 요청이 허용된 경우에도 요청에 적용되는 속도 제한을 이해하는 데 유용합니다. 목록의 각 항목은 형식을 따릅니다{rateLimitId}:{metric}:{resolvedDimVal1,dimVal2,…}.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

Metrics

API 예제