작동 메트릭 API

1) 목적과 책임 영역

• 일관된 SLI/SLO (로그인, 예금, 요금, 인출);
• KRI (초기 위험 지표: PSP/KYC/대기열/복제);
• 비즈니스 메트릭 (GEO/PSP/은행 승인의 성공, 성공적인 베팅 공유, p95/p99 키 경로 지속 시간);
• 대시 보드, 경고, 상태 페이지, 보고에 대한 안전하고 저렴하며 예측 가능한 판독 값.

2) 건축 원칙

읽기 무겁고 쓰기 소수: API는 TSDB/캐시에서 집계 만 읽습니다.
SLO 우선: 응답은 제 시간에 예측할 수 있습니다. 오류 및 저하-투명하게 신호됩니다.
비용 인식: SDK의 다운 샘플링, 할당량, 카나리아 기능.
개인 정보 보호 설계: 메타 데이터/레이블에 PII 없음; 토큰, 지오 게이트, SoD.
멀티 테넌트: 브랜드/지역/환경별 격리.

3) 데이터 모델 (표면)

Metric series = 'metric _ id' + '레이블 {}' + '타임 스탬프' + '값' (+ 선택적 'exemplar {trace _ id =...}').

3. 1 개 카테고리

SLI/SLO: '자기 _ 성공 _ rate', 'bet _ settle _ p99 _ ms', 'relat _ tat _ p95 _ ms', 'api _ 5xx _ rate'.
KRI: '큐 _ 소비자 _ lag', 'db _ replication _ lag', 'psp _ soft _ deep _ rate'.
'deposits _ success _ pct', 'bets _ success _ pct', 'kyc _ pass _ rate'.
'cpu _ util', 'cash _ hit _ ratio', 'cdn _ waf _ block _ rate'.

3. 2 개의 라벨 (엄격하게 제한됨)

'지역', '테넌트', '환경', '서비스', 'psp', 'bank _ group', 'geo', '장치', '버전', '구성 요소'.
금지: 'useID', 'sessionID', 원시 카드/문서 번호.

4) 수정 및 호환성

기본 경로: '/v1/metrics/... '; 새로운 'vX' 에서만 호환되지 않는 변경 사항.
레이블/시리즈 추가-역 호환.
시맨틱 변경은 응답 및 유예 기간의 '스키마 _ 버전' 필드를 통해 이루어집니다.
스키마 디렉토리는 '/v1/skemas '로 게시됩니다.

5) 엔드 포인트 (REST, gRPC/GraphQL에서 유사)

1. 'GET/v1/metrics/query'

• 'metric' (멀티미터), ',' 에서 '로,' step '(ре차이나지도),' agg '(' avg 'sum' min 'max' p50 | p95 | p99 '),
• '필터 [라벨] = 값' (다중), '그룹 _ by = 라벨 1, 라벨 2',
• 'downsample = 1m | 5m | 1h', 'experlars = 참' 거짓 ',' 제한 '(р차원),' 페이지 '.
• 답: 시리즈 '{metric, 레이블 {}, 포인트: [ts, 값]], 예제?}' 의 배열.

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

본문: 한 배치에서 최대 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/slos'

준비된 SLO보기: 오류 예산 소비 (빠른/느린), 대상 상태.

6) 샘플 요청

6. 1 TR, 1 분 그리드, 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 → 해결" (추적 예):

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 개의 쿼리 (POST/벌크 쿼리) 4 개의 배치.

7) 집계 및 백분위 수

지각 p50/p95/p99는 TSDB/애그리 게이터 레벨에서 계산됩니다. '다운 샘플' - 올바른 조성 (t-digest/HDR).
'group _ by' 는 카디널리티를 날려 버리지 않도록 흰색 레이블에만 허용됩니다.
'단계 검증: 실시간 최소 10 초, 공개 대시 보드 1m.

8) 현금, 다운 샘플링 및 신선도

다단계 캐시: 메모리 내 (최대 30-60 초), 분산 (최대 5 분), 공개 SLO 뷰를위한 CDN입니다.
다운 샘플링: 큰 창 ('> 24h') → 5m/1h 포인트가있는 자동.

Freshness-

9) 다중 임차인 및 격리

각 요청에는 '테넌트' (토큰/라벨) 가 포함되어야합니다.
ABAC/RBAC: 역할/정책은 '테넌트, 지역, 환경, metric _ id' 에 의한 액세스를 제한합니다.
보이기/충전: 'X-Query-Cost-Estimate' 헤더 및 사용량 카운터.

10) 인증 및 보안

OAuth2 mSL/스코프 서비스 토큰.
SoD: 가능한 규제 위험 (금융, RG) -개별 역할을 가진 지표에 대한 액세스.
속도 제한: 클라이언트 키 및 'metric _ id'.
PII 위생: 서버는 금지 된 필터/라벨이 없는지 확인합니다.

11) 지리 거주 및 준수

거주 정책에 관한 지역 저장 (EU/LATAM/APAC) 에서 데이터를 읽습니다.
지역 간 쿼리-PII가없고 '준수 _ scope' 가있는 집계에 대해서만 가능합니다.

12) 인스턴스 및 상관 관계

'예제 = 참' 을 사용하면 백분위 수 포인트에서의 응답은 빠른 RCA에 대해 한 쌍의 대표 'trace _ id' (PII 제외) 에 대한 참조를 반환합니다.
상관 관계: 응답 메타 데이터에서 '상관 _ id' 를 사용할 수 있습니다.

13) SLA API 및 버그

응답 SLA: p95 λ300 ms (캐시), 할 수 있습니다. 5 초 (콜드 경로), 가용성은 99 이상입니다. 9%.

• '400' - 유효하지 않은 요청 (너무 많은 '그룹 _ by', 나쁜 '단계'),
• '403' -불충분 한 권리/세입자
• '409' -회로 충돌,
• '429' -할당량/요율 제한,
• '502/504' - 스토리지 저하 (헤더에서-다운 샘플/단계에 대한 권장 사항),
• '206' 은 부분 응답입니다 (일부 파편을 사용할 수 없음).
• 진단 헤더: 'X- 쿼리-플랜', 'X- 쿼리-캐시', 'X- 쿼리-샤즈', 'X-RateLimit-Remaining'.

14) 쿼타, 속도 제한 및 역압

기본값: 클라이언트 당 10 rps, 응답 당 50 에피소드, 3 시간 창, '단계 10c'.
버스트 토큰: 대형 화면으로의 대시 보드, 조정 된 창.
역 압력: 서버는 '재생 후' 를 반환하여 '단계 '/' 다운 샘플' 을 증가 시키라고 조언 할 수 있습니다.

15) SDK 및 모범 사례

SDK: 타입 스크립트/이동/파이썬. 기본값: 공격적인 캐시, 기하 급수적 인 백오프, 'If-None-Match'.

• '/bulk-query '에 의한 그룹 쿼리;
• 'group _ by' 를 드물게 사용하십시오.
• 역사적 리뷰- 'downsample = 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 메트릭의 관찰 가능성

(PHP 3 = 3.0.6, PHP 4)

사용 KPI: rps, 평균 응답 량, 최고 비용 지표.
경고: 오류에 대한 연소율, 스파이크 '429', 드롭 캐시 적중 <대상.
통나무: PII가없는 구조화; '테넌트', 'metric _ id', 'query _ cost _ class'.

17) FinOps 정책

요청 수업: A (실시간 대시 보드), B (운영), C (분석). 다른 할당량/TTL.
비용: $/GB 읽기, $/요청, $/그래프. "무거운" 메트릭 및 레이블에 대한 월간 보고서.
최적화: 서버 병합, 널리 사용되는 SLO 뷰를위한 사전 집계, 클라이언트에 대한 자동 팁 ('단계/다운 샘플 제안').

18) 통합

상태 페이지: 기성품 SLO 뷰를 읽습니다.
경고: 규칙은 '/slo '및' instant '에 의존합니다.
Incident-bot: 짧은 사전 설정을 통한 빠른 그래프/슬리프 스 니펫.
워크 플로/릴리스 게이트: 빨간색 SLO에서 릴리스 블록.

19) 구현 로드맵 (6-10 주)

네드. 1-2: 메트릭 카탈로그, 레이블 화이트리스트, '/카탈로그 '스키마, 캐시가있는 '/쿼리' 프로토 타입 및 다운 샘플.
네드. 3-4: '/bulk-query ', '/slo', 예제, RBAC/ABAC, 할당량/속도 제한.
네드. 5-6: 지오 샤딩, 공개보기를위한 CNC, FinOps 헤드 라인, SLI API 대시 보드.
네드. 7-8: SDK (TS/Go/Py), 권장 사항/쿼리 린터, 카나리아 테스트.
네드. 9-10: 혼돈 교육 (샤드/캐시 실패), 가치 최적화, 정책 해제.

20) 유물

메트릭 카탈로그: id, 단위, 설명, 사용 가능한 'agg', 유효한 레이블.
액세스 정책: 역할, 영역, 한계, SoD.
쿼리 스타일 가이드-올바른/잘못된 쿼리의 예.
SLO 맵: SLI 규정 준수 공개 목표.
비용 보고서: 가장 비싼 쿼리/태그, 최적화 계획.

21) KPI/KRI API 메트릭

p95/99 대기 시간, 오류율, 부분 응답.
캐시 적중 비율 및 CPU/IO 절약.
평균 응답 크기 및 $/요청.
'/bulk-query '로 전환 한 대시 보드의 비율.
높은 카디널리티 요청으로 인한 사건.

22) 안티 패턴

수십 개의 마크로 무료 'group _ by' → 카디널리티 폭발.
클라이언트 → 왜곡에서 "접힌" 백분위 수.
다운 샘플 → 비싸고 느리지 않고 30-90 일 동안 요청하십시오.
허가없이 한 번의 응답으로 세입자/지역을 혼합합니다.
캐시/CDN이없는 공개 패널.
'vX' 및 유예 기간없이 메트릭의 의미를 변경합니다.

합계

운영 지표 API는 표준화 된 회로도 및 백분위 수, 캐시 및 다운 샘플링, 엄격한 레이블 및 액세스, RCA 용 SLO 뷰 및 예제, 투명 SLA 및 비용과 같은 원격 측정에 대한 안정적이고 안전하며 비용 효율적인 판독 계층입니다. 이 계층을 통해 개인 정보 보호, 예산 및 성능의 위험없이 안정적인 대시 보드, 경고, 상태 통신 및 릴리스 게이트를 구축 할 수 있습니다.