معیارهای عملیاتی API

1) هدف و حوزه مسئولیت

• SLI/SLO سازگار (ورود، واریز، نرخ، برداشت) ؛
• KRI (شاخص های خطر اولیه: PSP/KYC/صف/تکرار) ؛
• معیارهای کسب و کار (موفقیت مجوزهای GEO/PSP/بانکی، سهم شرط های موفق، مدت زمان مسیر کلیدی p95/p99) ؛
• خواندن امن، ارزان و قابل پیش بینی برای داشبورد، هشدار، صفحات وضعیت، گزارش.

2) اصول معماری

Read-heavy, write-few: API فقط aggregations را از TSDB/cache میخواند.
SLO-اول: پاسخ ها در زمان قابل پیش بینی هستند ؛ خطاها و تنزل - به طور شفاف نشان داده شده است.
هزینه آگاه: downsampling، سهمیه، ویژگی های قناری در SDK.
حریم خصوصی توسط طراحی: هیچ PII در ابرداده/برچسب ؛ نشانه ها، دروازه جغرافیایی، SoD.
چند مستاجر: جداسازی با نام تجاری/منطقه/محیط زیست.

3) مدل داده (سطح)

سری متریک = 'metric _ id' + 'labels {}' + 'timestamp' + 'value' (+ اختیاری 'examplar {trace _ id =...}').

3. 1 دسته بندی ها

SLI/SLO: 'auth _ success _ rate', 'bet _ settle _ p99 _ ms', 'withdraw _ tat _ p95 _ ms', 'api _ 5xx _ rate'.
KRI: 'queue _ consumer _ lag', 'db _ replication _ lag', 'psp _ soft _ decline _ rate'.
Бизнес: 'deposits _ success _ pct', 'bets _ success _ pct', 'kyc _ pass _ rate'.
Инфра: 'cpu _ util', 'cache _ hit _ ratio', 'cdn _ waf _ block _ rate'.

3. 2 برچسب ها (به شدت محدود)

«region»، «مستاجر»، «محیط زیست»، «سرویس»، «psp»، «بانک _ گروه»، «جغرافیایی»، «دستگاه»، «نسخه»، «جزء».
ممنوع: «شناسه کاربر»، «شناسه جلسه»، شماره کارت/سند خام.

4) نسخه و سازگاری

مسیر پایه: '/v1/metrics/... '; تغییرات ناسازگار - فقط در vX جدید.
اضافه کردن برچسب/سری - عقب سازگار است.
تغییر معانی از طریق فیلد «schema _ version» در پاسخ و دوره فضل است.
دایرکتوری schema به صورت «/v1/schemas »منتشر می شود.

5) نقاط پایانی (REST، مشابه در gRPC/GraphQL)

1. 'GET/v1/metrics/query'

• 'metric' (چند)، 'از'، 'به'، 'گام' (резолюция)، 'agg' ('avg' sum 'min' max 'p50 | p95 | p99')،
• 'filter [label] = value' (multi), 'group _ by = label1, label2',
• 'downsample = 1m | 5m | 1h', 'examplars = true' false ',' limit '(рядов),' page '.
• پاسخ: آرایه ای از سری '{metric, labels {}, points: [[ts, value]], examplars?}.

2. 'POST/v1/metrics/bulk-query'

بدن: تا 50 درخواست در یک دسته. درخواستها را برای داشبوردهای پیچیده ذخیره میکند.

3. 'GET/v1/metrics/instant'

مقادیر جاری در «t» (یا «اکنون») با فیلترهای مشخص شده.

4. 'GET/v1/متریک/کاتالوگ'

لیست معیارهای موجود، توضیحات، برچسب ها، جمع آوری های مجاز، اتصالات SLO.

5. 'GET/v1/metrics/health'

حالت از API خود: P95 تاخیر, انعطاف پذیری حافظه پنهان, سهم از بازدید کش.

6. 'GET/v1/metrics/slo'

نماهای SLO آماده: مصرف بودجه خطا (سریع/آهسته)، وضعیت هدف.

6) درخواست نمونه

6. 1 موفقیت مجوز PSP در TR، 1 دقیقه شبکه، p95:

GET /v1/metrics/query? metric=auth_success_rate&from=2025-11-01T13:00:00Z&to=2025-11-01T16:00:00Z&step=1m&agg=p95&filter[geo]=TR&group_by=psp&downsample=1m

6. 2 p99 «شرط → حل و فصل» بر اساس منطقه، با نمونه (نمونه ردیابی):

GET /v1/metrics/query? metric=bet_settle_p99_ms&from=...&to=...&step=5m&group_by=region&exemplars=true

6. 3 وضعیت اتحادیه اروپا سپرده لحظه SLO:

GET /v1/metrics/slo? domain=payments&region=EU&tenant=brandA

6. 4 دسته ای از 3 نمایش داده شد (POST/فله پرس و جو) - برای یک نمودار با لایه.

7) جمع و درصد

درصد p50/p95/p99 در سطح TSDB/aggregator محاسبه می شود ؛ با «downsample» - با ترکیب صحیح (t-digest/HDR).
گروه بندی فقط روی برچسبهای سفید مجاز است تا کارت اعتباری را منفجر نکند.
'step' معتبر است: حداقل 10 ثانیه برای زمان واقعی، 1 متر برای داشبورد عمومی.

8) پول نقد، downsampling و طراوت

حافظه پنهان چند سطحی: در حافظه (تا 30-60 ثانیه)، توزیع شده (تا 5 دقیقه)، CDN برای نمایش SLO عمومی.
Downsampling: اتوماتیک با پنجره های بزرگ (> 24h) → نقاط 5m/1h.
تازه - заголовки: "X-Data-Freshness: 12s"، "X-Downsample: 1m"، "X-Partial: true" false ".

9) چند مستاجر و انزوا

هر درخواست باید شامل 'tenant' (در نشانه/برچسب) باشد.
ABAC/RBAC: نقش/سیاست محدود کردن دسترسی توسط tenant، منطقه، محیط زیست، metric_id'.
نمایش/بازپرداخت: هدر ها و شمارنده های استفاده از «X-Query-Cost-Estimate».

10) احراز هویت و امنیت

OAuth2 mTLS/نشانه خدمات دامنه.
SoD: دسترسی به معیارهای با خطرات نظارتی ممکن (مالی، RG) - نقش های فردی.
محدودیت نرخ: توسط کلید مشتری و 'metric _ id'.
بهداشت PII: سرور عدم وجود فیلترها/برچسب های ممنوع را تأیید می کند.

11) جغرافیایی اقامت و انطباق

داده ها از ذخایر منطقه ای (EU/LATAM/APAC) در مورد سیاست اقامت خوانده می شود.
پرس و جوهای بین منطقه ای - فقط برای aggregates بدون PII و با «compliance _ scope».

12) نمونه ها و همبستگی

با 'exemplars = true'، پاسخ در نقاط صدک به یک جفت نماینده 'trace _ id' (بدون PII) برای RCA سریع ارجاع می دهد.
همبستگی: 'correlation _ id' در فراداده پاسخ موجود است.

13) API SLA و اشکالات

SLA پاسخ: p95 ≤ 300 ms (کش)، ≤ 1. 5 ثانیه (مسیر سرد)، در دسترس بودن ≥ 99. 9%.

• «400» - درخواست نامعتبر (بیش از حد «group _ by»، «مرحله» بد)،
• '403' - حقوق کافی/مستاجر،
• '409' - درگیری مدار،
• «429» - محدودیت سهمیه/نرخ،
• «502/504» - تخریب ذخیره سازی (در هدر - توصیه هایی برای downsample/step)،
• '206' یک پاسخ جزئی است (برخی از شاردها در دسترس نیستند).
• هدرهای تشخیصی: 'X-Query-Plan'، 'X-Query-Cache'، 'X-Query-Shards'، 'X-RateLimit-Remaining'.

14) سهمیه ها، محدودیت های نرخ و فشار پشتی

پیش فرض: 10 دور در هر مشتری، 50 قسمت در هر پاسخ، پنجره 3 ساعته، «مرحله ≥ 10c».
نشانه های پشت سر هم: برای داشبورد به صفحه نمایش بزرگ، پنجره های هماهنگ.
Backpressure: سرور ممکن است «Retry-After» را بازگرداند، توصیه به افزایش «step »/enable« downsample ».

15) SDK و بهترین شیوه ها

SDK: تایپ اسکریپت/برو/پایتون. پیش فرض: کش تهاجمی، عقب نشینی نمایشی، 'If-None-Match'.

• نمایش داده شد گروه توسط '/bulk-query '؛
• استفاده از «گروه» با صرفه جویی ؛
• برای بررسیهای تاریخی - «downsample = 1h»;
• اضافه کردن وقفه ≤ 2 ثانیه و 'لغو' نشانه.

15. 1 نمونه کوچک (TS)

ts const res = await client. query({
metric: ["auth_success_rate"],
from: "-3h", to: "now", step: "1m",
agg: "p95",
filter: { geo: "TR", tenant: "brandA" },
group_by: ["psp"],
downsample: "1m",
exemplars: true,
timeoutMs: 1800
});

16) مشاهده معیارهای API

SLI API: ، ،.
KPI استفاده: rps، متوسط حجم پاسخ، معیارهای هزینه بالا.
هشدارها: نرخ سوزاندن خطاها، اسپایک '429'، افت کش ضربه <هدف.
سیاهههای مربوط: ساختار، بدون PII ؛ 'tenant'، 'metric _ id'، 'query _ cost _ class'.

17) سیاست های FinOps

کلاس های درخواست: A (داشبورد زمان واقعی)، B (عملیاتی)، C (تجزیه و تحلیل). سهمیه های مختلف/TTL.
هزینه: $/GB خوانده شده، $/درخواست، $/نمودار. گزارش ماهانه در مورد معیارها و برچسب های «سنگین».
بهینه سازی: ادغام سرور، قبل از aggregates برای محبوب SLO مشاهده، راهنمایی خودکار به مشتری (پیشنهاد 'step/downsample').

18) ادغام

صفحه وضعیت: نماهای آماده SLO را می خواند.
هشدار: قوانین به «/slo »و« فوری »تکیه می کنند.
Incident-bot: قطعه های سریع نمودار/برش از طریق ایستگاه از پیش تنظیم کوتاه.
گردش کار/دروازه های انتشار: بلوک انتشار در SLO های قرمز.

19) نقشه راه پیاده سازی (6-10 هفته)

«ند». 1-2: کاتالوگ متریک، لیست های سفید برچسب، طرح های «/کاتالوگ »، نمونه اولیه/پرس و جو با حافظه پنهان و downsample.
«ند». 3-4: '/bulk-query ', '/slo', examplars, RBAC/ABAC, quota/rate limits.
«ند». 5-6: جغرافیایی، CDN برای نمایش عمومی، سرفصل های FinOps، داشبورد SLI API.
«ند». 7-8: SDK (TS/Go/Py)، recommendations/query linter، canary tests.
«ند». ۹-۱۰: آموزههای آشوب (شکست shard/cache)، بهینهسازی ارزش، سیاست مستهلک کردن.

20) مصنوعات

کاتالوگ متریک: شناسه، واحدها، توضیحات، موجود 'agg'، برچسب های معتبر.
سیاست دسترسی: نقش ها، مناطق، محدودیت ها، SoD.
Query Style Guide - نمونه هایی از پرس و جوهای صحیح/نادرست.
نقشه SLO: انطباق SLI ↔ اهداف عمومی.
گزارش هزینه: نمایش داده شد گران بالا/برچسب ها، طرح بهینه سازی.

21) معیارهای KPI/KRI API

تأخیر p95/99، میزان خطا، پاسخهای جزئی.
نسبت ضربه کش و صرفه جویی در CPU/IO.
میانگین اندازه پاسخ و $/درخواست.
نسبت داشبوردهایی که به «/bulk-query »تغییر کردهاند.
حوادث به دلیل درخواست های کاردینالیتی بالا.

22) ضد گلوله

Free 'group _ by' by دهها مارک → انفجار کاردینالیتی.
صدک «خورده» در مشتری → اعوجاج.
درخواست برای 30-90 روز بدون downsample → گران و آهسته است.
مخلوط کردن مستاجران/مناطق در یک پاسخ بدون مجوز.
پانل های عمومی بدون حافظه پنهان/CDN.
تغییر معانی معیارها بدون «vX» و دوره گریس.

مجموع

معیارهای عملیات API یک لایه خواندن پایدار، امن و مقرون به صرفه بیش از تله متری است: طرح های استاندارد و درصد، حافظه پنهان و downsampling، برچسب ها و دسترسی های دقیق، نمای SLO و نمونه هایی برای RCA، SLA های شفاف و هزینه. این لایه به شما امکان می دهد داشبورد های قابل اعتماد، هشدارها، ارتباطات وضعیت و دروازه های انتشار را بدون ریسک حریم خصوصی، بودجه و عملکرد ایجاد کنید.