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和成本。这样一层可以构建可靠的行车记录仪，除尘器，状态通信和发布门，而不会对隐私，预算和性能造成风险。