Interaksi dengan aturan gateway Semantik menumpuk Pencocokan entri dan spesifisitas Urutan evaluasi Interaksi dengan batas yang dikelola layanan Tanggapan yang dibatasi Waktu propagasi Akurasi penegakan hukum dan konsistensi akhirnya Fail-open perilaku Menelusuri dengan OpenTelemetry bentang

Penegakan batas tarif

Topik ini menjelaskan bagaimana gateway mengevaluasi dan memberlakukan batas kecepatan saat runtime, termasuk interaksi dengan fitur gateway lainnya, format respons yang dibatasi, dan pengamatan.

Interaksi dengan aturan gateway

Gateway mengevaluasi batas tarif sebelum aturan gateway. Jika batas tarif membatasi permintaan, permintaan tidak pernah mencapai tahap evaluasi aturan.

Semantik menumpuk

Ketika beberapa batas tarif berlaku untuk permintaan, gateway menggunakan logika AND — semua batas tarif harus lulus agar permintaan dapat dilanjutkan. Jika ada batas tarif tunggal yang menolak permintaan, gateway akan melumpukannya.

Pencocokan entri dan spesifisitas

Ketika batas tarif memiliki beberapa entri, gateway memilih entri pencocokan paling spesifik untuk nilai dimensi yang diselesaikan:

Pencocokan nilai yang tepat diutamakan daripada * entri.
*Nilai berarti “terapkan tarif ini ke semua nilai dimensi ini” - ini bertindak sebagai entri default.
Untuk batas laju multi-dimensi, gateway menggunakan fallback trailing progresif: pertama-tama ia mencoba pencocokan persis penuh, kemudian mengganti dimensi trailing dengan * satu per satu sampai kecocokan ditemukan.

Contoh berikut menunjukkan bagaimana entri dicocokkan untuk batas tarif dengan dimensionKeys: ["targetName", "toolName"] kapan nilai yang diselesaikan adalah["my-target", "readData"]:

Dimensi entri	Pertandingan?	Mengapa
`{"targetName": "my-target", "toolName": "readData"}`	Ya (diperiksa terlebih dahulu)	Cocokan tepat pada kedua dimensi. Paling spesifik.
`{"targetName": "my-target", "toolName": "*"}`	Ya (diperiksa kedua)	Cocokan tepat pada dimensi pertama, `*` pada dimensi kedua.
`{"targetName": "", "toolName": ""}`	Ya (dicentang terakhir)	Entri default. Paling tidak spesifik.

Entri pencocokan pertama menang. Jika tidak ada entri yang cocok (dan tidak ada * default), batas tarif dilewati untuk permintaan itu.

Urutan evaluasi

Gateway mengevaluasi batas tarif dalam urutan sebagai berikut:

Gateway mengevaluasi batas tarif dengan lebih banyak kunci dimensi terlebih dahulu (batas yang lebih spesifik diprioritaskan).
Dalam jumlah dimensi yang sama, gateway mengevaluasi batas tarif dengan tarif yang lebih ketat (lebih rendah) terlebih dahulu.
Evaluasi korsleting pada penolakan pertama — gateway tidak mengevaluasi batas tarif yang tersisa.

Interaksi dengan batas yang dikelola layanan

Gateway memberlakukan batas tarif yang ditentukan pelanggan dan batas yang dikelola layanan. Tingkat efektif untuk permintaan apa pun adalah minimum dari keduanya:

Gateway mengevaluasi batas tarif yang ditentukan pelanggan terlebih dahulu.
Jika permintaan melewati batas pelanggan, batas yang dikelola layanan dievaluasi.
Penolakan dari salah satu sumber menghasilkan pelambatan.

Tanggapan yang dibatasi

Ketika permintaan dibatasi, gateway mengembalikan respons kesalahan khusus protokol yang berisi retryAfter nilai dalam badan respons.

Protokol HTTP:


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

Protokol 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-compatible protokol:


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

Anthropic-compatible protokol:


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

Bid retryAfter ang menunjukkan berapa detik penelepon harus menunggu sebelum mencoba lagi. Gunakan nilai ini secara langsung dalam logika coba ulang sisi klien Anda.

Waktu propagasi

Perubahan batas laju (buat, perbarui, hapus) menyebar ke bidang data dalam waktu 30 detik. Selama propagasi:

Batas tarif baru tidak diberlakukan sampai propagasi selesai.
Batas tarif yang diperbarui terus menerapkan konfigurasi sebelumnya hingga pembaruan menyebar.
Batas tarif yang dihapus terus diberlakukan hingga penghapusan menyebar.

Akurasi penegakan hukum dan konsistensi akhirnya

Penegakan batas tarif pada akhirnya konsisten daripada tepat. Akurasi penegakan adalah perkiraan pada saat-saat setelah batas mulai menerima lalu lintas, dan meningkat saat lalu lintas berlanjut. Oleh karena itu, akurasi yang Anda amati tergantung pada pola lalu lintas Anda.

Perilaku berikut diharapkan:

Batas dingin diakui secara berlebihan pada awalnya. Batas dingin adalah batas yang baru dibuat atau yang tidak memiliki lalu lintas baru-baru ini. Untuk periode awal yang singkat, gateway mungkin terlalu menerima (mengizinkan lebih banyak permintaan daripada tarif yang dikonfigurasi) sebelum penegakan konvergen. Setelah batas berada di bawah lalu lintas terus menerus, akurasi meningkat dan laju throttle yang diamati menetap mendekati laju yang dikonfigurasi.
Lalu lintas berkelanjutan memberlakukan secara akurat, tetapi semburan pendek mungkin tidak. Ledakan singkat melawan batas dingin dapat melewati tanpa dibatasi. Tingkat yang sama dikirim sebagai lalu lintas berkelanjutan diberlakukan, karena akurasi meningkat saat batas memanas. Untuk mengamati atau menunjukkan penegakan, kirim lalu lintas berkelanjutan ke batas selama beberapa menit daripada satu ledakan singkat. Misalnya, untuk batas 4 permintaan per detik, gateway mungkin tidak membatasi permintaan ke-5 di detik pertama. Jika Anda mengirim 5 permintaan per detik terus menerus, Anda akan secara konsisten melihat permintaan tambahan dibatasi setelah batas pemanasan.
Tarif yang sangat rendah kurang akurat. Tarif di bawah kira-kira 1 permintaan per detik (misalnya, batas permintaan per menit kecil) lebih sulit untuk diterapkan secara tepat dan akan menunjukkan lebih banyak variabilitas. Lebih suka tarif yang lebih tinggi di mana penegakan yang tepat penting, dan perlakukan batas yang sangat rendah sebagai perkiraan.
Batas token menyatu lebih lambat. Token-per-minute membatasi pembaruan (rekonsiliasi) total penggunaan yang dilacak hanya setelah model merespons. Permintaan yang sedang terbang selama beberapa detik atau menit hanya menahan perkiraan biayanya terhadap anggaran sampai selesai. Ini memperluas jendela di mana gateway mungkin terlalu menerima permintaan, relatif terhadap batas permintaan. Lihat FAQ batas tarif Token untuk detailnya.

Rancang batasan Anda seputar penggunaan wajar dan perlindungan backend. Ini berarti menghaluskan semburan dan melindungi target dari tetangga yang bising melalui jendela yang berkelanjutan, daripada memblokir nomor permintaan yang tepat saat ambang batas dilewati. Batas tarif bukanlah gerbang yang tepat dan tepat untuk permintaan. Batas tarif juga bukan batas keamanan, seperti yang dijelaskan di bagian berikut.

Fail-open perilaku

Gateway menggunakan semantik gagal terbuka untuk evaluasi batas laju. Tabel berikut menjelaskan perilaku ketika sistem batas kecepatan mengalami kesalahan:

Skenario	Keputusan	Alasannya
Batas waktu layanan batas tarif	Izinkan	Ketersediaan lebih diutamakan daripada penegakan hukum.
Kunci dimensi tidak dapat diselesaikan dari permintaan	Lewati (izinkan)	Batas tarif tidak berlaku untuk jenis permintaan ini.
Kegagalan penyegaran cache batas kecepatan	Coba lagi dengan data basi	Konfigurasi terakhir yang diketahui digunakan sampai cache pulih.

penting

Karena perilaku gagal membuka, jangan hanya mengandalkan batas tarif sebagai batas keamanan. Gunakan batas tarif untuk manajemen lalu lintas dan kualitas layanan, dan gunakan aturan otentikasi, otorisasi, dan WAF untuk penegakan keamanan.

Menelusuri dengan OpenTelemetry bentang

Gateway memancarkan atribut rentang OpenTelemetry (OTEL) pada rentang server untuk setiap permintaan di mana batas tarif pelanggan dievaluasi. Gunakan atribut ini untuk debugging dan pemantauan.

Atribut	Deskripsi	Contoh
`aws.agentcore.gateway.throttle.customer.decision`	Keputusan penegakan hukum atas permintaan ini.	`allowed` atau `throttled`
`aws.agentcore.gateway.throttle.customer.limit_key`	B `rateLimitId` atas tarif yang menolak permintaan. Hanya hadir ketika keputusan ada`throttled`.	`per-target-rps`
`aws.agentcore.gateway.throttle.customer.metric`	Jenis metrik yang habis. Hanya hadir ketika keputusan ada`throttled`.	`requests`
`aws.agentcore.gateway.throttle.customer.matched_entry`	Comma-separated nilai dimensi diselesaikan dari entri yang memicu throttle. Hanya hadir ketika keputusan ada`throttled`.	`my-target,alice`
`aws.agentcore.gateway.throttle.customer.evaluated`	Daftar yang diurutkan dari semua bucket batas tarif yang diperiksa untuk permintaan ini. Setiap entri menunjukkan ID batas tarif, metrik, dan nilai dimensi yang diselesaikan. Hadir untuk keduanya `allowed` dan `throttled` keputusan.	`["per-target-rps:requests:my-target", "per-caller-rpm:requests:alice"]`

A evaluated tribut ini berguna untuk memahami batas tarif mana yang diterapkan pada permintaan, bahkan ketika itu diizinkan. Setiap entri dalam daftar mengikuti format{rateLimitId}:{metric}:{resolvedDimVal1,dimVal2,…}.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Metrik-metrik

Contoh API