عملية مقياس واجهة برمجة التطبيقات

1) الغرض من المسؤولية ومجالها

• اتساق SLI/SLO (تسجيل الدخول، الإيداع، السعر، السحب) ؛
• KRI (مؤشرات المخاطر المبكرة: PSP/KYC/قوائم الانتظار/عمليات التكرار) ؛
• مقاييس الأعمال التجارية (نجاح الأذونات المصرفية لتوقعات البيئة العالمية/PSP، حصة الرهانات الناجحة، مدد المسار الرئيسية p95/p99) ؛
• قراءات آمنة ورخيصة ويمكن التنبؤ بها للوحات القيادة والتنبيه وصفحات الحالة والإبلاغ.

2) المبادئ المعمارية

ثقيل القراءة، عدد قليل من الكتابة: يقرأ API فقط التجميعات من TSDB/cache.
أولا: يمكن التنبؤ بالاستجابات في الوقت المناسب ؛ الأخطاء والتدهور - يتم الإشارة إليها بشفافية.
إدراك التكلفة: تقليل الحجم، والحصص، وميزات الكناري في SDK.
الخصوصية حسب التصميم: لا يوجد مؤشر لتكنولوجيا المعلومات في البيانات الوصفية/البطاقات التعريفية ؛ الرموز، البوابة الجغرافية، SoD.
المستأجر المتعدد: العزل حسب العلامة التجارية/المنطقة/البيئة.

3) نموذج البيانات (السطح)

متسلسلة مترية = 'metric _ id' + 'labels {} +' timestamp '+' value '(+ اختياري' نموذج {trace _ id =...} ').

3. 1 فئات

SLI/SLO: «auth _ success _ rate»، «bet _ settle _ p99 _ ms'،» سحب _ tat _ p95 _ ms'، «api _ 5xx _ rate».
KRI: «قائمة الانتظار _ المستهلك _ lag»، «db _ replication _ lag»، «psp _ soft _ dress _ rate».
Бизнес: «الودائع _ النجاح _ pct'،» الرهانات _ النجاح _ pct'، «kyc _ pass _ rate».
Инфра: "cpu _ util'،" cache _ hit _ ratio "،" cdn _ waf _ block _ rate ".

3. 2 ملصقات (محدودة بدقة)

«region»، «المستأجر»، «البيئة»، «الخدمة»، «psp»، «البنك _ المجموعة»، «geo»، «الجهاز»، «النسخة»، «المكون».
محظور: «معرف المستخدم»، «معرف الجلسة»، أرقام البطاقة الخام/المستندات.

4) الحرث والتوافق

المسار الأساسي: '/v1/المقاييس/... '; تغييرات غير متوافقة - فقط في vX الجديد.
إضافة ملصقات/سلسلة - متوافقة مع الخلف.
يتم تغيير الدلالات من خلال مجال «schema _ version» في الاستجابة وفترة السماح.
يتم نشر دليل المخطط باسم «/v1/المخططات ».

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"، "نماذج = حقيقي" false "،" حد "(рядов)،" صفحة ".
• الجواب: مجموعة من السلاسل '{metric, labels {}, points: [[ts, value]], explars?}'.

2. «POST/v1/metrics/bulk-query»

الجسم: ما يصل إلى 50 طلبًا على دفعة واحدة. يحفظ طلبات لوحات القيادة المعقدة.

3. «GET/v1/metrics/instant»

القيم الحالية في 'ts' (أو' الآن ') مع المرشحات المحددة.

4. «GET/v1/metrics/catalg»

قائمة المقاييس المتاحة، الأوصاف، الملصقات، التجميعات المسموح بها، ارتباطات SLO.

5. «احصل على/v1/مقاييس/صحة»

حالة 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 ص 99 «bet→settle» حسب المنطقة، مع نماذج (أمثلة ضئيلة):

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/bulk-query) - لرسم بياني واحد مع طبقات.

7) التجميعات والمئوية

تحسب المئوية p50/p95/p99 على مستوى المصرف/المجمع ؛ مع «عينة منخفضة» - مع التركيبة الصحيحة (t-digest/HDR).
«group _ by» مسموح به فقط على الملصقات المدرجة على القائمة البيضاء حتى لا تفجر الكاردينالية.
تم التحقق من صحة «خطوة»: 10 ثوانٍ على الأقل للوقت الحقيقي، و 1 متر للوحات القيادة العامة.

8) النقد والتقليل والنضارة

مخبأ متعدد المستويات: في الذاكرة (حتى 30-60 ثانية)، موزع (حتى 5 دقائق)، CDN لمشاهدة SLO العامة.
تصغير الحجم: تلقائي بنوافذ كبيرة (> 24 ساعة) → نقاط 5 م/1 ساعة.
Freshness - заголовки: "X-Data-Freshness: 12s"، "X-Downsample: 1m"، "X-Partial: حقيقي" false ".

9) تعدد المستأجرين والعزلة

يجب أن يحتوي كل طلب على «مستأجر» (في رمز/ملصقات).
ABAC/RBAC: يقيد الدور/السياسة وصول المستأجر والمنطقة والبيئة metric_id'.
العرض/إعادة الشحن: رؤوس وعدادات الاستخدام «X-Query-Cost-Estimate».

10) التوثيق والأمن

OAuth2 mTLS/scope service tokens.
SoD: الوصول إلى المقاييس ذات المخاطر التنظيمية المحتملة (التمويل، النمو الحقيقي) - الأدوار الفردية.
حدود الأسعار: حسب مفتاح العميل و 'metric _ id'.
التصحاح PII: يتحقق الخادم من عدم وجود مرشحات/ملصقات محظورة.

11) الإقامة الجغرافية والامتثال

تُقرأ البيانات من المخزونات الإقليمية (EU/LATAM/APAC) حول سياسة الإقامة.
الاستفسارات عبر الأقاليم - فقط بالنسبة للمجموعات التي لا تحتوي على دليل الأداء الموحد ومع «الامتثال - النطاق».

12) الحالات والارتباط

باستخدام «نماذج = صحيح»، فإن الرد عند نقاط المئوية يعيد الإشارات إلى زوج من «التعقب _ المعرف» التمثيلي (بدون PII) لـ RCA السريع.
الارتباط: 'الارتباط _ معرف' متاح في البيانات الوصفية للاستجابة.

13) SLA API والأخطاء

الرد SLA: p95 ≤ 300 mm (cache), ≤ 1. 5 s (المسار البارد)، التوافر ≥ 99. 9%.

• «400» - طلب غير صحيح (الكثير من «المجموعة»، «خطوة سيئة»)،
• «403» - حقوق/مستأجر غير كافية،
• «409» - نزاع الدائرة،
• «429» - حد الحصص/السعر،
• «502/504» - تدهور التخزين (في الرؤوس - توصيات للعينة/الخطوة)،
• «206» هي استجابة جزئية (بعض الشظايا غير متوفرة).
• العناوين التشخيصية: "X-Query-Plan" و "X-Query-Cache" و "X-Query-Shards' و" X-RateLimity-Remain ".

14) الحصص وحدود الأسعار والضغط الخلفي

الافتراضي: 10 rps لكل عميل، 50 حلقة لكل رد، نافذة 3 ساعات، «خطوة ≥ 10 ج».
رموز الانفجار: للوحات القيادة على الشاشة الكبيرة، النوافذ المنسقة.
الضغط الخلفي: قد يعيد الخادم «Retry-After»، وينصح بزيادة «الخطوة »/تمكين« عينة المرور ».

15) SDK وأفضل الممارسات

SDK: Typescript/Go/Python. الافتراضي: ذاكرة التخزين المؤقت العدوانية، التراجع الأسي، «If-None-Match».

• استفسارات جماعية «/استفسار جماعي »؛
• استخدام 'المجموعة _ بواسطة' باعتدال ؛
• وللاستعراضات التاريخية - 'العينة السفلية = ساعة واحدة' ؛
• إضافة مهلة ≤ 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) إمكانية رصد مقاييس واجهة برمجة التطبيقات

SLI самого API: p95_latency، error_rate، cache_hit_ratio، partial_response_rate.
الاستخدام KPI: rps، متوسط حجم الاستجابة، أعلى مقاييس التكلفة.
التنبيهات: معدل الحرق على الأخطاء، ارتفاع «429»، إسقاط ذاكرة التخزين المؤقت <الهدف.
جذوع الأشجار: هيكلية، بدون دليل استثمار الاستثمار ؛ "مستأجر"، "metric _ id"، "query _ cost _ class'.

17) سياسات FinOps

دروس الطلب: A (لوحات القيادة في الوقت الحقيقي)، B (التشغيل)، C (التحليلات). حصص مختلفة/TTL.
التكلفة: دولار/جيجابايت، دولار/طلب، دولار/رسم بياني. تقرير شهري عن المقاييس والملصقات «الثقيلة».
التحسينات: دمج الخادم، التجميعات المسبقة لعرض SLO الشهير، نصائح تلقائية للعميل (اقتراح «خطوة/عينة هبوط»).

18) التكامل

صفحة الحالة: يقرأ مشاهدات SLO الجاهزة.
التنبيه: تعتمد القواعد على «/سلو »و« فوري ».
روبوت الحادث: مقتطفات سريعة من الرسوم البيانية/الشرائح من خلال التجهيزات المسبقة القصيرة.
سير العمل/بوابات الإصدار: كتلة الإصدار في SLOs الحمراء.

19) خارطة طريق التنفيذ (6-10 أسابيع)

نيد. 1-2: كتالوج المقاييس، القوائم البيضاء للملصقات، مخططات «/الكتالوج »، النموذج الأولي «/الاستفسار» مع ذاكرة التخزين المؤقت، والعينة السفلية.
نيد. 3-4: '/bulk-query '، '/slo'، نماذج، RBAC/ABAC، حدود الحصص/الأسعار.
نيد. 5-6: الشحن الجغرافي، CDN للعرض العام، عناوين FinOps، لوحة تحكم SLI API.
نيد. 7-8: SDK (TS/Go/Py)، التوصيات/بطانة الاستعلام، اختبارات الكناري.
نيد. 9-10: تعاليم الفوضى (فشل القطع/المخبأ)، تحسين القيمة، استنكار السياسة.

20) القطع الأثرية

الكتالوج المتري: معرف، وحدات، أوصاف، متوفر «agg»، ملصقات صالحة.
سياسة الوصول: الأدوار والمجالات والحدود و SoD.
دليل أسلوب الاستعلام - أمثلة على الاستفسارات الصحيحة/غير الصحيحة.
خريطة SLO: امتثال SLI ↔ الأهداف العامة.
تقرير التكلفة: أعلى الاستفسارات/العلامات باهظة الثمن، خطة التحسين.

21) KPI/KRI API Metrics

p95/99 الكمون، معدل الخطأ، الردود الجزئية.
نسبة ضرب المخبأ ومدخرات وحدة المعالجة المركزية/IO.
متوسط حجم الاستجابة والدولار/الطلب.
نسبة لوحات القيادة التي تحولت إلى «الاستعلام بالجملة».
الحوادث بسبب ارتفاع طلبات الكاردينالية.

22) أنتيباترن

مجموعة حرة بعشرات العلامات → انفجار الكاردينالية.
المئوية «مطوية» على العميل → التشوهات.
الطلبات لمدة 30-90 يومًا بدون عينة هبوطية → باهظة الثمن وبطيئة.
مزج المستأجرين/المناطق في رد واحد دون إذن.
لوحات عامة بدون مخبأ/CDN.
تغيير دلالات المقاييس بدون «vX» وفترة السماح.

المجموع

إن واجهة برمجة التطبيقات لمقاييس العمليات هي طبقة قراءة مستقرة وآمنة وفعالة من حيث التكلفة على القياس عن بُعد: المخططات الموحدة والمئوية، والمخابئ والتغليف، والملصقات والوصولات الصارمة، وعرض SLO ونماذج RCA، واتفاقات SLA الشفافة، والتكلفة. تتيح لك هذه الطبقة بناء لوحات معلومات وتنبيهات واتصالات حالة وإصدار بوابات موثوقة دون المخاطرة بالخصوصية والميزانية والأداء.