API metric վիրահատություն

1) Նշանակումն ու պատասխանատվության գոտին

API metrick-ը պլատֆորմի վիրահատական և բիզնես մետրերի հասանելիության միավորն է։ Նա տալիս է

խորհրդատվական SLI/SLO (լոգին, դեպոզիտ, տոկոսադրույք, եզրակացություն);

KRI (ռիսկի վաղ ցուցանիշները ՝ PSA/KYC/հերթը/վերարտադրումը);

բիզնես-մետրիկները (GEO/PSA/բանկերի հեղինակային իրավունքի հաջողությունը, հաջողակ միգրանտների մասնաբաժինը, p95/p99 հիմնական ճանապարհների տևողությունը);

ապահով, էժան և կանխատեսելի ընթերցումներ dashbords, alerting, state-էջ, հաշվետվություններ։

2) Ճարտարապետական սկզբունքները

Read-heavy, write-few: API-ն միայն կարդում է միավորներ TSDB/kash-ից։

SLO-first: Պատասխանները կանխատեսելի են ժամանակի ընթացքում։ սխալներն ու դեգրադացիաները ապշեցուցիչ ազդարարվում են։

Cost-a.ru: downsampling, քվոտաներ, kanarech fics MSK-ում։

Privacy-by-design: PII-ը մետատվական/լեյբլներում; Թոկեններ, գեո գեյթ, SoD։

Multi-tenae 'բրենդի/տարածաշրջանի/շրջակա միջավայրի մեկուսացում։

3) Տվյալների մոդելը (մակերեսային)

Մետրիկ = «metric _ id» + «labels++ +» timestamp '+ «value» (+ oporational' exemplar 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`, `tenant`, `environment`, `service`, `psp`, `bank_group`, `geo`, `device`, `version`, `component`.

Արգելված է '«userId», «sessionid Id», քարտերի/փաստաթղթերի հում համարներ։

4) Տարբերակումը և համատեղելիությունը

Հիմնական ճանապարհը '«/v1/metr.ru/... »; անհամատեղելի փոփոխությունները միայն նոր «vX» -ում են։

Պիտակների ավելացումը/շարքը backward-compatible է։

Սեմանտիկայի փոփոխությունը '«schema _ version» դաշտի միջոցով պատասխանը և grace ժամանակահատվածը։

Սխեմաների կատալոգը հրապարակվում է որպես «/v1/schemas »։

5) Endpoints (REST, ինչպես gRPC/GraphQL)

1. `GET /v1/metrics/query`

Պարամետրերը

`metric` (multi), `from`, `to`, `step` (резолюция), `agg` (`avg|sum|min|max|p50|p95|p99`),

`filter[label]=value` (multi), `group_by=label1,label2`,

`downsample=1m|5m|1h`, `exemplars=true|false`, `limit` (рядов), `page`.

Պատասխանը ՝ www.d.metric, labels _ com, poin.ru: [ts, value], exemplars?>։

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

Մարմինը 'մինչև 50 հարցումը մեկ բեռ է։ Խնայում է բարդ դաշնամուրի հարցումները։

3. `GET /v1/metrics/instant`

Նշված արժեքները «ts» պահին (կամ «հիմա») նշված ֆիլտրերով։

4. `GET /v1/metrics/catalog`

Առկա մետրի, նկարագրության, պիտակների, թույլատրելի ագրեգացիաների, SLO-2019։

5. `GET /v1/metrics/health`

API-ի վիճակը 'latency p95, քեշի անկայունությունը, քեշի հիթերի մասնաբաժինը։

6. `GET /v1/metrics/slo`

SLO-ի պատրաստած 'սխալների բյուջեի սպառումը (fox/slow), նպատակների կարգավիճակները։

6) Հարցումների օրինակներ

6. 1 PBS-ի հաջողությունը 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 «bet settle» տարածաշրջաններում, exemplars (treis-օրինակներ)։

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

6. 3 Ակնթարթ SLO դեպոզիտների կարգավիճակը EU-ով

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

6. 4 Batch 3 հարցումներից (POST/bulk-query) - մեկ գրաֆիկի համար շերտերով։

7) Ագրեգացիաները և փետուրները

P50/p95/p99-ը հաշվարկվում են TSDB/ագրեգատորի մակարդակում։ «downsample» - ճիշտ կոմպոզիցիայով (t-digest/HDR)։

«group _ by» թույլատրվում է միայն chitelisted պիտակների միջոցով, որպեսզի չպայթեցնեն կարդինալությունը։

'step' validions: Առնվազն 10s realtime, 1m հանրային dashbords համար։

8) Քաշ, downsampling և թարմություն

Բազմաստիճան քեշը 'in-memory (մինչև 30-60 s), բաշխված (մինչև 5 րոպե), CDN-ը հանրային SLO-ի համար։

Downsampling: ավտոմատ մեծ պատուհանների («> www.h») 355m/1ch կետով։

Freshness-заголовки: `X-Data-Freshness: 12s`, `X-Downsample: 1m`, `X-Partial: true|false`.

9) Multi-tenant և մեկուսացում

Յուրաքանչյուր հարցում պետք է պարունակի «tenault» (թոկենում/պիտակներում)։

ABAC/RBAC 'դերը/քաղաքականությունը սահմանափակում է հասանելիությունը' tenault, region, enviance, metric _ id "։

System/charge-back: «X-Query-Cost-Estimate» և usage-հաշվիչներ։

10) Վավերացում և անվտանգություն

OAuth2 mTSA/ծառայողական հոսանքները scope սահմանափակումով։

SoD 'մետրերի հասանելիությունը հնարավոր կարգավորող ռիսկերի հետ (ֆինանսներ, RG) - առանձնահատուկ դերեր։

Rate limits: հաճախորդի և «metric _ id»։

PII-intais: սերվերը առաջնորդում է արգելված ֆիլտրերի/պիտակների բացակայությունը։

11) Գեո նստավայրը և համադրումը

Տվյալները կարդում են բնակչության քաղաքականության մասին (EU/LATAM/APAC)։

Քրոս-տարածաշրջանային հարցումները միայն ագրեգատների համար առանց PII և եթե կա «complience _ scope»։

12) Dechra/Exemplars և հարաբերակցություն

«Exemplars = www.ru» -ի դեպքում պերցենտիլների կետերում հղումները վերադառնում են մի քանի ռեպրեսենտատիվ «trace _ id» (առանց PII) արագ RCA-ի համար։

Հարաբերակցությունը '«www.relation _ id» հասանելի է մետատվական պատասխաններում։

13) SLA API և սխալներ

SLA պատասխանը ՝ p95-300 ms (kash), 361։ 5-ը (սառը ճանապարհը), հասանելիությունը 3699։ 9%.

Մոսկվան

«400» -ը ոչ որակյալ հարցում է (չափազանց շատ «group _ by», վատ «step»),

«403» -ը բավարար իրավունքներ/տենանտ չէ,

«407» - սխեմաների հակամարտություն,

«429» - քվոտա/ռեյթ լիմիտ,

«502/504» - սթորաջի քայքայումը (վերնագրերում - առաջարկություններ downsample/step),

«206» -ը մասնակի պատասխան է (շարիդների մի մասը անհասանելի է)։

Ախտորոշման վերնագրերը ՝ «X-Query-Plan», «X-Query-Cache», «X-Query-Shards», «X-Rime-Remaining»։

14) Քվոտաներ, ռեյթ լիմիտներ և backpressure

Լռելյայն '10 rps հաճախորդի վրա, 50 սերիա պատասխանը, պատուհանը 3 ժամ, «step no 10c»։

Burst-toxens 'մեծ էկրանի վրա տաշբորների համար, պատուհանները։

Backpressure: Սերվերը կարող է վերադարձնել «Retry-After», խորհուրդ տալով բարձրացնել «step »/ներառել« downsample »։

15) MSK և լավագույն պրակտիկան

SDK: Typescript/Go/Python. Լռելյայն 'ագրեսիվ քաշ, էքսպոնենցիալ backoff, «If-None-Match»։

Հաճախորդների առաջարկությունները

խմբավորեք հարցումները '«/bulk-query »;

օգտագործեք 'group _ by' տնտեսական;

պատմական կոմպոզիցիաների համար '«downsample = 1h»;

ավելացրեք taim-uta-uta-token-ը և 'cancellation' -tokens։

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: p95_latency, error_rate, cache_hit_ratio, partial_response_rate.

KPI օգտագործումը ՝ rps, միջին պատասխանը, top-metriks արժեքով։

Alerta: burn-rate սխալներով, «429», cache-hit <108։

Լոգներ ՝ կառուցվածքային, առանց PII; «tenault», «metric _ id», «query _ cost _ class»։

17) Finops քաղաքականություն

Հարցումների դասարանները ՝ A (realtime dashbords), B (վիրահատական), C (վերլուծություն)։ Տարբեր քվոտաներ/TTL։

Արժեքը ՝ դոլար/GB ընթերցանություն, դոլար/հարցում, դոլար/գրաֆիկ։ Ամսական զեկույցը «ծանր» մետրերի և պիտակների մասին։

Օպտիմիզացիա 'սերվերային merge, նախադրյալներ հայտնի SLO-vew-ի համար, հաճախորդի ավտո խորհուրդ (suggested' step/downsample ")։

18) Մոսկվան

Կարգավիճակ-էջ 'կարդում է SLO-ի պատրաստի։

Alerting: կանոնները ապավինում են '/slo 'և' instrone>։

Պատահարը 'կարճ ճնշումների միջոցով գրաֆիկների/կտրվածքների արագ հավաքումը։

Workflow/Releam-gates: ածխաջրածինների բլոկը կարմիր SLO-ում։

19) Ճանապարհի քարտեզը (6-10 շաբաթ)

Մոսկվան։ 1-2 'մետրի կատալոգը, whitelisions պիտակները, սխեմաները '/catalog ", նախատիպը '/query' s և downsample։

Մոսկվան։ 3-4 : /bulk-query ", "/slo", exemplars, RBAC/ABAC, քվոտաներ/ռեյթ-լիմիտներ։

Մոսկվան։ 5-6 'գեո-շարդինգը, CDN հանրային վիզայի համար, FinOps-վերնագրերը, SLI API-ի դաշնամուրը։

Մոսկվան։ 7-8: MSK (TS/Go/Py), առաջարկություններ/հարցումների լինտեր, կանարական թեստեր։

Մոսկվան։ 9-10 'քաոս ուսուցումները (Շարդի/քեշի հրաժարվելը), արժեքի օպտիմիզացումը, ավանդների քաղաքականությունը։

20) Արտեֆակտները

Metric Catalog: id, միավորներ, նկարագրություններ, որոնք հասանելի են «agg», թույլատրելի պիտակներ։

DirectPolicy 'դերեր, տարածքներ, լիմիտներ, SoD։

Query Style Guide 'ճիշտ/սխալ հարցումների օրինակներ։

SLO Map: SLI-ի համապատասխանությունը հանրային նպատակներին։

Cost Report: Լավագույն թանկ հարցումները/պիտակները, օպտիմիզացման պլանը։

21) KPI/KRI API մետրիկ

p95/99 latency, error rate, partial responses.

Cache hit ratio և CPU/IO խնայողությունները։

Պատասխանների միջին չափը և դոլարը/հարցումը։

Dashbords-ի մասնաբաժինը, որը անցավ «/bulk-query »-ին։

Միջադեպերը բարձր կարդինալության հարցումների պատճառով։

22) Անտիպատերնի

Ազատ «group _ by» -ը տասնյակ պիտակների վրա բացատրում է կարդինալիզմի պայթյունը։

Նրանք գրեցին, «բարդ» կլիենտի վրա։

Հարցումները 30-90 օրվա ընթացքում առանց downsample-ի հայտարարվում են թանկ և դանդաղ։

Թենանտների/տարածաշրջանների խառնուրդը մեկ պատասխանով առանց հեղինակային իրավունքի։

Հանրային վահանակներ առանց քեշի/CDN։

Սեմանտիկայի փոփոխությունը առանց «vX» և grace ժամանակահատվածի։

Արդյունքը

API-ի գործողությունների մեթրիկը կայուն, անվտանգ և տնտեսական ընթերցանության շերտն է հեռուստացույցի վրա 'ստանդարտ սխեմաներ և գրգռված, քեշ և downsampling, խիստ պիտակներ և հասանելի, SLO-vu և exemplars RCA-ի համար, թափանցիկ SLA-ի և արժեքի համար։ Այս շերտը թույլ է տալիս կառուցել հուսալի տաշբորդեր, ալերտինգ, հաղորդակցման կարգավիճակ և օրինագծերի խաղացողներ առանց գաղտնիության, բյուջեի և արտադրողականության ռիսկի։