mega-framework 0.1.0

package/src/lib/mega-tracing.js

@@ -0,0 +1,715 @@
+// @ts-check
+/**
+ * MegaTracing — OpenTelemetry 분산 트레이싱 **옵트인** 통합 (ADR-114).
+ *
+ * ADR-077 의 어댑터 관찰성 hook(`onCallStart`/`onCallEnd`) 위에 **자동 span** 을 얹는다. 코어·어댑터
+ * 코드는 한 줄도 바꾸지 않는다 — `MegaAdapter.addHookListener`로 외부에서 hook 발화를
+ * 구독해 span 으로 변환할 뿐이다. 옵트인 OFF(`init` 미호출)면 어댑터에 리스너가 안 붙어 **0 비용**.
+ *
+ * # 동작 한눈에
+ *   1. `init(opts)` — OTel TracerProvider/exporter/sampler 구성 + tracer 확보.
+ *   2. `attachToManager(MegaAdapterManager)` — 부팅된 모든 공유 어댑터에 hook 리스너 일괄 구독.
+ *      (또는 `subscribe(adapter, meta)` 로 개별 어댑터 구독.)
+ *   3. 어댑터 도메인 호출(`query`/`get`/`acquire` …)마다 `onCallStart`→span 시작, `onCallEnd`→span 종료.
+ *   4. `shutdown()` — 리스너 해제 + span flush + provider 종료.
+ *
+ * # span 중첩(부모-자식) 추적 — 베이스 `_instrument` 의 `run()` seam (ADR-077 보강)
+ *   `onCallStart` 이 **스코프 토큰**(여기선 OTel span context)을 반환하면, 베이스 `_instrument` 가
+ *   도메인 `fn` 을 `MegaAdapter.#callScope.run(token, fn)` 안에서 실행한다. 그래서 `fn` 내부의 중첩
+ *   호출은 `adapter._currentCallScope` 로 부모 토큰을 읽어 자기 span 의 부모로 삼는다. `run()` 은
+ *   각 호출을 독립 스코프로 격리하므로 **순차·중첩·동시(`Promise.all`) 전부 정확**하다 — 과거
+ *   `enterWith` 방식이 공유 동기 실행을 오염시켜 sibling 을 잘못 묶던 문제(스모크로 확인)를 구조적으로
+ *   제거한다. 이 seam 은 ADR-077 의 `_instrument` 에 추가된 **단 한 줄(run 위임)** 이다(ADR-114, 오너 결정).
+ *
+ * # 신규 의존성 (ADR-114 + ADR-126 보강)
+ *   `@opentelemetry/api`, `@opentelemetry/sdk-trace-base`, `@opentelemetry/resources`,
+ *   `@opentelemetry/semantic-conventions`, `@opentelemetry/exporter-trace-otlp-http`(OTLP exporter),
+ *   `@opentelemetry/exporter-zipkin`(Zipkin exporter, ADR-126 보강 — 사용자 승인). audit 신규 0건.
+ *
+ * @module lib/mega-tracing
+ */
+import { trace, ROOT_CONTEXT, SpanKind, SpanStatusCode } from '@opentelemetry/api'
+import {
+  BasicTracerProvider,
+  SimpleSpanProcessor,
+  BatchSpanProcessor,
+  ConsoleSpanExporter,
+  InMemorySpanExporter,
+  AlwaysOnSampler,
+  AlwaysOffSampler,
+  TraceIdRatioBasedSampler,
+  ParentBasedSampler,
+} from '@opentelemetry/sdk-trace-base'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import {
+  ATTR_SERVICE_NAME,
+  ATTR_SERVICE_VERSION,
+  ATTR_DB_SYSTEM_NAME,
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DEPLOYMENT_ENVIRONMENT_NAME,
+} from '@opentelemetry/semantic-conventions'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { ZipkinExporter } from '@opentelemetry/exporter-zipkin'
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { MegaConfigError } from '../errors/config-error.js'
+
+/** tracer 이름 (instrumentation scope) — OTel 컨벤션상 패키지명 사용. */
+const TRACER_NAME = 'mega-framework'
+
+// 배선 코드(mega-app/ws-upgrade)가 @opentelemetry/api 를 직접 import 하지 않고 span kind 를 지정할 수
+// 있게 re-export 한다(SERVER=HTTP/WS 수신, CLIENT=어댑터 호출, INTERNAL=사용자 span 기본).
+export { SpanKind } from '@opentelemetry/api'
+
+/**
+ * **요청 단위 active OTel Context** 저장소 (ADR-126).
+ *
+ * HTTP/WS 루트 span 과 `ctx.tracer.span` 이 "지금 열려 있는 span" 을 비동기 흐름 전반에 전파하는 데 쓴다.
+ * 어댑터 자동 span(ADR-114)이 쓰는 per-adapter `MegaAdapter.#callScope` 와 **별개의 ALS** 다 — 어댑터
+ * 스코프가 없을 때(핸들러 최상위의 어댑터 호출 등) `handleStart` 가 이 저장소를 부모로 폴백해, 어댑터 span
+ * 이 HTTP/WS 루트 span 의 자식으로 정확히 중첩된다. `context-async-hooks` 패키지(신규 dep)를 도입하지
+ * 않고 우리 ALS 로 같은 효과를 낸다(ADR-114 의 "context manager 없이" 방침과 정합).
+ * @type {AsyncLocalStorage<import('@opentelemetry/api').Context>}
+ */
+const activeContextStore = new AsyncLocalStorage()
+
+/**
+ * 현재 활성 OTel Context — ALS 에 없으면 ROOT_CONTEXT(span 없음).
+ * @returns {import('@opentelemetry/api').Context}
+ */
+function getActiveContext() {
+  return activeContextStore.getStore() ?? ROOT_CONTEXT
+}
+
+/**
+ * 비활성(옵트인 OFF) 시 사용자 코드에 넘길 **no-op span** — 메서드는 다 있지만 아무것도 기록 안 함.
+ * `ctx.tracer.span(name, (span) => span.setAttribute(...))` 가 OFF 에서도 깨지지 않게 한다.
+ * @type {any}
+ */
+const NOOP_SPAN = Object.freeze({
+  setAttribute: () => NOOP_SPAN,
+  setAttributes: () => NOOP_SPAN,
+  addEvent: () => NOOP_SPAN,
+  addLink: () => NOOP_SPAN,
+  addLinks: () => NOOP_SPAN,
+  recordException: () => {},
+  setStatus: () => NOOP_SPAN,
+  updateName: () => NOOP_SPAN,
+  end: () => {},
+  isRecording: () => false,
+  spanContext: () => ({ traceId: '', spanId: '', traceFlags: 0 }),
+})
+
+/** 비활성 시 `enterSpan` 이 돌려주는 no-op 핸들. */
+const NOOP_HANDLE = Object.freeze({ span: NOOP_SPAN, end: () => {} })
+
+/** 비활성 시 `enterHttpSpan` 이 돌려주는 no-op 핸들. */
+const NOOP_HTTP_HANDLE = Object.freeze({ span: NOOP_SPAN, setError: () => {}, finish: () => {} })
+
+/**
+ * @typedef {object} TracingState
+ * @property {import('@opentelemetry/sdk-trace-base').BasicTracerProvider} provider
+ * @property {import('@opentelemetry/api').Tracer} tracer
+ * @property {import('@opentelemetry/sdk-trace-base').SpanExporter} exporter
+ */
+
+/** @type {TracingState | null} init 전이면 null = 비활성(no-op). */
+let state = null
+
+/**
+ * 어댑터 → 구독 해제 함수. shutdown 시 일괄 해제. init/shutdown 사이클을 넘어 살아남는 모듈 싱글톤.
+ * @type {Map<import('../adapters/mega-adapter.js').MegaAdapter, () => void>}
+ */
+const subscriptions = new Map()
+
+/**
+ * 활성 여부 (Boolean — `is*`, ADR-036). `init` 후 `shutdown` 전이면 true.
+ * @returns {boolean}
+ */
+export function isEnabled() {
+  return state !== null
+}
+
+/**
+ * OTel 트레이싱 초기화. 옵트인 — 본 함수를 부르지 않으면 어떤 어댑터에도 리스너가 안 붙어 0 비용.
+ *
+ * @param {object} opts
+ * @param {string} opts.serviceName - **필수**. `service.name` resource 속성.
+ * @param {string} [opts.endpoint] - OTLP HTTP traces endpoint (예: `http://localhost:4318/v1/traces`).
+ *   지정 + `exporter` 미지정 시 자동으로 `'otlp'` exporter 선택.
+ * @param {'always_on'|'always_off'|`traceidratio:${number}`|number} [opts.sampling='always_on'] -
+ *   샘플러. 비율은 `'traceidratio:0.1'` 또는 숫자 `0.1`(0~1). 비율 샘플러는 `ParentBased` 로 감싼다.
+ * @param {'console'|'otlp'|'zipkin'|'inmemory'|import('@opentelemetry/sdk-trace-base').SpanExporter} [opts.exporter] -
+ *   exporter 종류 문자열 또는 인스턴스 직접 주입(테스트는 `InMemorySpanExporter` 인스턴스). 미지정 시
+ *   `endpoint` 있으면 `'otlp'`, 없으면 `'console'`. `'zipkin'` 은 Zipkin v2 JSON(ADR-126 보강).
+ * @param {'simple'|'batch'} [opts.processor] - span processor. 미지정 시 otlp=`'batch'`, 그 외=`'simple'`.
+ * @param {string} [opts.version] - `service.version` resource 속성.
+ * @param {string} [opts.environment] - `deployment.environment.name` resource 속성.
+ * @param {Record<string, any>} [opts.attributes] - 추가 resource 속성(머지). 시크릿 금지.
+ * @returns {void}
+ * @throws {MegaConfigError} `tracing.already_initialized` / `tracing.service_name_required` / `tracing.invalid_sampling` / `tracing.invalid_exporter`.
+ */
+export function init(opts = /** @type {any} */ ({})) {
+  if (state !== null) {
+    throw new MegaConfigError(
+      'tracing.already_initialized',
+      'MegaTracing.init() called twice — call shutdown() first to re-initialize.',
+      {},
+    )
+  }
+  const serviceName = opts.serviceName
+  if (typeof serviceName !== 'string' || serviceName.length === 0) {
+    throw new MegaConfigError(
+      'tracing.service_name_required',
+      'MegaTracing.init({ serviceName }) is required (non-empty string).',
+      {},
+    )
+  }
+
+  const sampler = buildSampler(opts.sampling)
+  const { exporter, processorKind } = buildExporter(opts)
+  const SpanProcessor = processorKind === 'batch' ? BatchSpanProcessor : SimpleSpanProcessor
+
+  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 : {}),
+  })
+
+  const provider = new BasicTracerProvider({
+    resource,
+    sampler,
+    spanProcessors: [new SpanProcessor(exporter)],
+  })
+
+  state = {
+    provider,
+    tracer: provider.getTracer(TRACER_NAME),
+    exporter,
+  }
+}
+
+/**
+ * `MEGA_OTEL_*` 환경변수로 옵트인 초기화 (12-factor). `MEGA_OTEL_ENABLED!=='true'` 면 **no-op**
+ * (init 미호출 → 0 비용). 활성 시 `MEGA_OTEL_SERVICE_NAME` 필수.
+ *
+ * 매핑:
+ *   - `MEGA_OTEL_ENABLED` (true|false, 디폴트 false)
+ *   - `MEGA_OTEL_SERVICE_NAME` → serviceName (필수)
+ *   - `MEGA_OTEL_ENDPOINT` → endpoint (OTLP)
+ *   - `MEGA_OTEL_SAMPLING_RATIO` → sampling (숫자 비율; `always_on`/`always_off` 문자열도 허용)
+ *   - `MEGA_OTEL_EXPORTER` → exporter (otlp|console|inmemory)
+ *   - `MEGA_OTEL_VERSION` / `MEGA_OTEL_ENVIRONMENT` → resource 속성
+ *
+ * @param {Record<string, string|undefined>} [env=process.env]
+ * @returns {boolean} 활성화돼 init 했으면 true, 옵트인 OFF 면 false.
+ * @throws {MegaConfigError} 활성인데 serviceName 누락 시 `tracing.service_name_required`.
+ */
+export function fromEnv(env = process.env) {
+  if (env.MEGA_OTEL_ENABLED !== 'true') return false
+  /** @type {any} */
+  const opts = { serviceName: env.MEGA_OTEL_SERVICE_NAME }
+  if (env.MEGA_OTEL_ENDPOINT) opts.endpoint = env.MEGA_OTEL_ENDPOINT
+  if (env.MEGA_OTEL_EXPORTER) opts.exporter = env.MEGA_OTEL_EXPORTER
+  if (env.MEGA_OTEL_VERSION) opts.version = env.MEGA_OTEL_VERSION
+  if (env.MEGA_OTEL_ENVIRONMENT) opts.environment = env.MEGA_OTEL_ENVIRONMENT
+  const ratio = env.MEGA_OTEL_SAMPLING_RATIO
+  if (ratio !== undefined && ratio !== '') {
+    opts.sampling = ratio === 'always_on' || ratio === 'always_off' ? ratio : Number(ratio)
+  }
+  init(opts)
+  return true
+}
+
+/**
+ * 단일 어댑터의 `onCallStart`/`onCallEnd` 를 구독해 span 으로 변환한다. init 전이면 no-op(리스너 미부착).
+ * 이미 구독된 어댑터를 다시 부르면 기존 구독을 유지(중복 부착 방지).
+ *
+ * @param {import('../adapters/mega-adapter.js').MegaAdapter} adapter
+ * @param {{ domain?: string, driver?: string, key?: string }} [meta] - span 속성 보강용 메타.
+ * @returns {() => void} 구독 해제 함수.
+ */
+export function subscribe(adapter, meta = {}) {
+  if (state === null) return () => {} // 옵트인 OFF — 리스너 미부착.
+  const existing = subscriptions.get(adapter)
+  if (existing) return existing
+
+  /** @type {{ adapterName: string, domain: string|null, driver: string|null, key: string|null }} */
+  const m = {
+    adapterName: adapter?.constructor?.name ?? 'MegaAdapter',
+    domain: meta.domain ?? null,
+    driver: meta.driver ?? null,
+    key: meta.key ?? null,
+  }
+  /** @type {import('../adapters/mega-adapter.js').HookListener} */
+  const onStart = (callName, attrs) => {
+    try {
+      // 부모 = 진행 중 바깥 호출의 스코프 토큰(베이스 `run()` 이 설정). 없으면 루트.
+      return handleStart(m, adapter._currentCallScope, callName, attrs)
+    } catch (err) {
+      // 트레이싱 버그가 도메인 호출을 깨면 안 됨(M1 정합) — 표면화 후 무시.
+      console.warn('[MegaTracing] onCallStart handler error (ignored):', err)
+      return undefined
+    }
+  }
+  /** @type {import('../adapters/mega-adapter.js').HookListener} */
+  const onEnd = (callName, attrs, err, scope) => {
+    try {
+      handleEnd(scope, attrs, err)
+    } catch (e) {
+      console.warn('[MegaTracing] onCallEnd handler error (ignored):', e)
+    }
+  }
+  const unStart = adapter.addHookListener('onCallStart', onStart)
+  const unEnd = adapter.addHookListener('onCallEnd', onEnd)
+  const unsubscribe = () => {
+    unStart()
+    unEnd()
+    subscriptions.delete(adapter)
+  }
+  subscriptions.set(adapter, unsubscribe)
+  return unsubscribe
+}
+
+/**
+ * 부팅된 전역 어댑터 매니저의 **모든 공유 어댑터**에 hook 리스너를 일괄 구독한다(ADR-102 글로벌 공유).
+ * `connectAll` 이후 호출 권장(연결 안 된 어댑터도 구독은 안전 — 첫 호출 때 span 발화).
+ *
+ * @param {{ entries: () => Array<{ domain: string, key: string, driver: string, adapter: import('../adapters/mega-adapter.js').MegaAdapter }> }} manager -
+ *   `MegaAdapterManager` (entries() 노출). 테스트 더블도 같은 형태면 됨.
+ * @returns {number} 구독한 어댑터 수.
+ */
+export function attachToManager(manager) {
+  if (state === null) return 0 // 옵트인 OFF.
+  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
+}
+
+/**
+ * 트레이싱 종료 — 모든 구독 해제 + 남은 span flush + provider 종료. init 전이면 no-op.
+ * @returns {Promise<void>}
+ */
+export async function shutdown() {
+  for (const unsubscribe of [...subscriptions.values()]) unsubscribe()
+  subscriptions.clear()
+  const s = state
+  state = null
+  // 활성 컨텍스트 ALS 비활성화 — 남은 enterWith 컨텍스트를 모두 비운다(다음 run()/enterWith 가 재활성화).
+  activeContextStore.disable()
+  if (s !== null) {
+    await s.provider.forceFlush()
+    await s.provider.shutdown()
+  }
+}
+
+/**
+ * 현재 exporter 반환(테스트·디버그용). `InMemorySpanExporter` 면 `.getFinishedSpans()` 로 span 검사.
+ * @returns {import('@opentelemetry/sdk-trace-base').SpanExporter | null}
+ */
+export function getExporter() {
+  return state?.exporter ?? null
+}
+
+/**
+ * 강제 flush — `BatchSpanProcessor` 사용 시 테스트에서 span 발화를 기다릴 때.
+ * @returns {Promise<void>}
+ */
+export async function forceFlush() {
+  if (state !== null) await state.provider.forceFlush()
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// 사용자/요청 span API (ADR-126) — HTTP/WS 루트 span · ctx.tracer.span · 로그 trace_id
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * **사용자 직접 span** — `name` span 을 현재 활성 span(없으면 루트)의 자식으로 열고 `fn(span)` 을 그
+ * span 컨텍스트 안에서 실행한다(`run()` 격리). `fn` 이 Promise 면 resolve/reject 까지 기다려 span 을
+ * 닫는다. 옵트인 OFF 면 0 비용 — span 없이 `fn(NOOP_SPAN)` 만 호출한다. `ctx.tracer.span` 의 구현부.
+ *
+ * @template T
+ * @param {string} name - span 이름(예: `'charge.process'`).
+ * @param {(span: import('@opentelemetry/api').Span) => T} fn - span 안에서 실행할 함수(span 인자 받음).
+ * @param {{ attributes?: Record<string, any>, kind?: import('@opentelemetry/api').SpanKind }} [opts]
+ * @returns {T} `fn` 의 반환값(그대로 — 동기/Promise 모두).
+ * @throws {*} `fn` 이 throw/reject 하면 span 에 기록(ERROR)하고 그대로 재전파(silent 금지).
+ */
+export function span(name, fn, opts = {}) {
+  if (state === null) return fn(NOOP_SPAN) // 옵트인 OFF — 0 비용.
+  const parentCtx = getActiveContext()
+  const sp = state.tracer.startSpan(
+    name,
+    { kind: opts.kind, attributes: filterAttributes(opts.attributes) },
+    parentCtx,
+  )
+  const childCtx = trace.setSpan(parentCtx, sp)
+  // run() 격리 — fn 내부의 중첩 span/어댑터 호출이 sp 를 부모로 읽는다(요청 ALS).
+  return activeContextStore.run(childCtx, () => {
+    /** @type {any} */
+    let result
+    try {
+      result = fn(sp)
+    } catch (err) {
+      endSpanWith(sp, err)
+      throw err
+    }
+    if (result && typeof result.then === 'function') {
+      return /** @type {any} */ (
+        result.then(
+          (/** @type {any} */ v) => {
+            endSpanWith(sp, undefined)
+            return v
+          },
+          (/** @type {any} */ err) => {
+            endSpanWith(sp, err)
+            throw err
+          },
+        )
+      )
+    }
+    endSpanWith(sp, undefined)
+    return result
+  })
+}
+
+/**
+ * **시작/종료 분리형 span** — HTTP `onRequest`/`onResponse` 처럼 시작과 종료가 다른 콜백인 경우에 쓴다.
+ * span 을 열고 `enterWith` 로 현재 비동기 흐름의 활성 컨텍스트를 이 span 으로 만든 뒤, `end(err)` 를
+ * 가진 핸들을 돌려준다(핸들은 보통 `req` 에 보관했다가 응답 시 닫는다). 옵트인 OFF 면 no-op 핸들.
+ *
+ * ⚠️ `enterWith` 는 **요청별로 격리된 비동기 흐름**에서만 호출해야 한다(HTTP 요청·WS 메시지 콜백은 각각
+ *   독립 async context 라 안전 — 실측 확인). 공유 동기 스코프에서 부르면 sibling 오염(ADR-114) 위험.
+ *
+ * @param {string} name
+ * @param {{ attributes?: Record<string, any>, kind?: import('@opentelemetry/api').SpanKind, parent?: import('@opentelemetry/api').Context }} [opts]
+ * @returns {{ span: import('@opentelemetry/api').Span, end: (err?: unknown, endAttributes?: Record<string, any>) => void }}
+ */
+export function enterSpan(name, opts = {}) {
+  if (state === null) return /** @type {any} */ (NOOP_HANDLE)
+  const parentCtx = opts.parent ?? getActiveContext()
+  const sp = state.tracer.startSpan(
+    name,
+    { kind: opts.kind, attributes: filterAttributes(opts.attributes) },
+    parentCtx,
+  )
+  activeContextStore.enterWith(trace.setSpan(parentCtx, sp))
+  return {
+    span: sp,
+    end(err, endAttributes) {
+      if (endAttributes) sp.setAttributes(filterAttributes(endAttributes))
+      endSpanWith(sp, err)
+    },
+  }
+}
+
+/**
+ * **HTTP 루트 span** 전용 헬퍼 — `onRequest` 에서 열고(`enterWith` 로 활성화), `onError` 에서 예외를
+ * 기록(`setError`), `onResponse` 에서 상태코드와 함께 닫는다(`finish`). HTTP 시맨틱(5xx=ERROR)을 한곳에
+ * 모아 배선 코드(mega-app)가 OTel enum 을 안 만지게 한다. 옵트인 OFF 면 no-op 핸들.
+ *
+ * @param {{ method: string, route: string, path: string, host?: string, app: string }} info
+ * @returns {{ span: import('@opentelemetry/api').Span, setError: (err: unknown) => void, finish: (statusCode: number) => void }}
+ */
+export function enterHttpSpan({ method, route, path, host, app }) {
+  if (state === null) return /** @type {any} */ (NOOP_HTTP_HANDLE)
+  const handle = enterSpan(`http.${method} ${route}`, {
+    kind: SpanKind.SERVER,
+    attributes: {
+      'http.request.method': method,
+      'http.route': route,
+      'url.path': path,
+      ...(host ? { 'server.address': host } : {}),
+      'mega.app': app,
+    },
+  })
+  let errored = false
+  return {
+    span: handle.span,
+    setError(err) {
+      errored = true
+      const e = err instanceof Error ? err : new Error(String(err))
+      handle.span.recordException(e)
+      handle.span.setStatus({ code: SpanStatusCode.ERROR, message: e.message })
+    },
+    finish(statusCode) {
+      handle.span.setAttribute('http.response.status_code', statusCode)
+      // OTel: SERVER span 은 5xx 만 ERROR. 4xx 는 클라이언트 잘못이라 UNSET 유지(이미 errored 면 보존).
+      if (!errored && Number(statusCode) >= 500) {
+        handle.span.setStatus({ code: SpanStatusCode.ERROR, message: `HTTP ${statusCode}` })
+      }
+      handle.span.end()
+    },
+  }
+}
+
+/**
+ * 현재 활성 span 의 trace/span id (로그 상관관계용). 활성 span 없거나 옵트인 OFF 면 null.
+ * @returns {{ traceId: string, spanId: string } | null}
+ */
+export function currentTraceIds() {
+  if (state === null) return null
+  const sp = trace.getSpan(getActiveContext())
+  if (!sp) return null
+  const sc = sp.spanContext()
+  if (!sc || typeof sc.traceId !== 'string' || sc.traceId === '' || sc.traceId === '0'.repeat(32)) return null
+  return { traceId: sc.traceId, spanId: sc.spanId }
+}
+
+/**
+ * **pino mixin** — 활성 span 이 있으면 모든 로그 라인에 `{ trace_id, span_id }` 를 주입한다(ADR-116 (d)).
+ * 로거가 켜진 앱에서 `logger: { mixin: MegaTracing.logMixin }` 로 배선하면 요청 로그가 trace 와 상관된다.
+ * 활성 span 없으면 빈 객체(주입 없음). 옵트인 OFF 면 항상 빈 객체 → 0 비용.
+ * @returns {{ trace_id?: string, span_id?: string }}
+ */
+export function logMixin() {
+  const ids = currentTraceIds()
+  return ids ? { trace_id: ids.traceId, span_id: ids.spanId } : {}
+}
+
+/**
+ * `ctx.tracer` 로 노출하는 트레이서 표면(ADR-077/116 canonical `ctx.tracer.span`). 모듈 싱글톤 — 활성
+ * 컨텍스트는 ALS 가 요청별로 들고 있으므로 객체 1개를 모든 요청이 공유해도 안전(getter 가 ALS 를 읽음).
+ */
+export const tracer = Object.freeze({
+  span,
+  /** @returns {import('@opentelemetry/api').Span | undefined} 현재 활성 span(없으면 undefined — 03-api-spec §10). */
+  activeSpan() {
+    if (state === null) return undefined
+    return trace.getSpan(getActiveContext())
+  },
+  /** @returns {string|null} 현재 활성 trace id(없으면 null). */
+  get traceId() {
+    return currentTraceIds()?.traceId ?? null
+  },
+  /** @returns {string|null} 현재 활성 span id(없으면 null). */
+  get spanId() {
+    return currentTraceIds()?.spanId ?? null
+  },
+})
+
+// ──────────────────────────────────────────────────────────────────────────
+// 내부 — span 시작/종료 핸들러 (hook 리스너가 호출)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * span 을 결과(성공/에러)에 맞게 닫는다 — 공통 종료 로직(상태·예외 기록).
+ * @param {import('@opentelemetry/api').Span} sp
+ * @param {unknown} err - 있으면 ERROR + recordException, 없으면 OK.
+ * @returns {void}
+ */
+function endSpanWith(sp, err) {
+  if (err) {
+    const e = err instanceof Error ? err : new Error(String(err))
+    sp.recordException(e)
+    sp.setStatus({ code: SpanStatusCode.ERROR, message: e.message })
+  } else {
+    sp.setStatus({ code: SpanStatusCode.OK })
+  }
+  sp.end()
+}
+
+/**
+ * attrs 에서 OTel 허용 primitive 만 골라 **새 객체**로 반환한다(span 시작 속성용).
+ * @param {Record<string, any>} [attrs]
+ * @returns {Record<string, any>}
+ */
+function filterAttributes(attrs) {
+  /** @type {Record<string, any>} */
+  const out = {}
+  mergePrimitiveAttrs(out, attrs)
+  return out
+}
+
+/**
+ * `onCallStart` → span 시작. 부모 스코프 토큰(있으면)을 parent context 로 삼아 span 을 만들고,
+ * 자식이 부모로 읽을 **스코프 토큰**(span 을 담은 OTel context)을 반환한다. 베이스 `_instrument` 가
+ * 이 토큰으로 도메인 fn 을 `run()` 안에서 실행한다.
+ *
+ * @param {{ adapterName: string, domain: string|null, driver: string|null, key: string|null }} meta
+ * @param {import('@opentelemetry/api').Context | undefined} parentScope - `adapter._currentCallScope`.
+ * @param {string} callName
+ * @param {object} [attrs]
+ * @returns {import('@opentelemetry/api').Context | undefined} 스코프 토큰(span 담은 context) 또는 undefined(비활성).
+ */
+function handleStart(meta, parentScope, callName, attrs) {
+  if (state === null) return undefined
+  // 부모 우선순위: (1) 진행 중 바깥 어댑터 호출의 스코프(`run()` seam) → (2) HTTP/WS/ctx.tracer 가 연 활성
+  //   span(요청 ALS) → (3) 루트. (2) 폴백 덕에 핸들러 최상위의 어댑터 호출이 HTTP 루트 span 의 자식이 된다.
+  const parentCtx = parentScope ?? getActiveContext()
+  const name = meta.driver ? `${meta.driver}.${callName}` : callName
+  const span = state.tracer.startSpan(
+    name,
+    { kind: SpanKind.CLIENT, attributes: buildStartAttributes(meta, callName, attrs) },
+    parentCtx,
+  )
+  return trace.setSpan(parentCtx, span)
+}
+
+/**
+ * `onCallEnd` → 스코프 토큰에서 span 을 꺼내 종료한다. 토큰이 없으면(비활성 호출) 무시.
+ * `state`(활성) 여부와 무관하게 토큰의 span 을 닫아 누수를 막는다(shutdown 직후 in-flight 케이스).
+ *
+ * @param {import('@opentelemetry/api').Context | undefined} scope - 짝 `onCallStart` 의 반환 토큰.
+ * @param {object} [attrs] - 결과 속성(`{ ...startAttrs, latencyMs }`).
+ * @param {Error} [err] - 있으면 status=ERROR + recordException.
+ * @returns {void}
+ */
+function handleEnd(scope, attrs, err) {
+  const span = scope ? trace.getSpan(scope) : undefined
+  if (!span) return // 비활성 호출(토큰 없음) 또는 불균형 — 방어적 무시.
+  applyEndAttributes(span, attrs)
+  if (err) {
+    span.recordException(err)
+    span.setStatus({ code: SpanStatusCode.ERROR, message: err instanceof Error ? err.message : String(err) })
+  } else {
+    span.setStatus({ code: SpanStatusCode.OK })
+  }
+  span.end()
+}
+
+/**
+ * 시작 span 속성 구성 — 어댑터 메타(`mega.*`) + 도메인별 시맨틱(`db.system.name`) + 사용자 attrs.
+ * @param {{ adapterName: string, domain: string|null, driver: string|null, key: string|null }} meta
+ * @param {string} callName
+ * @param {object} [attrs]
+ * @returns {Record<string, any>}
+ */
+function buildStartAttributes(meta, callName, attrs) {
+  /** @type {Record<string, any>} */
+  const out = { 'mega.adapter': meta.adapterName, 'mega.call': callName }
+  if (meta.domain) out['mega.domain'] = meta.domain
+  if (meta.driver) out['mega.driver'] = meta.driver
+  if (meta.key) out['mega.key'] = meta.key
+  // DB 도메인은 OTel 시맨틱 컨벤션 `db.system.name` 으로도 노출(백엔드 자동 인식).
+  if (meta.domain === 'db' && meta.driver) out[ATTR_DB_SYSTEM_NAME] = meta.driver
+  mergePrimitiveAttrs(out, attrs)
+  // 어댑터는 OTel 무지 — `statement`(파라미터화된 SQL) 키로 넘기면 여기서 표준 `db.query.text` 로
+  // 매핑한다(ADR-138). DB 도메인 한정. 바인딩 값은 어댑터가 애초에 안 싣는다(시크릿·카디널리티 안전).
+  if (meta.domain === 'db' && typeof out.statement === 'string') {
+    out[ATTR_DB_QUERY_TEXT] = out.statement
+    delete out.statement
+  }
+  return out
+}
+
+/**
+ * 종료 시 결과 속성 반영 — latency 를 `mega.latency_ms` 로, 그 외 신규 primitive attr 머지.
+ * @param {import('@opentelemetry/api').Span} span
+ * @param {object} [attrs]
+ * @returns {void}
+ */
+function applyEndAttributes(span, attrs) {
+  if (!attrs || typeof attrs !== 'object') return
+  const a = /** @type {Record<string, any>} */ (attrs)
+  if (typeof a.latencyMs === 'number') span.setAttribute('mega.latency_ms', a.latencyMs)
+  /** @type {Record<string, any>} */
+  const rest = {}
+  mergePrimitiveAttrs(rest, attrs)
+  delete rest.latencyMs // mega.latency_ms 로 이미 반영.
+  // `statement` 는 시작 span 에서 이미 `db.query.text` 로 매핑됐다(ADR-138). 종료 attr 은 시작 attr 을
+  // 다시 싣고 오므로, 여기서 원키를 지우지 않으면 매핑 전 `statement` 가 span 에 되살아난다.
+  delete rest.statement
+  if (Object.keys(rest).length > 0) span.setAttributes(rest)
+}
+
+/**
+ * attrs 중 OTel 이 허용하는 primitive(문자열/숫자/불리언, 또는 그 배열)만 골라 머지한다.
+ * `undefined`/`null`/객체/함수는 건너뛴다(예: `withTransaction` 의 `{ table: undefined }`).
+ * @param {Record<string, any>} target
+ * @param {object} [attrs]
+ * @returns {void}
+ */
+function mergePrimitiveAttrs(target, attrs) {
+  if (!attrs || typeof attrs !== 'object') return
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === undefined || v === null) continue
+    const t = typeof v
+    if (t === 'string' || t === 'number' || t === 'boolean') {
+      target[k] = v
+    } else if (Array.isArray(v) && v.every((x) => ['string', 'number', 'boolean'].includes(typeof x))) {
+      target[k] = v
+    }
+    // 그 외(객체/함수/심볼)는 스킵 — OTel attribute 값으로 부적합 + 의도치 않은 페이로드 노출 방지.
+  }
+}
+
+/**
+ * 샘플링 옵션 → OTel Sampler. 비율은 `ParentBasedSampler(root=ratio)` 로 감싸 자식이 부모 결정을 따른다.
+ * @param {string|number|undefined} sampling
+ * @returns {import('@opentelemetry/sdk-trace-base').Sampler}
+ */
+function buildSampler(sampling) {
+  if (sampling === undefined || sampling === null || sampling === 'always_on') return new AlwaysOnSampler()
+  if (sampling === 'always_off') return new AlwaysOffSampler()
+  let ratio
+  if (typeof sampling === 'number') ratio = sampling
+  else if (typeof sampling === 'string' && sampling.startsWith('traceidratio:')) {
+    ratio = Number(sampling.slice('traceidratio:'.length))
+  } else {
+    throw new MegaConfigError(
+      'tracing.invalid_sampling',
+      `sampling must be 'always_on' | 'always_off' | 'traceidratio:<0..1>' | <number 0..1> (got '${sampling}').`,
+      { details: { sampling } },
+    )
+  }
+  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 1) {
+    throw new MegaConfigError(
+      'tracing.invalid_sampling',
+      `sampling ratio must be a number in [0, 1] (got ${ratio}).`,
+      { details: { sampling, ratio } },
+    )
+  }
+  return new ParentBasedSampler({ root: new TraceIdRatioBasedSampler(ratio) })
+}
+
+/**
+ * exporter 옵션 → { exporter, processorKind }. 문자열 종류 또는 인스턴스 직접 주입을 받는다.
+ * @param {{ exporter?: any, endpoint?: string, processor?: 'simple'|'batch' }} opts
+ * @returns {{ exporter: import('@opentelemetry/sdk-trace-base').SpanExporter, processorKind: 'simple'|'batch' }}
+ */
+function buildExporter(opts) {
+  const explicitProcessor = opts.processor
+  // 인스턴스 직접 주입(테스트의 InMemorySpanExporter 등) — `export` 함수를 가진 객체로 판별.
+  if (opts.exporter && typeof opts.exporter === 'object' && typeof opts.exporter.export === 'function') {
+    return { exporter: opts.exporter, processorKind: explicitProcessor ?? 'simple' }
+  }
+  const kind = typeof opts.exporter === 'string' ? opts.exporter : opts.endpoint ? 'otlp' : 'console'
+  switch (kind) {
+    case 'console':
+      return { exporter: new ConsoleSpanExporter(), processorKind: explicitProcessor ?? 'simple' }
+    case 'inmemory':
+      return { exporter: new InMemorySpanExporter(), processorKind: explicitProcessor ?? 'simple' }
+    case 'otlp':
+      return {
+        exporter: new OTLPTraceExporter(opts.endpoint ? { url: opts.endpoint } : {}),
+        processorKind: explicitProcessor ?? 'batch',
+      }
+    case 'zipkin':
+      // Zipkin v2 JSON span 포맷. endpoint 미지정 시 ZipkinExporter 디폴트(http://localhost:9411/api/v2/spans).
+      return {
+        exporter: new ZipkinExporter(opts.endpoint ? { url: opts.endpoint } : {}),
+        processorKind: explicitProcessor ?? 'batch',
+      }
+    default:
+      throw new MegaConfigError(
+        'tracing.invalid_exporter',
+        `exporter must be 'console' | 'otlp' | 'zipkin' | 'inmemory' | <SpanExporter instance> (got '${kind}').`,
+        { details: { exporter: kind } },
+      )
+  }
+}
+
+/**
+ * 테스트 격리용 reset — 동기 강제 정리(provider flush 없이 상태만 비움). 비동기 정상 종료는 `shutdown`.
+ * @returns {void}
+ */
+export function _reset() {
+  for (const unsubscribe of [...subscriptions.values()]) unsubscribe()
+  subscriptions.clear()
+  activeContextStore.disable()
+  state = null
+}