API操作指標

1）指派和責任範圍

• 一致性SLI/SLO（登錄，存款，利率，提取）；
• KRI（早期風險指標：PSP/KYC/隊列/復制）；
• 業務指標（GEO/PSP/銀行授權成功，成功利率份額，關鍵路徑長度p95/p99）；
• 安全、便宜、可預測的讀數,適用於行車記錄儀、差分儀、狀態頁面、報告。

2）建築原則

Read-heavy, write-few： API僅讀取TSDB/緩存中的聚合。
SLO-first：響應按時間可預測；錯誤和退化-透明地發出信號。
Cost-aware：SDK中的downsampling，配額，金絲雀仙女。
隱私設計：元數據/標簽中沒有PII；代幣、地理門、SoD。
Multi-tenant：按品牌/地區/環境隔離。

3）數據模型（表面）

一系列='metric_id'+'labels{}+'timestamp'+'value'（+可選的'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」，原始地圖/文檔編號。

4）轉化與兼容性

基本路徑：'/v1/metrics/……'；不兼容的更改-僅在新的「vX」中。
添加標簽/系列是反向兼容的。
語義的變化-通過響應和grace時期中的「schema_version」字段。
方案目錄發布為「/v1/schemas」。

5）殘局（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`.
• 答：「{metric, labels{}，points：［ts, value］］，exemplars？}」。

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

主體：多達50個請求一個batcham。節省復雜行車記錄儀的查詢。

3. `GET /v1/metrics/instant`

給定過濾器的當前值為「ts」（或「now」）。

4. `GET /v1/metrics/catalog`

列出可用指標、說明、標簽、有效聚合、SLO綁定。

5. `GET /v1/metrics/health`

API本身的狀態：latency 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 「bet→settle」按地區分列，具有exemplars（示例）：

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

6.3 EU即時存款SLO狀態：

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

6.3個查詢中的4 Butch （POST/bulk-query）-用於具有圖層的單個圖。

7）聚集和分解

P50/p95/p99的percentili以TSDB/聚合器級別計算；「downsample」-具有正確的構圖（t-digest/HDR）。
「group_by」僅通過whitelisted標簽允許，以免炸毀基數。
「step」驗證為：realtime的最低10 s，公共dashbords的最低1 m。

8）現金，downsampling和新鮮

多級緩存：內存（最多30-60秒），分布（最多5分鐘），CDN用於公共SLO景觀。
Downsampling：在大窗口（'>24h'） → 5m/1h點處使用自動機。

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

9） Multi-tenant和隔離

每個請求都必須包含「tenant」（令牌/標簽）。
ABAC/RBAC：角色/政策限制通過'tenant, region, environment, metric_id'訪問。
Show/charge-back：標題「X-Qery-Cost-Estimate」和用戶計數器。

10）認證與安全

OAuth2 mTLS/scope限制服務令牌。
SoD：訪問可能存在監管風險（財務，RG）的指標-個別角色。
限額：通過客戶端密鑰和「metric_id」。
PII消毒：服務器驗證沒有禁止的過濾器/標簽。

11）地質居民和合規性

數據來自居民政策方面的區域倉庫（EU/LATAM/APAC）。
跨區域查詢-僅適用於沒有PII且存在「compliance_scope」的聚合。

12） 實例/Exemplars和相關性

在響應中，「exemplars=true」會返回指向一對表示性「trace_id」（沒有PII）的鏈接，用於快速RCA。
相關性：「correlation_id」在響應元數據中可用。

13） SLA API和錯誤

響應SLA： p95 ≤ 300 ms（緩存），≤ 1。5 s（冷路），可用性≥ 99。9%.

• '400'是未經驗證的要求（太多的'group_by'，壞的'step'），
• 「403」-沒有足夠的權利/tenant，
• 「409」是計劃的沖突，
• 「429」是配額/限額，
• '502/504'-storaja降解（標題-downsample/step建議），
• '206'是部分響應（某些碎片不可用）。
• 診斷標題：「X-Qery-Plan」，「X-Qery-Cache」，「X-Qery-Shards」，「X-RateLimit-Remaining」。

14）配額，限額和後壓

默認值：每個客戶端10 rps, 50系列響應,窗口3小時,「step ≥ 10 c」。
爆破令牌：對於大屏幕上的行車記錄板，匹配的窗口。
Backpressure：服務器可以返回「Retry-After」，建議增加「step」/啟用 「downsample」。

15） SDK和最佳實踐

SDK: Typescript/Go/Python.默認值：激進緩存,指數反沖,「If-None-Match」。

• 通過「/bulk-query」將查詢分組；
• 經濟地使用「grupp_by」；
• 對於歷史評論-「downsample=1h」；
• 將超時≤ 2加到「cancellation」-token。

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,平均響應量,最高成本指標。
Alerts： burn-rate按錯誤計算,「429」激增,cache-hit <target。
Logs：結構化，沒有PII；「tenant」，「metric_id」，「query_cost_class」。

17） FinOps政策

查詢類：A （realtime dashbords）、B（操作）、C（分析）。不同的配額/TTL。
費用：$/GB讀，$/查詢，$/圖。每月報告「重」指標和標簽。
優化：服務器merge,流行SLO景點的預聚合,自動客戶端提示（suggested 'step/downsample'）。

18）整合

狀態頁面：讀取完成的SLO視圖。
Alerting：規則依靠'/slo'和'instant'。
事件機器人：通過短暫的預設快速嗅探圖形/切片。
Workflow/Release-gates：紅色SLO版本塊。

19）實施路線圖（6-10周）

奈德。1-2：指標目錄，標簽的白人主義者，「/catalog」方案，帶緩存和downsample的原型「/query」。
奈德。3-4：'/bulk-query'，'/slo'，exemplars，RBAC/ABAC，配額/限制。
奈德。5-6：地理標記，用於公共景觀的CDN，FinOps標題，SLI API dashboard。
奈德。7-8：SDK（TS/Go/Py），咨詢/linter查詢，金絲雀測試。
奈德。9-10：混沌演習（shards/緩存故障），價值優化，deprekate策略。

20）文物

Metric Catalog：id，單位，可用說明「agg」，有效標簽。
訪問策略：角色，領域，限制，SoD。
Query Style Guide：查詢正確/錯誤的示例。
SLO Map：符合SLI ↔公共目標。
成本報告：最昂貴的查詢/標簽,優化計劃。

21） KPI/KRI API指標

p95/99 latency, error rate, partial responses.

Cache hit ratio和節省CPU/IO。
平均響應大小和$/查詢。
改用「/bulk-query」的行車記錄儀的比例。
由於高基數請求引起的事件。

22）反模式

數十個標簽上的免費「group_by」 →基數爆炸。
Percentili，在客戶端「折疊」→失真。
30-90天沒有下標本的請求→昂貴而緩慢。
在沒有授權的情況下將特南特/區域混合為一個響應。
沒有緩存/CDN的公共面板。
更改沒有「vX」和寬限期的度量標準的語義。

底線

API操作指標是用於遙測的穩定，安全且經濟高效的讀取層：標準化電路和筆觸，緩存和下載，嚴格的標簽和可用性，用於RCA的SLO視圖和外觀，透明的SLA和成本。這樣一層可以構建可靠的行車記錄儀，除塵器，狀態通信和發布門，而不會對隱私，預算和性能造成風險。