mega-framework 0.1.0

package/src/lib/mega-metrics.js

@@ -0,0 +1,661 @@
+// @ts-check
+/**
+ * MegaMetrics — OpenTelemetry 메트릭 **옵트인** 통합 + Prometheus `/metrics` 노출 (ADR-131).
+ *
+ * # 무엇인가 (중학생용 설명)
+ *   트레이싱(ADR-126)이 "요청 하나가 어디를 거쳐갔나"를 **개별 추적**한다면, 메트릭은 "요청이 초당 몇 건
+ *   왔고 평균 얼마나 걸렸나"를 **숫자로 집계**한다. 운영자는 이 집계 숫자를 Prometheus 로 긁어가(scrape)
+ *   대시보드·알람을 만든다. 둘은 분리된 관심사다 — 트레이싱=분산 추적, 메트릭=집계.
+ *
+ * # 동작 한눈에 (트레이싱과 같은 옵트인 싱글톤 패턴)
+ *   1. `init(opts)` — OTel MeterProvider + PrometheusExporter(preventServerStart) 구성 + 인스트루먼트 생성.
+ *   2. 코어 배선(mega-app `onResponse`, 어댑터 hook, 세션/잡/브루트포스)이 `record*` 를 호출해 누적.
+ *   3. `/metrics` 라우트가 `collect()` 로 Prometheus 텍스트를 만들어 응답(보안 면제 — ADR-072).
+ *   4. `shutdown()` — provider 종료.
+ *   옵트인 OFF(`init` 미호출)면 모든 `record*` 가 즉시 return = **0 비용**.
+ *
+ * # 왜 OTel metrics SDK (옵션 A, ADR-131)
+ *   트레이싱이 이미 OTel(`@opentelemetry/*` 2.x)을 쓰고 docker collector 가 떠 있어,
+ *   메트릭도 같은 SDK 로 가면 (a) Prometheus 텍스트 직접 노출(`/metrics`)과 (b) OTLP collector 푸시를
+ *   둘 다 열어둘 수 있다. 신규 dep = `@opentelemetry/exporter-prometheus`(+ 트랜지티브로 이미 있던
+ *   `@opentelemetry/sdk-metrics` 직접 등재). 기존 OTel 2.7.1/0.218.0 라인과 정확히 일치(audit 신규 0).
+ *
+ * # 서빙 = 메인 포트 + 직접 직렬화 (단일 경로)
+ *   PrometheusExporter 는 기본적으로 자체 HTTP 서버(:9464)를 띄우지만, 우리는 `preventServerStart:true`
+ *   로 서버를 끄고 **MetricReader 로서만** 쓴다. `/metrics` 라우트가 `reader.collect()` → `PrometheusSerializer`
+ *   로 텍스트를 만들어 메인 포트로 응답한다(`/health` 면제 패턴 정합, ADR-072). 단위 테스트도 같은
+ *   `collect()` 를 쓰므로 prod 와 포맷이 갈라지지 않는다.
+ *
+ * # 카디널리티 관리
+ *   HTTP route 라벨은 **매칭된 라우트 패턴**(`req.routeOptions.url`, 예 `/users/:id`)만 쓴다. 매칭 안 된
+ *   요청(404)은 raw path 를 그대로 라벨에 넣으면 무한 카디널리티(공격자가 임의 경로 폭격 → 메모리 폭증)가
+ *   되므로 고정 라벨 `__unmatched__` 로 접는다. 시크릿/PII 는 라벨에 절대 안 박는다.
+ *
+ * @module lib/mega-metrics
+ * @see ADR-131 (/metrics 옵트인 + OTel metrics SDK)
+ * @see https://opentelemetry.io/docs/specs/otel/metrics/ (OTel metrics)
+ * @see https://prometheus.io/docs/instrumenting/exposition_formats/ (Prometheus 텍스트 포맷)
+ */
+import { MeterProvider } from '@opentelemetry/sdk-metrics'
+import { PrometheusExporter, PrometheusSerializer } from '@opentelemetry/exporter-prometheus'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
+} from '@opentelemetry/semantic-conventions'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/** meter 이름 (instrumentation scope) — OTel 컨벤션상 패키지명. */
+const METER_NAME = 'mega-framework'
+
+/** Prometheus 텍스트 노출 포맷 content-type (exposition format 0.0.4). */
+export const PROM_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8'
+
+/**
+ * HTTP/WS/어댑터 latency 히스토그램 버킷(**초** 단위 — Prometheus base-unit 컨벤션). 웹 요청 지연에 맞춘
+ * 표준 버킷(5ms~10s). OTel 디폴트 버킷은 ms 에 맞춰져(0,5,10,…10000) 초 단위와 안 맞으므로 명시 지정.
+ */
+const LATENCY_BUCKETS_SECONDS = Object.freeze([0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10])
+
+/**
+ * 업로드 파일 크기 히스토그램 버킷(**바이트** 단위). 1KB~100MB — 일반 웹 업로드(이미지·문서·소형 첨부)
+ * 분포에 맞춘 표준 버킷. base-unit = bytes(Prometheus `_bytes` suffix 컨벤션).
+ */
+const UPLOAD_SIZE_BUCKETS_BYTES = Object.freeze([
+  1024, 10_240, 102_400, 1_048_576, 5_242_880, 10_485_760, 52_428_800, 104_857_600,
+])
+
+/** 매칭 안 된 라우트(404 등)의 고정 라벨 — 카디널리티 폭증 차단(M-A). */
+const UNMATCHED_ROUTE = '__unmatched__'
+
+/**
+ * @typedef {object} MetricsState
+ * @property {import('@opentelemetry/sdk-metrics').MeterProvider} provider
+ * @property {PrometheusExporter} reader - MetricReader(=PrometheusExporter, preventServerStart).
+ * @property {PrometheusSerializer} serializer
+ * @property {Instruments} m - 생성된 인스트루먼트 묶음.
+ */
+
+/**
+ * @typedef {object} Instruments
+ * @property {import('@opentelemetry/api').Counter} httpRequests
+ * @property {import('@opentelemetry/api').Histogram} httpDuration
+ * @property {import('@opentelemetry/api').Counter} wsMessages
+ * @property {import('@opentelemetry/api').Histogram} wsDuration
+ * @property {import('@opentelemetry/api').Counter} adapterCalls
+ * @property {import('@opentelemetry/api').Histogram} adapterDuration
+ * @property {import('@opentelemetry/api').Counter} jobs
+ * @property {import('@opentelemetry/api').Counter} sessions
+ * @property {import('@opentelemetry/api').Counter} bruteforce
+ * @property {import('@opentelemetry/api').Counter} uploadFiles
+ * @property {import('@opentelemetry/api').Histogram} uploadBytes
+ * @property {import('@opentelemetry/api').Counter} i18n
+ * @property {import('@opentelemetry/api').Counter} templateRenders
+ * @property {import('@opentelemetry/api').Histogram} templateDuration
+ */
+
+/** @type {MetricsState | null} init 전이면 null = 비활성(모든 record* no-op). */
+let state = null
+
+/**
+ * 단일 어댑터 → onCallEnd 구독 해제 함수. shutdown 시 일괄 해제. (트레이싱과 달리 onCallStart 은 구독하지
+ * 않는다 — 메트릭은 종료 시점의 latency/err 만 필요하고, 스코프 토큰을 안 건드려 트레이싱과 무간섭.)
+ * @type {Map<import('../adapters/mega-adapter.js').MegaAdapter, () => void>}
+ */
+const subscriptions = new Map()
+
+/**
+ * 단일 잡 워커/큐 → 이벤트 구독 해제 함수(어댑터 subscriptions 와 분리 — emitter 키). shutdown/_reset 시 일괄 해제.
+ * @type {Map<import('node:events').EventEmitter, () => void>}
+ */
+const jobSubscriptions = new Map()
+
+/**
+ * 활성 여부 (Boolean — `is*`). `init` 후 `shutdown` 전이면 true.
+ * @returns {boolean}
+ */
+export function isEnabled() {
+  return state !== null
+}
+
+/**
+ * OTel 메트릭 초기화. 옵트인 — 본 함수를 부르지 않으면 모든 `record*` 가 0 비용 no-op.
+ *
+ * @param {object} opts
+ * @param {string} opts.serviceName - **필수**. `service.name` resource 속성.
+ * @param {string} [opts.version] - `service.version`.
+ * @param {string} [opts.environment] - `deployment.environment.name`.
+ * @param {Record<string, any>} [opts.attributes] - 추가 resource 속성(머지). 시크릿 금지.
+ * @returns {void}
+ * @throws {MegaConfigError} `metrics.already_initialized` / `metrics.service_name_required`.
+ */
+export function init(opts = /** @type {any} */ ({})) {
+  if (state !== null) {
+    throw new MegaConfigError(
+      'metrics.already_initialized',
+      'MegaMetrics.init() called twice — call shutdown() first to re-initialize.',
+      {},
+    )
+  }
+  const serviceName = opts.serviceName
+  if (typeof serviceName !== 'string' || serviceName.length === 0) {
+    throw new MegaConfigError(
+      'metrics.service_name_required',
+      'MegaMetrics.init({ serviceName }) is required (non-empty string).',
+      {},
+    )
+  }
+
+  const resource = resourceFromAttributes({
+    [ATTR_SERVICE_NAME]: serviceName,
+    ...(typeof opts.version === 'string' ? { [ATTR_SERVICE_VERSION]: opts.version } : {}),
+    ...(typeof opts.environment === 'string' ? { [ATTR_DEPLOYMENT_ENVIRONMENT_NAME]: opts.environment } : {}),
+    ...(opts.attributes && typeof opts.attributes === 'object' ? opts.attributes : {}),
+  })
+
+  // preventServerStart — 자체 :9464 서버를 띄우지 않고 우리가 collect() 로 직접 긁는다(메인 포트 서빙).
+  const reader = new PrometheusExporter({ preventServerStart: true })
+  const provider = new MeterProvider({ resource, readers: [reader] })
+  const meter = provider.getMeter(METER_NAME)
+  const m = buildInstruments(meter)
+  registerSystemGauges(meter)
+
+  state = { provider, reader, serializer: new PrometheusSerializer(), m }
+}
+
+/**
+ * `MEGA_METRICS_*` / `METRICS_ENABLED` 환경변수로 옵트인 초기화 (12-factor). 비활성이면 **no-op**.
+ * `/metrics` 자체는 `health.exposeMetrics` config 로 켜지지만(ADR-072), SDK 초기화는 env 로도 가능하게
+ * 트레이싱(`MegaTracing.fromEnv`)과 대칭으로 둔다. 둘 중 하나라도 켜지면 활성.
+ *
+ * 매핑:
+ *   - `METRICS_ENABLED` 또는 `MEGA_METRICS_ENABLED` (true 면 활성)
+ *   - `MEGA_METRICS_SERVICE_NAME` → serviceName (없으면 `MEGA_OTEL_SERVICE_NAME` 폴백)
+ *   - `MEGA_METRICS_VERSION` / `MEGA_METRICS_ENVIRONMENT` → resource 속성
+ *
+ * @param {Record<string, string|undefined>} [env=process.env]
+ * @returns {boolean} 활성화돼 init 했으면 true, 옵트인 OFF 면 false.
+ * @throws {MegaConfigError} 활성인데 serviceName 누락 시 `metrics.service_name_required`.
+ */
+export function fromEnv(env = process.env) {
+  const enabled = env.METRICS_ENABLED === 'true' || env.MEGA_METRICS_ENABLED === 'true'
+  if (!enabled) return false
+  /** @type {any} */
+  const opts = { serviceName: env.MEGA_METRICS_SERVICE_NAME ?? env.MEGA_OTEL_SERVICE_NAME }
+  if (env.MEGA_METRICS_VERSION) opts.version = env.MEGA_METRICS_VERSION
+  if (env.MEGA_METRICS_ENVIRONMENT) opts.environment = env.MEGA_METRICS_ENVIRONMENT
+  init(opts)
+  return true
+}
+
+/**
+ * 현재 누적된 메트릭을 Prometheus 텍스트(exposition format)로 직렬화한다. `/metrics` 라우트와 테스트가
+ * **같은 경로**로 사용한다. 옵트인 OFF 면 빈 문자열.
+ * @returns {Promise<string>}
+ */
+export async function collect() {
+  if (state === null) return ''
+  const { resourceMetrics, errors } = await state.reader.collect()
+  if (errors.length > 0) {
+    // 수집 중 일부 인스트루먼트 실패 — 묵시 무시 금지. 표면화하되, 모은 만큼은 그대로 노출(부분 실패가
+    // 전체 scrape 를 죽이지 않게). 운영자가 로그로 인지하게 한다.
+    console.warn('[MegaMetrics] collect() encountered errors (partial metrics served):', errors)
+  }
+  return state.serializer.serialize(resourceMetrics)
+}
+
+/**
+ * 트레이싱 종료 대칭 — provider 종료(+ 구독 해제). init 전이면 no-op.
+ * @returns {Promise<void>}
+ */
+export async function shutdown() {
+  for (const unsubscribe of [...subscriptions.values()]) unsubscribe()
+  subscriptions.clear()
+  for (const unsubscribe of [...jobSubscriptions.values()]) unsubscribe()
+  jobSubscriptions.clear()
+  const s = state
+  state = null
+  if (s !== null) await s.provider.shutdown()
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// 기록 API (코어 배선이 호출) — 전부 옵트인 OFF 면 즉시 return = 0 비용.
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * HTTP 요청 1건 기록 — 카운터 +1 + latency 히스토그램. mega-app `onResponse` hook 이 호출.
+ * @param {object} info
+ * @param {string} info.method - HTTP 메서드(대문자).
+ * @param {string} [info.route] - **매칭된 라우트 패턴**(`/users/:id`). 없으면 `__unmatched__`(M-A).
+ * @param {number} info.statusCode - 응답 상태코드.
+ * @param {number} info.durationMs - 처리 시간(ms).
+ * @param {string} info.app - 앱 이름.
+ * @returns {void}
+ */
+export function recordHttp({ method, route, statusCode, durationMs, app }) {
+  if (state === null) return
+  const labels = {
+    method: String(method ?? '').toUpperCase(),
+    route: route && route.length > 0 ? route : UNMATCHED_ROUTE,
+    app: app ?? '',
+  }
+  state.m.httpRequests.add(1, { ...labels, status_code: String(statusCode) })
+  state.m.httpDuration.record(toSeconds(durationMs), labels)
+}
+
+/**
+ * WebSocket 메시지 1건 기록. ws 수신 배선이 호출.
+ * @param {object} info
+ * @param {string} info.type - 메시지 타입(라우트 키처럼 bounded 한 값만 — raw payload X).
+ * @param {string} [info.ns] - 네임스페이스.
+ * @param {number} [info.durationMs] - 처리 시간(ms). 있으면 히스토그램 기록.
+ * @param {string} [info.app] - 앱 이름.
+ * @returns {void}
+ */
+export function recordWs({ type, ns, durationMs, app }) {
+  if (state === null) return
+  const labels = { type: String(type ?? ''), ns: ns ?? '', app: app ?? '' }
+  state.m.wsMessages.add(1, labels)
+  if (typeof durationMs === 'number') state.m.wsDuration.record(toSeconds(durationMs), { type: labels.type, app: labels.app })
+}
+
+/**
+ * 어댑터 호출 1건 기록 — 도메인/드라이버/콜별 카운터 + latency. 보통 `subscribe`(onCallEnd)가 호출.
+ * @param {object} info
+ * @param {string} info.domain - db|cache|bus|lock.
+ * @param {string} info.driver - 드라이버명(postgres|redis|nats|…).
+ * @param {string} info.call - 도메인 콜명(query|get|publish|acquire|…).
+ * @param {number} info.durationMs - latency(ms).
+ * @param {boolean} info.isError - 실패 여부.
+ * @returns {void}
+ */
+export function recordAdapterCall({ domain, driver, call, durationMs, isError }) {
+  if (state === null) return
+  const labels = { domain: domain ?? '', driver: driver ?? '', call: call ?? '' }
+  state.m.adapterCalls.add(1, { ...labels, status: isError ? 'error' : 'ok' })
+  state.m.adapterDuration.record(toSeconds(durationMs), labels)
+}
+
+/**
+ * 잡 큐 이벤트 1건 기록(enqueued|processed|retried|dlq). MegaJobQueue/Worker 가 호출.
+ * @param {object} info
+ * @param {string} info.queue - 큐 이름.
+ * @param {'enqueued'|'processed'|'retried'|'dlq'} info.event
+ * @returns {void}
+ */
+export function recordJob({ queue, event }) {
+  if (state === null) return
+  state.m.jobs.add(1, { queue: queue ?? '', event: String(event) })
+}
+
+/**
+ * 세션 이벤트 1건 기록(created|destroyed). 세션 미들웨어가 호출.
+ * @param {object} info
+ * @param {string} [info.driver] - file|redis.
+ * @param {'created'|'destroyed'} info.event
+ * @returns {void}
+ */
+export function recordSession({ driver, event }) {
+  if (state === null) return
+  state.m.sessions.add(1, { driver: driver ?? '', event: String(event) })
+}
+
+/**
+ * 브루트포스 이벤트 1건 기록(check|fail|lockout|reset). MegaBruteForce 가 호출.
+ * subject(이메일·IP)는 **라벨에 절대 안 넣는다** — 카디널리티 폭증 + PII. namespace 만 라벨.
+ * @param {object} info
+ * @param {string} info.namespace - 도메인 네임스페이스(login|password-reset|…).
+ * @param {'check'|'fail'|'lockout'|'reset'} info.event
+ * @returns {void}
+ */
+export function recordBruteForce({ namespace, event }) {
+  if (state === null) return
+  state.m.bruteforce.add(1, { namespace: namespace ?? '', event: String(event) })
+}
+
+/**
+ * 파일 업로드 결과 1건 기록. multipart 통합(`src/core/multipart.js`)이 호출.
+ *
+ * - 카운터 `mega_upload_files_total{app,result}` +1 — result 는 **bounded enum** 만:
+ *   `accepted`(MIME 화이트리스트 통과) / `rejected_mime`(비허용 MIME) / `saved`(디스크 저장 완료).
+ *   파일명·MIME 문자열은 라벨에 **안 넣는다** — 카디널리티 폭증·PII 방지. 크기 초과(413)·개수
+ *   초과(413)는 @fastify/multipart 가 네이티브로 throw 하므로 `mega_http_requests_total{status_code="413"}`
+ *   로 이미 관측된다(중복 집계 안 함).
+ * - `bytes` 가 주어지면 히스토그램 `mega_upload_file_bytes{app}` 에 분포 기록(저장 완료 시점).
+ *
+ * @param {object} info
+ * @param {string} [info.app] - 앱 이름.
+ * @param {'accepted'|'rejected_mime'|'saved'} info.result - 업로드 결과(bounded enum).
+ * @param {number} [info.bytes] - 파일 크기(바이트). 있으면 히스토그램 기록.
+ * @returns {void}
+ */
+export function recordUpload({ app, result, bytes }) {
+  if (state === null) return
+  state.m.uploadFiles.add(1, { app: app ?? '', result: String(result) })
+  if (typeof bytes === 'number' && bytes >= 0) state.m.uploadBytes.record(bytes, { app: app ?? '' })
+}
+
+/**
+ * i18n 이벤트 1건 집계(ADR-135). init 전이면 no-op.
+ *
+ * - `event='request'`: 요청별 결정 언어 분포(앱·언어 라벨). onRequest 1회.
+ * - `event='missing'`: 누락 키(dev saveMissing 신호 — 앱·언어·scope 라벨). 키 자체는 라벨 미노출(카디널리티).
+ *
+ * lang/scope 는 `available`·{server,client} 로 bounded 라 카디널리티 안전.
+ *
+ * @param {object} info
+ * @param {string} [info.app] - 앱 이름.
+ * @param {string} info.lang - 결정/요청 언어.
+ * @param {string} [info.scope] - namespace scope(missing 시 server|client). request 면 생략.
+ * @param {'request'|'missing'} info.event
+ * @returns {void}
+ */
+export function recordI18n({ app, lang, scope, event }) {
+  if (state === null) return
+  state.m.i18n.add(1, { app: app ?? '', lang: String(lang ?? ''), scope: scope ?? '', event: String(event) })
+}
+
+/**
+ * 템플릿 렌더 1건 기록(ADR-136). init 전이면 no-op. 템플릿 통합(`src/core/template.js`)이 호출.
+ *
+ * - 카운터 `mega_template_renders_total{app,result}` +1 — result 는 **bounded enum** 만:
+ *   `rendered`(성공) / `error`(렌더 실패 — 문법 오류·파일 없음·참조 throw). view 이름·경로는 라벨에
+ *   **안 넣는다** — 카디널리티 폭증·경로 노출 방지(upload/i18n 패턴 정합).
+ * - `durationMs` 가 주어지면 히스토그램 `mega_template_render_duration_seconds{app}` 에 분포 기록.
+ * - `bytes` 는 span 속성으로만 남기고 메트릭 라벨엔 안 쓴다(렌더 시간이 운영 신호 — 크기는 응답 메트릭과 중복).
+ *
+ * @param {object} info
+ * @param {string} [info.app] - 앱 이름.
+ * @param {'rendered'|'error'} info.result - 렌더 결과(bounded enum).
+ * @param {number} [info.durationMs] - 렌더 소요(ms). 있으면 히스토그램 기록(초 단위 변환).
+ * @param {number} [info.bytes] - 렌더 바이트(현재 메트릭 미사용 — 시그니처 호환·향후 확장용).
+ * @returns {void}
+ */
+export function recordTemplate({ app, result, durationMs }) {
+  if (state === null) return
+  state.m.templateRenders.add(1, { app: app ?? '', result: String(result) })
+  if (typeof durationMs === 'number' && durationMs >= 0) state.m.templateDuration.record(durationMs / 1000, { app: app ?? '' })
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// 어댑터 자동 수집 (onCallEnd 구독 — 트레이싱 subscribe 대칭, 단 onCallStart 미구독)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * 단일 어댑터의 `onCallEnd` 를 구독해 호출 메트릭으로 변환한다. init 전이면 no-op. 중복 구독 방지.
+ * @param {import('../adapters/mega-adapter.js').MegaAdapter} adapter
+ * @param {{ domain?: string, driver?: string, key?: string }} [meta]
+ * @returns {() => void} 구독 해제 함수.
+ */
+export function subscribe(adapter, meta = {}) {
+  if (state === null) return () => {}
+  const existing = subscriptions.get(adapter)
+  if (existing) return existing
+  const domain = meta.domain ?? ''
+  const driver = meta.driver ?? ''
+  /** @type {import('../adapters/mega-adapter.js').HookListener} */
+  const onEnd = (callName, attrs, err) => {
+    // hook 은 throw 금지(M1) — 베이스가 #safeHookEnd 로 격리하지만, 여기서도 record* 가 던지지 않게 단순 유지.
+    const latencyMs = /** @type {any} */ (attrs)?.latencyMs
+    recordAdapterCall({
+      domain,
+      driver,
+      call: callName,
+      durationMs: typeof latencyMs === 'number' ? latencyMs : 0,
+      isError: err !== undefined && err !== null,
+    })
+  }
+  const unEnd = adapter.addHookListener('onCallEnd', onEnd)
+  const unsubscribe = () => {
+    unEnd()
+    subscriptions.delete(adapter)
+  }
+  subscriptions.set(adapter, unsubscribe)
+  return unsubscribe
+}
+
+/**
+ * 부팅된 전역 어댑터 매니저의 모든 공유 어댑터에 onCallEnd 리스너를 일괄 구독한다(트레이싱 attachToManager 대칭).
+ * @param {{ entries: () => Array<{ domain: string, key: string, driver: string, adapter: import('../adapters/mega-adapter.js').MegaAdapter }> }} manager
+ * @returns {number} 구독한 어댑터 수.
+ */
+export function attachToManager(manager) {
+  if (state === null) return 0
+  let count = 0
+  for (const e of manager.entries()) {
+    subscribe(e.adapter, { domain: e.domain, driver: e.driver, key: e.key })
+    count += 1
+  }
+  return count
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// 잡 워커 자동 수집 (MegaJobWorker/MegaJobQueue 이벤트 구독 — ADR-132)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * 잡 큐 이벤트명 → `recordJob` event 라벨 매핑. 큐가 방출하는 6종(`dispatch/start/done/retry/fail/dlq`) 중
+ * **카운터로 의미 있는 4종만** 매핑한다: `start`(처리 시작)은 누적 카운터가 무의미하고, `fail`(중간 실패 —
+ * phase 로 단계 구분)은 최종 결과가 `dlq`(소진 라우팅) 또는 `done`(이후 성공)으로 귀결되므로 dlq 로 집계한다.
+ * @type {Readonly<Record<string, 'enqueued'|'processed'|'retried'|'dlq'>>}
+ */
+const JOB_EVENT_MAP = Object.freeze({
+  dispatch: 'enqueued', // enqueue(잡 발행)
+  done: 'processed', // 처리 성공 + ack
+  retry: 'retried', // 재시도 1회 실패(다음 시도 전)
+  dlq: 'dlq', // DLQ 라우팅 완료(최종 실패 소진)
+})
+
+/**
+ * 잡 워커(또는 큐)의 이벤트를 구독해 잡 메트릭(`mega_jobs_total`)으로 변환한다(어댑터 {@link subscribe} 대칭).
+ * `init` 전이면 **no-op**(0 비용 — 빈 해제 함수 반환). 같은 emitter 를 다시 구독하면 기존 해제 함수를 반환해
+ * **중복 부착을 방지**한다(어댑터 subscribe 와 동일 정책).
+ *
+ * `MegaJobWorker` 는 하부 `MegaJobQueue` 의 이벤트를 그대로 재방출(forward)하므로, **워커 1곳만 구독하면**
+ * 그 워커가 든 모든 bus 큐의 잡이 집계된다. `MegaJobQueue` 를 직접 구독해도 동일하게 동작한다(둘 다 같은
+ * 이벤트명을 방출). queue 라벨 = 이벤트 payload 의 `subject`.
+ *
+ * 리스너가 던질 일은 없지만(`recordJob` 은 카운터 add 뿐), 만에 하나 던져도 큐의 `#safeEmit`/워커 forward
+ * 가 격리하므로 잡 처리 흐름(ack/nak/DLQ)에는 영향이 없다(M-3 불변식 정합).
+ *
+ * @param {import('node:events').EventEmitter} emitter - `dispatch/done/retry/dlq` 를 방출하는 MegaJobWorker/MegaJobQueue.
+ * @returns {() => void} 구독 해제 함수.
+ */
+export function subscribeJobs(emitter) {
+  if (state === null) return () => {}
+  const existing = jobSubscriptions.get(emitter)
+  if (existing) return existing
+  /** @type {Array<[string, (payload: any) => void]>} 부착한 (이벤트명, 리스너) — 해제 시 그대로 off. */
+  const attached = []
+  for (const [queueEvent, metricEvent] of Object.entries(JOB_EVENT_MAP)) {
+    /** @param {any} payload */
+    const listener = (payload) => recordJob({ queue: payload?.subject, event: metricEvent })
+    emitter.on(queueEvent, listener)
+    attached.push([queueEvent, listener])
+  }
+  const unsubscribe = () => {
+    for (const [queueEvent, listener] of attached) emitter.off(queueEvent, listener)
+    jobSubscriptions.delete(emitter)
+  }
+  jobSubscriptions.set(emitter, unsubscribe)
+  return unsubscribe
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// 내부 — 인스트루먼트 생성 + 시스템 게이지
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * 모든 인스트루먼트를 생성한다. 이름은 `mega_` prefix + snake_case + base-unit suffix(Prometheus 컨벤션).
+ * @param {import('@opentelemetry/api').Meter} meter
+ * @returns {Instruments}
+ */
+function buildInstruments(meter) {
+  return {
+    httpRequests: meter.createCounter('mega_http_requests_total', {
+      description: 'HTTP 요청 총 건수 (method/route/status_code/app 라벨).',
+    }),
+    httpDuration: meter.createHistogram('mega_http_request_duration_seconds', {
+      description: 'HTTP 요청 처리 시간(초).',
+      unit: 's',
+      advice: { explicitBucketBoundaries: [...LATENCY_BUCKETS_SECONDS] },
+    }),
+    wsMessages: meter.createCounter('mega_ws_messages_total', {
+      description: 'WebSocket 수신 메시지 총 건수 (type/ns/app 라벨).',
+    }),
+    wsDuration: meter.createHistogram('mega_ws_message_duration_seconds', {
+      description: 'WebSocket 메시지 처리 시간(초).',
+      unit: 's',
+      advice: { explicitBucketBoundaries: [...LATENCY_BUCKETS_SECONDS] },
+    }),
+    adapterCalls: meter.createCounter('mega_adapter_calls_total', {
+      description: '어댑터 도메인 호출 총 건수 (domain/driver/call/status 라벨).',
+    }),
+    adapterDuration: meter.createHistogram('mega_adapter_call_duration_seconds', {
+      description: '어댑터 호출 latency(초).',
+      unit: 's',
+      advice: { explicitBucketBoundaries: [...LATENCY_BUCKETS_SECONDS] },
+    }),
+    jobs: meter.createCounter('mega_jobs_total', {
+      description: '잡 큐 이벤트 총 건수 (queue/event=enqueued|processed|retried|dlq 라벨).',
+    }),
+    sessions: meter.createCounter('mega_sessions_total', {
+      description: '세션 이벤트 총 건수 (driver/event=created|destroyed 라벨).',
+    }),
+    bruteforce: meter.createCounter('mega_bruteforce_events_total', {
+      description: '브루트포스 이벤트 총 건수 (namespace/event=check|fail|lockout|reset 라벨). subject 는 PII 라 미노출.',
+    }),
+    uploadFiles: meter.createCounter('mega_upload_files_total', {
+      description: '파일 업로드 결과 총 건수 (app/result=accepted|rejected_mime|saved 라벨). 파일명·MIME 은 PII/카디널리티 라 미노출.',
+    }),
+    uploadBytes: meter.createHistogram('mega_upload_file_bytes', {
+      description: '업로드 파일 크기 분포(바이트) — 디스크 저장 완료 시점(app 라벨).',
+      unit: 'By',
+      advice: { explicitBucketBoundaries: [...UPLOAD_SIZE_BUCKETS_BYTES] },
+    }),
+    i18n: meter.createCounter('mega_i18n_events_total', {
+      description: 'i18n 이벤트 총 건수 (app/lang/scope/event=request|missing 라벨). request=요청별 언어 분포, missing=누락 키(dev). lang/scope 는 bounded.',
+    }),
+    templateRenders: meter.createCounter('mega_template_renders_total', {
+      description: '템플릿 렌더 총 건수 (app/result=rendered|error 라벨). view 이름·경로는 카디널리티/경로 노출 방지로 미노출.',
+    }),
+    templateDuration: meter.createHistogram('mega_template_render_duration_seconds', {
+      description: '템플릿 렌더 소요 분포(초) — ejs-mate 렌더 1패스 기준(app 라벨).',
+      unit: 's',
+      advice: { explicitBucketBoundaries: [...LATENCY_BUCKETS_SECONDS] },
+    }),
+  }
+}
+
+/**
+ * 시스템(프로세스) 게이지를 등록한다 — scrape 시점에 콜백으로 현재값 관측(observable).
+ * 메모리/uptime/CPU 는 라벨 없거나 bounded 라 카디널리티 안전.
+ * @param {import('@opentelemetry/api').Meter} meter
+ * @returns {void}
+ */
+function registerSystemGauges(meter) {
+  const memory = meter.createObservableGauge('mega_process_memory_bytes', {
+    description: '프로세스 메모리 사용량(바이트) — kind=rss|heap_used|heap_total|external 라벨.',
+    unit: 'By',
+  })
+  memory.addCallback((result) => {
+    const mu = process.memoryUsage()
+    result.observe(mu.rss, { kind: 'rss' })
+    result.observe(mu.heapUsed, { kind: 'heap_used' })
+    result.observe(mu.heapTotal, { kind: 'heap_total' })
+    result.observe(mu.external, { kind: 'external' })
+  })
+
+  const uptime = meter.createObservableGauge('mega_process_uptime_seconds', {
+    description: '프로세스 가동 시간(초).',
+    unit: 's',
+  })
+  uptime.addCallback((result) => result.observe(process.uptime()))
+
+  const cpu = meter.createObservableCounter('mega_process_cpu_seconds_total', {
+    description: '프로세스 누적 CPU 시간(초) — type=user|system 라벨.',
+    unit: 's',
+  })
+  cpu.addCallback((result) => {
+    const cu = process.cpuUsage() // microseconds 단위 → 초로 환산.
+    result.observe(cu.user / 1e6, { type: 'user' })
+    result.observe(cu.system / 1e6, { type: 'system' })
+  })
+}
+
+/** @param {number} ms @returns {number} ms → 초(히스토그램 base-unit). */
+function toSeconds(ms) {
+  return (typeof ms === 'number' && ms >= 0 ? ms : 0) / 1000
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// /metrics IP allowList (접근 제어 — ADR-131)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * 클라이언트 IP 가 allowList 에 허용되는지 (Boolean — `is*`). `/metrics` 엔드포인트 접근 제어용(ADR-072
+ * 면제 위에 추가 인증). allowList 항목은 **정확한 IP**(IPv4/IPv6) 또는 **IPv4 CIDR**(`10.0.0.0/8`).
+ * 빈 list/미지정이면 **모두 허용**(메인 포트 노출 — 사이드카/내부망 전제, 운영자 결정).
+ *
+ * IPv6 CIDR 는 미지원(정확 매치만) — 필요 시 후속 확장. 잘못된 CIDR 항목은 매치 실패로 간주(조용히
+ * 통과시키지 않음 = fail-closed 방향).
+ *
+ * @param {string} ip - 클라이언트 IP(Fastify `req.ip`). IPv4-mapped IPv6(`::ffff:1.2.3.4`)는 IPv4 로 정규화.
+ * @param {string[]} [allowList] - 허용 IP/CIDR 목록.
+ * @returns {boolean}
+ */
+export function isIpAllowed(ip, allowList) {
+  if (!Array.isArray(allowList) || allowList.length === 0) return true // 빈 list = 전부 허용.
+  if (typeof ip !== 'string' || ip.length === 0) return false
+  const norm = ip.startsWith('::ffff:') ? ip.slice('::ffff:'.length) : ip // IPv4-mapped IPv6 정규화.
+  for (const entry of allowList) {
+    if (typeof entry !== 'string' || entry.length === 0) continue
+    if (entry === ip || entry === norm) return true // 정확 매치(IPv4/IPv6).
+    if (entry.includes('/') && isIpv4InCidr(norm, entry)) return true // IPv4 CIDR.
+  }
+  return false
+}
+
+/**
+ * IPv4 가 CIDR 범위에 드는지. CIDR/IP 가 IPv4 형식이 아니거나 prefix 가 0~32 밖이면 false(fail-closed).
+ * @param {string} ip @param {string} cidr - `a.b.c.d/n`.
+ * @returns {boolean}
+ */
+function isIpv4InCidr(ip, cidr) {
+  const [range, bitsRaw] = cidr.split('/')
+  const bits = Number(bitsRaw)
+  if (!Number.isInteger(bits) || bits < 0 || bits > 32) return false
+  const ipNum = ipv4ToInt(ip)
+  const rangeNum = ipv4ToInt(range)
+  if (ipNum === null || rangeNum === null) return false
+  if (bits === 0) return true // /0 = 모든 IPv4.
+  const mask = (0xffffffff << (32 - bits)) >>> 0
+  return (ipNum & mask) === (rangeNum & mask)
+}
+
+/** IPv4 문자열 → 32비트 정수(unsigned). 형식 위반이면 null. @param {string} ip @returns {number|null} */
+function ipv4ToInt(ip) {
+  const parts = ip.split('.')
+  if (parts.length !== 4) return null
+  let n = 0
+  for (const p of parts) {
+    if (!/^\d{1,3}$/.test(p)) return null
+    const v = Number(p)
+    if (v > 255) return null
+    n = (n << 8) | v
+  }
+  return n >>> 0
+}
+
+/**
+ * 테스트 격리용 reset — 동기 강제 정리(provider flush 없이 상태만 비움). 정상 종료는 `shutdown`.
+ * @returns {void}
+ */
+export function _reset() {
+  for (const unsubscribe of [...subscriptions.values()]) unsubscribe()
+  subscriptions.clear()
+  for (const unsubscribe of [...jobSubscriptions.values()]) unsubscribe()
+  jobSubscriptions.clear()
+  state = null
+}