オペレーションメトリクスAPI

1）責任の目的と領域

• 一貫したSLI/SLO（ログイン、預金、レート、出金）；
• KRI（初期リスク指標：PSP/KYC/キュー/レプリケーション）；
• ビジネスメトリック（GEO/PSP/銀行認可の成功、成功したベットのシェア、p95/p99キーパス期間）；
• ダッシュボード、アラート、ステータスページ、レポートのための安全で安価で予測可能な読み取り。

2）建築の原則

Read-heavy、 write-low： APIはTSDB/cacheからの集計のみを読み込みます。
SLO-first：応答は時間内に予測可能です。エラーと劣化-透過的に信号されます。
コスト配慮：SDKのダウンサンプリング、クォータ、カナリア機能。
プライバシー・バイ・デザイン：メタデータ/ラベルにPIIはありません。トークン、ジオゲート、SoD。
マルチテナント：ブランド/地域/環境による分離。

3）データモデル（表面）

メトリックシリーズ='metric_id'+'ラベル{}'+'timestamp'+'value'（+optional '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'、 rawカード/ドキュメント番号。

4）バージョン管理と互換性

ベースパス：'/v1/metrics/……';互換性のない変更-新しい'vX'でのみ。
ラベル/シリーズの追加-下位互換性。
意味の変更は、応答と猶予期間の'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'

本体：1バッチで最大50リクエスト。複雑なダッシュボードのリクエストを保存します。

3。 'GET/v1/metrics/instant'

指定されたフィルタで'ts'（または'now'）の現在の値。

4。 'GET/v1/metrics/catalog'

利用可能なメトリック、説明、ラベル、許可された集計、SLOバインディングのリスト。

5。 'GET/v1/metrics/health'

API自体の状態：レイテンシp95、キャッシュの回復力、キャッシュのヒットのシェア。

6。 'GET/v1/metrics/slo'

準備ができたSLOビュー：エラー予算の消費（高速/遅い）、ターゲットのステータス。

6）サンプル要求

6.1 TR、 1-minグリッド、p95でのPSP承認の成功：

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.4 3つのクエリのバッチ（POST/bulk-query）-レイヤー付きの1つのグラフ用。

7）集計とパーセンタイル

パーセンタイルp50/p95/p99はTSDB/aggregatorレベルで計算されます。'downsample'-正しい構成（t-digest/HDR）。
'group_by'は、カーディナリティを吹き飛ばさないように、ホワイトリストラベルでのみ許可されます。
'step'が検証されます。リアルタイムでは最小10秒、パブリックダッシュボードでは1mです。

8）現金、ダウンサンプリングおよび新鮮さ

マルチレベルキャッシュ：インメモリ（最大30-60秒）、分散（最大5分）、パブリックSLOビューのCDN。
ダウンサンプリング：大きい窓（'>24h'）との自動→5m/1hポイント。
Freshness： 'X-Data-Freshness： 12'、 'X-Downsample： 1m'、 'X-Partial： true' false'。

9）複数のテナントおよび分離

各リクエストには「テナント」（トークン/ラベル）が含まれている必要があります。
ABAC/RBAC： role/policyは'tenant、 region、 environment、 metric_id'によるアクセスを制限します。
Show/charge-back： 'X-Query-Cost-Estimate'ヘッダーとusage-counters。

10）認証とセキュリティ

mTLS/スコープサービストークンをOAuth2します。
SoD：規制リスク（金融、RG）の可能性のある指標へのアクセス-個々の役割。
レート制限：クライアントキーと'metric_id'。
PII衛生：サーバーは禁止されたフィルター/ラベルがないことを検証します。

11）ジオレジデンスとコンプライアンス

データは、居住ポリシーに関する地域貯蔵庫（EU/LATAM/APAC）から読み取られます。
クロスリージョナルクエリ-PIIのない集計と'compliance_scope'の場合のみ。

12）インスタンスと相関関係

'exemplars=true'を指定すると、パーセンタイル点のレスポンスは高速RCAのための代表的な'trace_id' （PIIなし）のペアへの参照を返します。
相関：'correlation_id'はレスポンスメタデータで使用できます。

13） SLA APIとバグ

応答SLA： p95 ≤ 300 ms（キャッシュ）、≤ 1。5 s（コールドパス）、可用性≥ 99。9%.

• '400'-無効なリクエスト（'group_by'、 bad 'step'）、
• '403'-不十分な権利/テナント、
• '409'-回路競合、
• '429'-クォータ/レート制限、
• '502/504'-ストレージの劣化（ヘッダ内-ダウンサンプル/ステップの推奨事項）、
• '206'は部分的な応答である（一部のシャードは使用できない）。
• 診断ヘッダ：'X-Query-Plan'、 'X-Query-Cache'、 'X-Query-Shards'、 'X-RateLimit-Remaining'。

14）クォータ、レート制限、バックプレッシャー

デフォルト：クライアントあたり10 rps、応答あたり50エピソード、3時間ウィンドウ、'ステップ≥ 10c'。
バーストトークン：大画面、コーディネートされたウィンドウへのダッシュボード用。
Backpressure：サーバは'Retry-After'を返す可能性があり、'step'を増やす/'downsample'を有効にするようにアドバイスします。

15） SDKとベストプラクティス

SDK： Typescript/Go/Python。デフォルト：アグレッシブキャッシュ、指数関数バックオフ、'If-None-Match'。

• '/bulk-query'でクエリをグループ化する。
• 'group_by'を控えめに使う。
• 歴史的レビュー-'ダウンサンプル=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メトリックの可視性

API： p95_latency、 error_rate、 cache_hit_ratio、 partial_response_rate。
使用方法KPI： rps、平均応答量、トップコストメトリック。
アラート：エラーのバーンレート、スパイク'429'、ドロップキャッシュヒット<ターゲット。

ログ： 構造化、PIIなし；'tend'、' metric_id'、'query_cost_class'

17） FinOpsポリシー

リクエストクラス：A（リアルタイムダッシュボード）、B（運用）、C（分析）。異なるクォータ/TTL。
コスト：$/GB読み取り、$/リクエスト、$/グラフ。「重い」指標とラベルに関する月次レポート。
最適化化ーバーのマージ、一般的なSLOビューの事前集計、クライアントへの自動ヒント（推奨'ステップ/ダウンサンプル'）。

18）統合

ステータスページ：既製のSLOビューを読み込みます。
アラート：ルールは'/slo'と'instant'に依存します。
Incident-bot：短いプリセットを介したグラフ/スライスのクイックスニペット。
ワークフロー/Release-gates：赤いSLOのリリースブロック。

19）実装ロードマップ（6-10週間）

ネッド。1-2：メトリックカタログ、ラベルホワイトリスト、'/catalog'スキーマ、'/query'プロトタイプ、およびダウンサンプル。
ネッド。3-4： '/bulk-query'、'/slo'、 exemplars、 RBAC/ABAC、クォータ/レート制限。
ネッド。5-6：ジオシャーディング、パブリックビューCDN、 FinOpsの見出し、SLI APIダッシュボード。
ネッド。7-8： SDK （TS/Go/Py）、推奨/クエリリンタ、カナリアテスト。
ネッド。9-10：カオスの教え（シャード/キャッシュの失敗）、値の最適化、非推奨ポリシー。

20）アーティファクト

メトリックカタログ：id、 units、 descriptions、利用可能な'agg'、有効なラベル。
アクセスポリシー：役割、エリア、制限、SoD。
クエリースタイルガイド-正しい/間違ったクエリの例。
SLOマップ：SLIコンプライアンス↔公共の目標。
コストレポート：最高の高価なクエリ/タグ、最適化プラン。

21） KPI/KRI APIメトリック

p95/99レイテンシ、エラー率、部分的な応答。
キャッシュのヒット率とCPU/IOの節約。
平均応答サイズと$/リクエスト。
'/bulk-query'に切り替えたダッシュボードの割合。
高いカーディナリティ要求によるインシデント。

22） Antipatterns

マークの数十の無料'group_by'→カルディナリティの爆発。
クライアントの「折りたたまれた」パーセンタイル→歪み。
ダウンサンプルなしで30-90日間の要求→高価で遅い。
テナント/リージョンを許可なしに1つの応答に混在させます。
キャッシュ/CDNのない公開パネル。
'vX'と猶予期間のないメトリックのセマンティクスを変更します。

合計

オペレーション指標APIは、テレメトリー上の安定した安全で費用対効果の高い読み取りレイヤーです。標準化された回路図とパーセンタイル、キャッシュとダウンサンプリング、厳格なラベルとアクセス、RCA、透明なSLA、およびコストのSLOビューと例示です。このレイヤーを使用すると、プライバシー、予算、パフォーマンスを危険にさらすことなく、信頼性の高いダッシュボード、アラート、ステータス通信、リリースゲートを構築できます。