@omni-api/plugin-observability 0.0.1

package/README.md

@@ -0,0 +1,86 @@
+# @omni/plugin-observability
+
+OmniAPI 一站式可观测：**结构化日志 + OTel 追踪 + Prometheus 指标**，三件套全部 **peer-optional** —— 装哪个用哪个，都不装也能跑。
+
+## 安装
+
+最小：
+```bash
+pnpm add @omni/plugin-observability
+```
+
+按需启用（业务自己决定要哪个）：
+```bash
+pnpm add pino                       # 结构化日志
+pnpm add @opentelemetry/api         # 分布式追踪（你需要自己配 SDK / Exporter）
+pnpm add prom-client                # Prometheus 指标
+```
+
+## 快速使用
+
+```ts
+import { createObservability } from '@omni/plugin-observability';
+
+const obs = await createObservability({
+  logger: { level: 'info', bindings: { service: 'orders', env: 'prod' } },
+  metrics: { prefix: 'myapp' },
+});
+
+defineProcedure({
+  name: 'order.create',
+  middleware: [obs.middleware /* 自动 log + trace + metrics */],
+  // ...
+});
+
+// HTTP 暴露 /metrics
+import { createHttpAdapter } from '@omni/http';
+const http = createHttpAdapter({ registry, logger: obs.logger });
+http.server.get('/_metrics', async (_req, reply) => {
+  reply.header('content-type', 'text/plain; version=0.0.4');
+  return obs.metrics.render();
+});
+```
+
+## 自动产出
+
+每个 procedure 调用都会产生：
+
+### 日志
+```
+INFO  procedure.success {"procedure":"order.create","source":"http","requestId":"req_xxx","durationMs":42}
+WARN  procedure.failure {"procedure":"order.delete","code":"FORBIDDEN","durationMs":3,"errorMessage":"..."}
+ERROR procedure.failure {"procedure":"x","code":"INTERNAL",...}   # 5xx 用 error 级别
+```
+日志级别策略：
+- 4xx 业务错误 → `warn`（业务可预期）
+- 5xx / 非 OmniError → `error`
+
+### 指标（Prometheus）
+- `omni_procedure_total{name, source, status, code}` —— 计数
+  - status: `success` / `client_error` / `server_error`
+  - code: `OK` / `VALIDATION_ERROR` / `FORBIDDEN` / ...
+- `omni_procedure_duration_seconds{name, source, status}` —— 直方图（默认桶 1ms~10s）
+
+### Trace
+- 每个 procedure 一个 span：`procedure <name>`
+- 自动属性：`omni.procedure.name`、`omni.source`、`omni.request_id`、`omni.user_id`、`omni.duration_ms`
+- 异常自动 `recordException` + `setStatus(ERROR)`
+
+## 子模块单独使用
+
+```ts
+import { createLogger, createTracer, createMetrics } from '@omni/plugin-observability';
+
+const logger  = await createLogger({ level: 'info' });
+const tracer  = await createTracer({ name: 'orders' });
+const metrics = await createMetrics({ prefix: 'app' });
+```
+
+## 为什么 peer-optional？
+
+避免框架强绑定具体观测栈。业务可能：
+- 只要日志（pino），不要 metrics
+- 内部已经有自家 OTel 配置
+- 只想跑测试，三个都不要
+
+→ 这些场景全部支持，零 if-else。

package/dist/index.d.ts

@@ -0,0 +1,204 @@
+import { Logger, Middleware } from '@omni-api/core';
+
+/** pino 的最小接口（避免引入完整类型） */
+interface PinoLike {
+    trace(obj: unknown, msg?: string): void;
+    debug(obj: unknown, msg?: string): void;
+    info(obj: unknown, msg?: string): void;
+    warn(obj: unknown, msg?: string): void;
+    error(obj: unknown, msg?: string): void;
+    child(bindings: Record<string, unknown>): PinoLike;
+}
+interface CreateLoggerOptions {
+    /** 日志级别 */
+    level?: 'trace' | 'debug' | 'info' | 'warn' | 'error';
+    /** 全局绑定字段（如 service / version / env） */
+    bindings?: Record<string, unknown>;
+    /**
+     * 直接传入 pino 实例（已存在的 logger 复用）。
+     * 不传则尝试动态加载 pino；pino 不可用则 fallback 到 consoleLogger。
+     */
+    pino?: PinoLike;
+    /**
+     * 字段级脱敏路径（pino 原生支持的 path 语法）。
+     *
+     * 默认包含一组安全基线：authorization / cookie / token / password 等。
+     * 设 `redactPaths: false` 关闭脱敏；传数组则在默认基线上叠加。
+     */
+    redactPaths?: string[] | false;
+    /** 自定义替换值，默认 '[REDACTED]' */
+    redactCensor?: string;
+}
+/**
+ * 创建结构化 Logger。
+ *
+ * - 优先级：options.pino > 动态加载 pino > consoleLogger fallback
+ * - 异步加载 pino（peer-optional）；为了让构造同步可用，提供了同步 fallback
+ *
+ * 业务通常这样用：
+ *   const logger = await createLogger({ level: 'info', bindings: { service: 'orders' } });
+ */
+declare function createLogger(options?: CreateLoggerOptions): Promise<Logger>;
+
+/**
+ * Span 接口（OTel API 的最小子集）—— 用最小约束避免强依赖整个 OTel 类型库。
+ */
+interface Span {
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    recordException(err: unknown): void;
+    end(): void;
+}
+/**
+ * Tracer 接口。
+ */
+interface Tracer {
+    /** 创建 span 并执行 fn，正常 / 异常都会自动 end */
+    startActiveSpan<T>(name: string, attributes: Record<string, unknown>, fn: (span: Span) => Promise<T>): Promise<T>;
+}
+/** OTel SpanStatusCode 常量（避免引入 OTel 包） */
+declare const SPAN_STATUS_OK = 1;
+declare const SPAN_STATUS_ERROR = 2;
+/** No-op Tracer：OTel 未安装时的兜底，保证业务代码不需要写 if 判断 */
+declare const noopTracer: Tracer;
+interface CreateTracerOptions {
+    /** Tracer 名称，默认 'omni-api' */
+    name?: string;
+    /** 直接注入 OTel TracerProvider 中拿到的 tracer（高级用法） */
+    tracer?: {
+        startActiveSpan: (name: string, fn: (s: Record<string, unknown>) => unknown) => unknown;
+    };
+}
+/**
+ * 创建 Tracer。
+ *
+ * - 优先级：options.tracer > 动态加载 @opentelemetry/api > noopTracer
+ * - OTel 未安装时返回 no-op，业务代码无需 if-else
+ */
+declare function createTracer(options?: CreateTracerOptions): Promise<Tracer>;
+
+/**
+ * 一个最小的 Counter 接口（避开 prom-client 完整类型）。
+ */
+interface Counter {
+    inc(labels?: Record<string, string | number>, value?: number): void;
+}
+/**
+ * 一个最小的 Histogram 接口。
+ */
+interface Histogram {
+    observe(labels: Record<string, string | number>, value: number): void;
+}
+/**
+ * Metrics 接口：
+ *   - procedureTotal: 累计调用数（按 status / source / name 维度）
+ *   - procedureDuration: 调用耗时分布（histogram，秒为单位）
+ *   - render(): 输出 Prometheus 文本（接 /_metrics 用）
+ */
+interface Metrics {
+    procedureTotal: Counter;
+    procedureDuration: Histogram;
+    /** 渲染 Prometheus exposition 文本 */
+    render(): Promise<string>;
+}
+interface PromClientLike {
+    Counter: new (config: {
+        name: string;
+        help: string;
+        labelNames: string[];
+        registers?: unknown[];
+    }) => Counter;
+    Histogram: new (config: {
+        name: string;
+        help: string;
+        labelNames: string[];
+        buckets?: number[];
+        registers?: unknown[];
+    }) => Histogram;
+    Registry: new () => {
+        metrics(): Promise<string>;
+        clear(): void;
+    };
+    register: {
+        metrics(): Promise<string>;
+    };
+}
+declare const noopMetrics: Metrics;
+interface CreateMetricsOptions {
+    /** 指标名前缀，默认 'omni' */
+    prefix?: string;
+    /** Histogram 桶（秒），默认覆盖 1ms ~ 10s */
+    buckets?: number[];
+    /** 直接注入 prom-client（测试用） */
+    promClient?: PromClientLike;
+}
+/**
+ * 创建 metrics 实例。
+ *
+ * - prom-client 未安装则返回 no-op
+ * - 装了的话，自动注册两个指标到 **新建的独立 Registry**（避免和业务原有 register 冲突）
+ *   render() 输出该 Registry 的指标
+ */
+declare function createMetrics(options?: CreateMetricsOptions): Promise<Metrics>;
+
+interface ObservabilityDeps {
+    logger: Logger;
+    tracer: Tracer;
+    metrics: Metrics;
+}
+interface ObservabilityOptions {
+    /** 是否在 info 级别打印每次成功调用（默认 true） */
+    logSuccess?: boolean;
+    /** 把 input 写到 log（默认 false，避免日志泄漏敏感信息） */
+    logInput?: boolean;
+    /** 把 output 写到 log（默认 false） */
+    logOutput?: boolean;
+}
+/**
+ * 一体化可观测性中间件：自动包住 procedure 执行，产出 log + trace + metrics。
+ *
+ * 用法（作为全局中间件）：
+ *   const deps = { logger, tracer, metrics };
+ *   defineProcedure({ middleware: [observability(deps)], ... });
+ *
+ * 但更常见是放到 router 共享，或框架未来的 App.use 全局挂载。
+ */
+declare function observability(deps: ObservabilityDeps, options?: ObservabilityOptions): Middleware;
+
+interface ObservabilityFactoryOptions {
+    logger?: CreateLoggerOptions;
+    tracer?: CreateTracerOptions;
+    metrics?: CreateMetricsOptions;
+    middleware?: ObservabilityOptions;
+}
+interface ObservabilityFactory extends ObservabilityDeps {
+    /** 一体化中间件：放进 procedure.middleware 即生效 */
+    middleware: Middleware;
+}
+/**
+ * 一站式工厂：创建好 logger / tracer / metrics 三件套，并产出对应中间件。
+ *
+ * 三个子模块都是 peer-optional：
+ *   - 装了 pino → 走 pino；否则走 consoleLogger
+ *   - 装了 @opentelemetry/api → 走 OTel；否则 no-op
+ *   - 装了 prom-client → 走 prom；否则 no-op，render() 返回空字符串
+ *
+ * 用法：
+ *   const obs = await createObservability({
+ *     logger: { level: 'info', bindings: { service: 'orders' } },
+ *     metrics: { prefix: 'myapp' },
+ *   });
+ *   defineProcedure({ middleware: [obs.middleware], ... });
+ *
+ *   // HTTP 暴露 /metrics
+ *   app.get('/_metrics', async (req, reply) => {
+ *     reply.header('content-type', 'text/plain; version=0.0.4');
+ *     return obs.metrics.render();
+ *   });
+ */
+declare function createObservability(options?: ObservabilityFactoryOptions): Promise<ObservabilityFactory>;
+
+export { type Counter, type CreateLoggerOptions, type CreateMetricsOptions, type CreateTracerOptions, type Histogram, type Metrics, type ObservabilityDeps, type ObservabilityFactory, type ObservabilityFactoryOptions, type ObservabilityOptions, SPAN_STATUS_ERROR, SPAN_STATUS_OK, type Span, type Tracer, createLogger, createMetrics, createObservability, createTracer, noopMetrics, noopTracer, observability };

package/dist/index.js

@@ -0,0 +1,264 @@
+import { consoleLogger, OmniError } from '@omni-api/core';
+
+// src/logger.ts
+
+// src/optional-require.ts
+async function tryRequire(moduleId) {
+  try {
+    const mod = await import(
+      /* @vite-ignore */
+      moduleId
+    );
+    return mod;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/logger.ts
+var DEFAULT_REDACT_PATHS = [
+  // Header 相关
+  "req.headers.authorization",
+  'req.headers["x-api-key"]',
+  "req.headers.cookie",
+  "request.headers.authorization",
+  'request.headers["x-api-key"]',
+  "request.headers.cookie",
+  "headers.authorization",
+  'headers["x-api-key"]',
+  "headers.cookie",
+  // 业务字段
+  "*.password",
+  "*.passwd",
+  "*.secret",
+  "*.token",
+  "*.apiKey",
+  "*.api_key",
+  "*.privateKey",
+  "*.private_key",
+  "*.idCard",
+  "*.id_card",
+  "*.cvv",
+  "*.pin",
+  // 顶层（pino 不会递归 *.path 到顶层）
+  "password",
+  "token",
+  "secret",
+  "apiKey",
+  "privateKey"
+];
+function adaptPino(p) {
+  const wrap = (level) => {
+    return (msg, meta) => {
+      if (meta) p[level](meta, msg);
+      else p[level]({}, msg);
+    };
+  };
+  return {
+    debug: wrap("debug"),
+    info: wrap("info"),
+    warn: wrap("warn"),
+    error: wrap("error"),
+    child: (extra) => adaptPino(p.child(extra))
+  };
+}
+async function createLogger(options = {}) {
+  const { level = "info", bindings = {}, pino: pinoInstance, redactPaths, redactCensor = "[REDACTED]" } = options;
+  if (pinoInstance) return adaptPino(pinoInstance);
+  const mod = await tryRequire("pino");
+  if (mod) {
+    const factory = mod.default ?? mod;
+    let finalPaths;
+    if (redactPaths === false) {
+      finalPaths = void 0;
+    } else if (Array.isArray(redactPaths)) {
+      finalPaths = [...DEFAULT_REDACT_PATHS, ...redactPaths];
+    } else {
+      finalPaths = DEFAULT_REDACT_PATHS;
+    }
+    const pinoOpts = { level, base: bindings };
+    if (finalPaths && finalPaths.length > 0) {
+      pinoOpts.redact = { paths: finalPaths, censor: redactCensor };
+    }
+    const instance = factory(pinoOpts);
+    return adaptPino(instance);
+  }
+  return Object.keys(bindings).length > 0 ? consoleLogger.child(bindings) : consoleLogger;
+}
+
+// src/tracer.ts
+var SPAN_STATUS_OK = 1;
+var SPAN_STATUS_ERROR = 2;
+function adaptOtelTracer(otelTracer) {
+  return {
+    startActiveSpan: (name, attributes, fn) => {
+      return new Promise((resolve, reject) => {
+        otelTracer.startActiveSpan(name, async (rawSpan) => {
+          const span = rawSpan;
+          for (const [k, v] of Object.entries(attributes)) {
+            if (v !== void 0 && v !== null) span.setAttribute(k, v);
+          }
+          try {
+            const result = await fn({
+              setAttribute: (k, v) => span.setAttribute(k, v),
+              setStatus: (s) => span.setStatus(s),
+              recordException: (e) => span.recordException(e),
+              end: () => span.end()
+            });
+            span.setStatus({ code: SPAN_STATUS_OK });
+            span.end();
+            resolve(result);
+          } catch (err) {
+            span.recordException(err);
+            span.setStatus({
+              code: SPAN_STATUS_ERROR,
+              message: err instanceof Error ? err.message : String(err)
+            });
+            span.end();
+            reject(err);
+          }
+        });
+      });
+    }
+  };
+}
+var noopTracer = {
+  startActiveSpan: async (_name, _attrs, fn) => {
+    return fn({
+      setAttribute: () => void 0,
+      setStatus: () => void 0,
+      recordException: () => void 0,
+      end: () => void 0
+    });
+  }
+};
+async function createTracer(options = {}) {
+  if (options.tracer) return adaptOtelTracer(options.tracer);
+  const otel = await tryRequire("@opentelemetry/api");
+  if (otel?.trace) {
+    globalThis.__OMNI_OTEL_API__ = otel;
+    const tracer = otel.trace.getTracer(options.name ?? "omni-api");
+    return adaptOtelTracer(tracer);
+  }
+  return noopTracer;
+}
+
+// src/metrics.ts
+var noopCounter = { inc: () => void 0 };
+var noopHistogram = { observe: () => void 0 };
+var noopMetrics = {
+  procedureTotal: noopCounter,
+  procedureDuration: noopHistogram,
+  render: async () => ""
+};
+var DEFAULT_BUCKETS = [1e-3, 5e-3, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+async function createMetrics(options = {}) {
+  const prefix = options.prefix ?? "omni";
+  const buckets = options.buckets ?? DEFAULT_BUCKETS;
+  const promClient = options.promClient ?? await tryRequire("prom-client");
+  if (!promClient) return noopMetrics;
+  const registry = new promClient.Registry();
+  const procedureTotal = new promClient.Counter({
+    name: `${prefix}_procedure_total`,
+    help: "Total number of procedure invocations",
+    labelNames: ["name", "source", "status", "code"],
+    registers: [registry]
+  });
+  const procedureDuration = new promClient.Histogram({
+    name: `${prefix}_procedure_duration_seconds`,
+    help: "Procedure execution duration in seconds",
+    labelNames: ["name", "source", "status"],
+    buckets,
+    registers: [registry]
+  });
+  return {
+    procedureTotal,
+    procedureDuration,
+    render: () => registry.metrics()
+  };
+}
+function observability(deps, options = {}) {
+  const { logger: rootLogger, tracer, metrics } = deps;
+  const logSuccess = options.logSuccess ?? true;
+  const logInput = options.logInput ?? false;
+  const logOutput = options.logOutput ?? false;
+  return async (ctx, next) => {
+    const procName = ctx.procedure?.name ?? "unknown";
+    const source = ctx.source;
+    const start = process.hrtime.bigint();
+    const childLogger = rootLogger.child({ procedure: procName, source, requestId: ctx.requestId });
+    ctx.logger = childLogger;
+    return tracer.startActiveSpan(
+      `procedure ${procName}`,
+      {
+        "omni.procedure.name": procName,
+        "omni.source": source,
+        "omni.request_id": ctx.requestId,
+        "omni.user_id": ctx.user?.id ?? ""
+      },
+      async (span) => {
+        try {
+          if (logInput) {
+            childLogger.debug("procedure.start", { procedure: procName });
+          }
+          const result = await next();
+          const durationSec = Number(process.hrtime.bigint() - start) / 1e9;
+          metrics.procedureDuration.observe(
+            { name: procName, source, status: "success" },
+            durationSec
+          );
+          metrics.procedureTotal.inc({ name: procName, source, status: "success", code: "OK" });
+          span.setAttribute("omni.duration_ms", Math.round(durationSec * 1e3));
+          if (logSuccess) {
+            childLogger.info("procedure.success", {
+              durationMs: Math.round(durationSec * 1e3),
+              ...logOutput ? { output: safeStringify(result) } : {}
+            });
+          }
+          return result;
+        } catch (err) {
+          const durationSec = Number(process.hrtime.bigint() - start) / 1e9;
+          const code = err instanceof OmniError ? err.code : "INTERNAL";
+          const status = err instanceof OmniError && err.status < 500 ? "client_error" : "server_error";
+          metrics.procedureDuration.observe({ name: procName, source, status }, durationSec);
+          metrics.procedureTotal.inc({ name: procName, source, status, code });
+          span.setAttribute("omni.error.code", code);
+          span.setAttribute("omni.duration_ms", Math.round(durationSec * 1e3));
+          const isClientError = err instanceof OmniError && err.status < 500;
+          const logger = isClientError ? childLogger.warn : childLogger.error;
+          logger.call(childLogger, "procedure.failure", {
+            code,
+            durationMs: Math.round(durationSec * 1e3),
+            errorMessage: err instanceof Error ? err.message : String(err)
+          });
+          throw err;
+        }
+      }
+    );
+  };
+}
+function safeStringify(value, maxBytes = 4096) {
+  try {
+    const s = JSON.stringify(value);
+    if (s.length <= maxBytes) return s;
+    return s.slice(0, maxBytes) + "...[truncated]";
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+// src/factory.ts
+async function createObservability(options = {}) {
+  const [logger, tracer, metrics] = await Promise.all([
+    createLogger(options.logger),
+    createTracer(options.tracer),
+    createMetrics(options.metrics)
+  ]);
+  const deps = { logger, tracer, metrics };
+  const middleware = observability(deps, options.middleware);
+  return { ...deps, middleware };
+}
+
+export { SPAN_STATUS_ERROR, SPAN_STATUS_OK, createLogger, createMetrics, createObservability, createTracer, noopMetrics, noopTracer, observability };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/optional-require.ts","../src/logger.ts","../src/tracer.ts","../src/metrics.ts","../src/middleware.ts","../src/factory.ts"],"names":[],"mappings":";;;;;AAUA,eAAsB,WAAwB,QAAA,EAA0C;AACtF,EAAA,IAAI;AACF,IAAA,MAAM,MAAO,MAAM;AAAA;AAAA,MAA0B;AAAA,KAAA;AAC7C,IAAA,OAAO,GAAA;AAAA,EACT,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,MAAA;AAAA,EACT;AACF;;;ACyBA,IAAM,oBAAA,GAAuB;AAAA;AAAA,EAE3B,2BAAA;AAAA,EACA,0BAAA;AAAA,EACA,oBAAA;AAAA,EACA,+BAAA;AAAA,EACA,8BAAA;AAAA,EACA,wBAAA;AAAA,EACA,uBAAA;AAAA,EACA,sBAAA;AAAA,EACA,gBAAA;AAAA;AAAA,EAEA,YAAA;AAAA,EACA,UAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,WAAA;AAAA,EACA,cAAA;AAAA,EACA,eAAA;AAAA,EACA,UAAA;AAAA,EACA,WAAA;AAAA,EACA,OAAA;AAAA,EACA,OAAA;AAAA;AAAA,EAEA,UAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,QAAA;AAAA,EACA;AACF,CAAA;AAKA,SAAS,UAAU,CAAA,EAAqB;AACtC,EAAA,MAAM,IAAA,GAAO,CAAC,KAAA,KAA0E;AACtF,IAAA,OAAO,CAAC,KAAK,IAAA,KAAS;AACpB,MAAA,IAAI,IAAA,EAAM,CAAA,CAAE,KAAK,CAAA,CAAE,MAAM,GAAG,CAAA;AAAA,WACvB,CAAA,CAAE,KAAK,CAAA,CAAE,IAAI,GAAG,CAAA;AAAA,IACvB,CAAA;AAAA,EACF,CAAA;AACA,EAAA,OAAO;AAAA,IACL,KAAA,EAAO,KAAK,OAAO,CAAA;AAAA,IACnB,IAAA,EAAM,KAAK,MAAM,CAAA;AAAA,IACjB,IAAA,EAAM,KAAK,MAAM,CAAA;AAAA,IACjB,KAAA,EAAO,KAAK,OAAO,CAAA;AAAA,IACnB,OAAO,CAAC,KAAA,KAAU,UAAU,CAAA,CAAE,KAAA,CAAM,KAAK,CAAC;AAAA,GAC5C;AACF;AAWA,eAAsB,YAAA,CAAa,OAAA,GAA+B,EAAC,EAAoB;AACrF,EAAA,MAAM,EAAE,KAAA,GAAQ,MAAA,EAAQ,QAAA,GAAW,EAAC,EAAG,IAAA,EAAM,YAAA,EAAc,WAAA,EAAa,YAAA,GAAe,YAAA,EAAa,GAAI,OAAA;AAGxG,EAAA,IAAI,YAAA,EAAc,OAAO,SAAA,CAAU,YAAY,CAAA;AAG/C,EAAA,MAAM,GAAA,GAAM,MAAM,UAAA,CAAuF,MAAM,CAAA;AAC/G,EAAA,IAAI,GAAA,EAAK;AACP,IAAA,MAAM,OAAA,GACH,IAAmD,OAAA,IACnD,GAAA;AAGH,IAAA,IAAI,UAAA;AACJ,IAAA,IAAI,gBAAgB,KAAA,EAAO;AACzB,MAAA,UAAA,GAAa,MAAA;AAAA,IACf,CAAA,MAAA,IAAW,KAAA,CAAM,OAAA,CAAQ,WAAW,CAAA,EAAG;AACrC,MAAA,UAAA,GAAa,CAAC,GAAG,oBAAA,EAAsB,GAAG,WAAW,CAAA;AAAA,IACvD,CAAA,MAAO;AACL,MAAA,UAAA,GAAa,oBAAA;AAAA,IACf;AAEA,IAAA,MAAM,QAAA,GAAoC,EAAE,KAAA,EAAO,IAAA,EAAM,QAAA,EAAS;AAClE,IAAA,IAAI,UAAA,IAAc,UAAA,CAAW,MAAA,GAAS,CAAA,EAAG;AACvC,MAAA,QAAA,CAAS,MAAA,GAAS,EAAE,KAAA,EAAO,UAAA,EAAY,QAAQ,YAAA,EAAa;AAAA,IAC9D;AAEA,IAAA,MAAM,QAAA,GAAW,QAAQ,QAAQ,CAAA;AACjC,IAAA,OAAO,UAAU,QAAQ,CAAA;AAAA,EAC3B;AAGA,EAAA,OAAO,MAAA,CAAO,KAAK,QAAQ,CAAA,CAAE,SAAS,CAAA,GAAI,aAAA,CAAc,KAAA,CAAM,QAAQ,CAAA,GAAI,aAAA;AAC5E;;;ACnHA,IAAM,cAAA,GAAiB;AACvB,IAAM,iBAAA,GAAoB;AAG1B,SAAS,gBAAgB,UAAA,EAEd;AACT,EAAA,OAAO;AAAA,IACL,eAAA,EAAiB,CAAI,IAAA,EAAc,UAAA,EAAqC,EAAA,KAA4C;AAClH,MAAA,OAAO,IAAI,OAAA,CAAW,CAAC,OAAA,EAAS,MAAA,KAAW;AACzC,QAAA,UAAA,CAAW,eAAA,CAAgB,IAAA,EAAM,OAAO,OAAA,KAAY;AAClD,UAAA,MAAM,IAAA,GAAO,OAAA;AAOb,UAAA,KAAA,MAAW,CAAC,CAAA,EAAG,CAAC,KAAK,MAAA,CAAO,OAAA,CAAQ,UAAU,CAAA,EAAG;AAC/C,YAAA,IAAI,MAAM,MAAA,IAAa,CAAA,KAAM,MAAM,IAAA,CAAK,YAAA,CAAa,GAAG,CAAC,CAAA;AAAA,UAC3D;AACA,UAAA,IAAI;AACF,YAAA,MAAM,MAAA,GAAS,MAAM,EAAA,CAAG;AAAA,cACtB,cAAc,CAAC,CAAA,EAAG,MAAM,IAAA,CAAK,YAAA,CAAa,GAAG,CAAC,CAAA;AAAA,cAC9C,SAAA,EAAW,CAAC,CAAA,KAAM,IAAA,CAAK,UAAU,CAAC,CAAA;AAAA,cAClC,eAAA,EAAiB,CAAC,CAAA,KAAM,IAAA,CAAK,gBAAgB,CAAC,CAAA;AAAA,cAC9C,GAAA,EAAK,MAAM,IAAA,CAAK,GAAA;AAAI,aACrB,CAAA;AACD,YAAA,IAAA,CAAK,SAAA,CAAU,EAAE,IAAA,EAAM,cAAA,EAAgB,CAAA;AACvC,YAAA,IAAA,CAAK,GAAA,EAAI;AACT,YAAA,OAAA,CAAQ,MAAM,CAAA;AAAA,UAChB,SAAS,GAAA,EAAK;AACZ,YAAA,IAAA,CAAK,gBAAgB,GAAG,CAAA;AACxB,YAAA,IAAA,CAAK,SAAA,CAAU;AAAA,cACb,IAAA,EAAM,iBAAA;AAAA,cACN,SAAS,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG;AAAA,aACzD,CAAA;AACD,YAAA,IAAA,CAAK,GAAA,EAAI;AACT,YAAA,MAAA,CAAO,GAAG,CAAA;AAAA,UACZ;AAAA,QACF,CAAC,CAAA;AAAA,MACH,CAAC,CAAA;AAAA,IACH;AAAA,GACF;AACF;AAGA,IAAM,UAAA,GAAqB;AAAA,EACzB,eAAA,EAAiB,OAAO,KAAA,EAAO,MAAA,EAAQ,EAAA,KAAO;AAC5C,IAAA,OAAO,EAAA,CAAG;AAAA,MACR,cAAc,MAAM,MAAA;AAAA,MACpB,WAAW,MAAM,MAAA;AAAA,MACjB,iBAAiB,MAAM,MAAA;AAAA,MACvB,KAAK,MAAM;AAAA,KACZ,CAAA;AAAA,EACH;AACF;AAeA,eAAsB,YAAA,CAAa,OAAA,GAA+B,EAAC,EAAoB;AACrF,EAAA,IAAI,OAAA,CAAQ,MAAA,EAAQ,OAAO,eAAA,CAAgB,QAAQ,MAAM,CAAA;AAEzD,EAAA,MAAM,IAAA,GAAO,MAAM,UAAA,CAEhB,oBAAoB,CAAA;AAEvB,EAAA,IAAI,MAAM,KAAA,EAAO;AAGf,IAAC,WAAmB,iBAAA,GAAoB,IAAA;AACxC,IAAA,MAAM,SAAS,IAAA,CAAK,KAAA,CAAM,SAAA,CAAU,OAAA,CAAQ,QAAQ,UAAU,CAAA;AAC9D,IAAA,OAAO,gBAAgB,MAAM,CAAA;AAAA,EAC/B;AAEA,EAAA,OAAO,UAAA;AACT;;;ACjEA,IAAM,WAAA,GAAuB,EAAE,GAAA,EAAK,MAAM,MAAA,EAAU;AACpD,IAAM,aAAA,GAA2B,EAAE,OAAA,EAAS,MAAM,MAAA,EAAU;AAC5D,IAAM,WAAA,GAAuB;AAAA,EAC3B,cAAA,EAAgB,WAAA;AAAA,EAChB,iBAAA,EAAmB,aAAA;AAAA,EACnB,QAAQ,YAAY;AACtB;AAWA,IAAM,eAAA,GAAkB,CAAC,IAAA,EAAO,IAAA,EAAO,IAAA,EAAM,KAAA,EAAO,IAAA,EAAM,GAAA,EAAK,IAAA,EAAM,GAAA,EAAK,CAAA,EAAG,GAAA,EAAK,GAAG,EAAE,CAAA;AASvF,eAAsB,aAAA,CAAc,OAAA,GAAgC,EAAC,EAAqB;AACxF,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,IAAU,MAAA;AACjC,EAAA,MAAM,OAAA,GAAU,QAAQ,OAAA,IAAW,eAAA;AACnC,EAAA,MAAM,UAAA,GACJ,OAAA,CAAQ,UAAA,IAAe,MAAM,WAA2B,aAAa,CAAA;AAEvE,EAAA,IAAI,CAAC,YAAY,OAAO,WAAA;AAExB,EAAA,MAAM,QAAA,GAAW,IAAI,UAAA,CAAW,QAAA,EAAS;AACzC,EAAA,MAAM,cAAA,GAAiB,IAAI,UAAA,CAAW,OAAA,CAAQ;AAAA,IAC5C,IAAA,EAAM,GAAG,MAAM,CAAA,gBAAA,CAAA;AAAA,IACf,IAAA,EAAM,uCAAA;AAAA,IACN,UAAA,EAAY,CAAC,MAAA,EAAQ,QAAA,EAAU,UAAU,MAAM,CAAA;AAAA,IAC/C,SAAA,EAAW,CAAC,QAAQ;AAAA,GACrB,CAAA;AACD,EAAA,MAAM,iBAAA,GAAoB,IAAI,UAAA,CAAW,SAAA,CAAU;AAAA,IACjD,IAAA,EAAM,GAAG,MAAM,CAAA,2BAAA,CAAA;AAAA,IACf,IAAA,EAAM,yCAAA;AAAA,IACN,UAAA,EAAY,CAAC,MAAA,EAAQ,QAAA,EAAU,QAAQ,CAAA;AAAA,IACvC,OAAA;AAAA,IACA,SAAA,EAAW,CAAC,QAAQ;AAAA,GACrB,CAAA;AAED,EAAA,OAAO;AAAA,IACL,cAAA;AAAA,IACA,iBAAA;AAAA,IACA,MAAA,EAAQ,MAAO,QAAA,CAA4C,OAAA;AAAQ,GACrE;AACF;ACpEO,SAAS,aAAA,CACd,IAAA,EACA,OAAA,GAAgC,EAAC,EACrB;AACZ,EAAA,MAAM,EAAE,MAAA,EAAQ,UAAA,EAAY,MAAA,EAAQ,SAAQ,GAAI,IAAA;AAChD,EAAA,MAAM,UAAA,GAAa,QAAQ,UAAA,IAAc,IAAA;AACzC,EAAA,MAAM,QAAA,GAAW,QAAQ,QAAA,IAAY,KAAA;AACrC,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,KAAA;AAEvC,EAAA,OAAO,OAAO,KAAK,IAAA,KAAS;AAC1B,IAAA,MAAM,QAAA,GAAW,GAAA,CAAI,SAAA,EAAW,IAAA,IAAQ,SAAA;AACxC,IAAA,MAAM,SAAS,GAAA,CAAI,MAAA;AACnB,IAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,MAAA,CAAO,MAAA,EAAO;AAIpC,IAAA,MAAM,WAAA,GAAc,UAAA,CAAW,KAAA,CAAM,EAAE,SAAA,EAAW,UAAU,MAAA,EAAQ,SAAA,EAAW,GAAA,CAAI,SAAA,EAAW,CAAA;AAC9F,IAAC,IAA2B,MAAA,GAAS,WAAA;AAErC,IAAA,OAAO,MAAA,CAAO,eAAA;AAAA,MACZ,aAAa,QAAQ,CAAA,CAAA;AAAA,MACrB;AAAA,QACE,qBAAA,EAAuB,QAAA;AAAA,QACvB,aAAA,EAAe,MAAA;AAAA,QACf,mBAAmB,GAAA,CAAI,SAAA;AAAA,QACvB,cAAA,EAAgB,GAAA,CAAI,IAAA,EAAM,EAAA,IAAM;AAAA,OAClC;AAAA,MACA,OAAO,IAAA,KAAS;AACd,QAAA,IAAI;AACF,UAAA,IAAI,QAAA,EAAU;AACZ,YAAA,WAAA,CAAY,KAAA,CAAM,iBAAA,EAAmB,EAAE,SAAA,EAAW,UAAU,CAAA;AAAA,UAC9D;AAEA,UAAA,MAAM,MAAA,GAAS,MAAM,IAAA,EAAK;AAC1B,UAAA,MAAM,cAAc,MAAA,CAAO,OAAA,CAAQ,OAAO,MAAA,EAAO,GAAI,KAAK,CAAA,GAAI,GAAA;AAE9D,UAAA,OAAA,CAAQ,iBAAA,CAAkB,OAAA;AAAA,YACxB,EAAE,IAAA,EAAM,QAAA,EAAU,MAAA,EAAQ,QAAQ,SAAA,EAAU;AAAA,YAC5C;AAAA,WACF;AACA,UAAA,OAAA,CAAQ,cAAA,CAAe,GAAA,CAAI,EAAE,IAAA,EAAM,QAAA,EAAU,QAAQ,MAAA,EAAQ,SAAA,EAAW,IAAA,EAAM,IAAA,EAAM,CAAA;AAEpF,UAAA,IAAA,CAAK,aAAa,kBAAA,EAAoB,IAAA,CAAK,KAAA,CAAM,WAAA,GAAc,GAAI,CAAC,CAAA;AAEpE,UAAA,IAAI,UAAA,EAAY;AACd,YAAA,WAAA,CAAY,KAAK,mBAAA,EAAqB;AAAA,cACpC,UAAA,EAAY,IAAA,CAAK,KAAA,CAAM,WAAA,GAAc,GAAI,CAAA;AAAA,cACzC,GAAI,YAAY,EAAE,MAAA,EAAQ,cAAc,MAAM,CAAA,KAAM;AAAC,aACtD,CAAA;AAAA,UACH;AAEA,UAAA,OAAO,MAAA;AAAA,QACT,SAAS,GAAA,EAAK;AACZ,UAAA,MAAM,cAAc,MAAA,CAAO,OAAA,CAAQ,OAAO,MAAA,EAAO,GAAI,KAAK,CAAA,GAAI,GAAA;AAC9D,UAAA,MAAM,IAAA,GAAO,GAAA,YAAe,SAAA,GAAY,GAAA,CAAI,IAAA,GAAO,UAAA;AACnD,UAAA,MAAM,SAAS,GAAA,YAAe,SAAA,IAAa,GAAA,CAAI,MAAA,GAAS,MAAM,cAAA,GAAiB,cAAA;AAE/E,UAAA,OAAA,CAAQ,iBAAA,CAAkB,QAAQ,EAAE,IAAA,EAAM,UAAU,MAAA,EAAQ,MAAA,IAAU,WAAW,CAAA;AACjF,UAAA,OAAA,CAAQ,cAAA,CAAe,IAAI,EAAE,IAAA,EAAM,UAAU,MAAA,EAAQ,MAAA,EAAQ,MAAM,CAAA;AAEnE,UAAA,IAAA,CAAK,YAAA,CAAa,mBAAmB,IAAI,CAAA;AACzC,UAAA,IAAA,CAAK,aAAa,kBAAA,EAAoB,IAAA,CAAK,KAAA,CAAM,WAAA,GAAc,GAAI,CAAC,CAAA;AAGpE,UAAA,MAAM,aAAA,GAAgB,GAAA,YAAe,SAAA,IAAa,GAAA,CAAI,MAAA,GAAS,GAAA;AAC/D,UAAA,MAAM,MAAA,GAAS,aAAA,GAAgB,WAAA,CAAY,IAAA,GAAO,WAAA,CAAY,KAAA;AAC9D,UAAA,MAAA,CAAO,IAAA,CAAK,aAAa,mBAAA,EAAqB;AAAA,YAC5C,IAAA;AAAA,YACA,UAAA,EAAY,IAAA,CAAK,KAAA,CAAM,WAAA,GAAc,GAAI,CAAA;AAAA,YACzC,cAAc,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG;AAAA,WAC9D,CAAA;AAED,UAAA,MAAM,GAAA;AAAA,QACR;AAAA,MACF;AAAA,KACF;AAAA,EACF,CAAA;AACF;AAGA,SAAS,aAAA,CAAc,KAAA,EAAgB,QAAA,GAAW,IAAA,EAAc;AAC9D,EAAA,IAAI;AACF,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,SAAA,CAAU,KAAK,CAAA;AAC9B,IAAA,IAAI,CAAA,CAAE,MAAA,IAAU,QAAA,EAAU,OAAO,CAAA;AACjC,IAAA,OAAO,CAAA,CAAE,KAAA,CAAM,CAAA,EAAG,QAAQ,CAAA,GAAI,gBAAA;AAAA,EAChC,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,kBAAA;AAAA,EACT;AACF;;;AC9EA,eAAsB,mBAAA,CACpB,OAAA,GAAuC,EAAC,EACT;AAC/B,EAAA,MAAM,CAAC,MAAA,EAAQ,MAAA,EAAQ,OAAO,CAAA,GAAI,MAAM,QAAQ,GAAA,CAAI;AAAA,IAClD,YAAA,CAAa,QAAQ,MAAM,CAAA;AAAA,IAC3B,YAAA,CAAa,QAAQ,MAAM,CAAA;AAAA,IAC3B,aAAA,CAAc,QAAQ,OAAO;AAAA,GAC9B,CAAA;AAED,EAAA,MAAM,IAAA,GAA0B,EAAE,MAAA,EAAQ,MAAA,EAAQ,OAAA,EAAQ;AAC1D,EAAA,MAAM,UAAA,GAAa,aAAA,CAAc,IAAA,EAAM,OAAA,CAAQ,UAAU,CAAA;AAEzD,EAAA,OAAO,EAAE,GAAG,IAAA,EAAM,UAAA,EAAW;AAC/B","file":"index.js","sourcesContent":["/**\n * 动态加载可选 peer dependency。\n *\n * 设计：避免静态 `import` 让 pino/OTel/prom-client 成为强依赖。\n * 业务方装了哪个，就启用哪个；都没装则自动 no-op。\n *\n * 使用：\n *   const pino = await tryRequire<typeof import('pino')>('pino');\n *   if (pino) { ... } else { // fallback }\n */\nexport async function tryRequire<T = unknown>(moduleId: string): Promise<T | undefined> {\n  try {\n    const mod = (await import(/* @vite-ignore */ moduleId)) as T;\n    return mod;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * 同步版本：用 createRequire 加载（仅 CommonJS 包可用）。\n *\n * pino / prom-client 都支持 CJS interop，所以这条路可用；\n * 但如果用户用纯 ESM 项目装的纯 ESM 版本，会失败 —— 此时 fallback 到动态 import 异步加载即可。\n */\nexport function tryRequireSync<T = unknown>(moduleId: string): T | undefined {\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-require-imports\n    return require(moduleId) as T;\n  } catch {\n    return undefined;\n  }\n}\n","import { type Logger, consoleLogger } from '@omni-api/core';\nimport { tryRequire } from './optional-require.js';\n\n/** pino 的最小接口（避免引入完整类型） */\ninterface PinoLike {\n  trace(obj: unknown, msg?: string): void;\n  debug(obj: unknown, msg?: string): void;\n  info(obj: unknown, msg?: string): void;\n  warn(obj: unknown, msg?: string): void;\n  error(obj: unknown, msg?: string): void;\n  child(bindings: Record<string, unknown>): PinoLike;\n}\n\nexport interface CreateLoggerOptions {\n  /** 日志级别 */\n  level?: 'trace' | 'debug' | 'info' | 'warn' | 'error';\n  /** 全局绑定字段（如 service / version / env） */\n  bindings?: Record<string, unknown>;\n  /**\n   * 直接传入 pino 实例（已存在的 logger 复用）。\n   * 不传则尝试动态加载 pino；pino 不可用则 fallback 到 consoleLogger。\n   */\n  pino?: PinoLike;\n  /**\n   * 字段级脱敏路径（pino 原生支持的 path 语法）。\n   *\n   * 默认包含一组安全基线：authorization / cookie / token / password 等。\n   * 设 `redactPaths: false` 关闭脱敏；传数组则在默认基线上叠加。\n   */\n  redactPaths?: string[] | false;\n  /** 自定义替换值，默认 '[REDACTED]' */\n  redactCensor?: string;\n}\n\n/**\n * 默认敏感字段路径（pino path 语法）。\n *\n * 覆盖最常见的\"日志泄漏 token\"场景：\n * - HTTP request headers（Bearer / API key / cookie）\n * - 业务字段：password / token / secret / privateKey / idCard / cvv\n * - 嵌套通配符 `*`：自动覆盖任意层级\n */\nconst DEFAULT_REDACT_PATHS = [\n  // Header 相关\n  'req.headers.authorization',\n  'req.headers[\"x-api-key\"]',\n  'req.headers.cookie',\n  'request.headers.authorization',\n  'request.headers[\"x-api-key\"]',\n  'request.headers.cookie',\n  'headers.authorization',\n  'headers[\"x-api-key\"]',\n  'headers.cookie',\n  // 业务字段\n  '*.password',\n  '*.passwd',\n  '*.secret',\n  '*.token',\n  '*.apiKey',\n  '*.api_key',\n  '*.privateKey',\n  '*.private_key',\n  '*.idCard',\n  '*.id_card',\n  '*.cvv',\n  '*.pin',\n  // 顶层（pino 不会递归 *.path 到顶层）\n  'password',\n  'token',\n  'secret',\n  'apiKey',\n  'privateKey',\n];\n\n/**\n * 把 pino-like 对象适配为 OmniAPI Logger 接口。\n */\nfunction adaptPino(p: PinoLike): Logger {\n  const wrap = (level: 'trace' | 'debug' | 'info' | 'warn' | 'error'): Logger['debug'] => {\n    return (msg, meta) => {\n      if (meta) p[level](meta, msg);\n      else p[level]({}, msg);\n    };\n  };\n  return {\n    debug: wrap('debug'),\n    info: wrap('info'),\n    warn: wrap('warn'),\n    error: wrap('error'),\n    child: (extra) => adaptPino(p.child(extra)),\n  };\n}\n\n/**\n * 创建结构化 Logger。\n *\n * - 优先级：options.pino > 动态加载 pino > consoleLogger fallback\n * - 异步加载 pino（peer-optional）；为了让构造同步可用，提供了同步 fallback\n *\n * 业务通常这样用：\n *   const logger = await createLogger({ level: 'info', bindings: { service: 'orders' } });\n */\nexport async function createLogger(options: CreateLoggerOptions = {}): Promise<Logger> {\n  const { level = 'info', bindings = {}, pino: pinoInstance, redactPaths, redactCensor = '[REDACTED]' } = options;\n\n  // 1) 显式注入\n  if (pinoInstance) return adaptPino(pinoInstance);\n\n  // 2) 动态加载 pino\n  const mod = await tryRequire<{ default: (opts?: unknown) => PinoLike } | { (opts?: unknown): PinoLike }>('pino');\n  if (mod) {\n    const factory =\n      (mod as { default?: (opts?: unknown) => PinoLike }).default ??\n      (mod as (opts?: unknown) => PinoLike);\n\n    // 计算最终 redact 路径\n    let finalPaths: string[] | undefined;\n    if (redactPaths === false) {\n      finalPaths = undefined;\n    } else if (Array.isArray(redactPaths)) {\n      finalPaths = [...DEFAULT_REDACT_PATHS, ...redactPaths];\n    } else {\n      finalPaths = DEFAULT_REDACT_PATHS;\n    }\n\n    const pinoOpts: Record<string, unknown> = { level, base: bindings };\n    if (finalPaths && finalPaths.length > 0) {\n      pinoOpts.redact = { paths: finalPaths, censor: redactCensor };\n    }\n\n    const instance = factory(pinoOpts);\n    return adaptPino(instance);\n  }\n\n  // 3) Fallback：consoleLogger（带 bindings）\n  return Object.keys(bindings).length > 0 ? consoleLogger.child(bindings) : consoleLogger;\n}\n","import { tryRequire } from './optional-require.js';\n\n/**\n * Span 接口（OTel API 的最小子集）—— 用最小约束避免强依赖整个 OTel 类型库。\n */\nexport interface Span {\n  setAttribute(key: string, value: string | number | boolean): void;\n  setStatus(status: { code: number; message?: string }): void;\n  recordException(err: unknown): void;\n  end(): void;\n}\n\n/**\n * Tracer 接口。\n */\nexport interface Tracer {\n  /** 创建 span 并执行 fn，正常 / 异常都会自动 end */\n  startActiveSpan<T>(name: string, attributes: Record<string, unknown>, fn: (span: Span) => Promise<T>): Promise<T>;\n}\n\n/** OTel SpanStatusCode 常量（避免引入 OTel 包） */\nconst SPAN_STATUS_OK = 1;\nconst SPAN_STATUS_ERROR = 2;\n\n/** 实现 OTel API 形态的 Tracer 适配 */\nfunction adaptOtelTracer(otelTracer: {\n  startActiveSpan: (name: string, fn: (span: Record<string, unknown>) => unknown) => unknown;\n}): Tracer {\n  return {\n    startActiveSpan: <T>(name: string, attributes: Record<string, unknown>, fn: (s: Span) => Promise<T>): Promise<T> => {\n      return new Promise<T>((resolve, reject) => {\n        otelTracer.startActiveSpan(name, async (rawSpan) => {\n          const span = rawSpan as Record<string, unknown> & {\n            setAttribute(k: string, v: unknown): void;\n            setStatus(s: { code: number; message?: string }): void;\n            recordException(e: unknown): void;\n            end(): void;\n          };\n          // 注入初始属性\n          for (const [k, v] of Object.entries(attributes)) {\n            if (v !== undefined && v !== null) span.setAttribute(k, v);\n          }\n          try {\n            const result = await fn({\n              setAttribute: (k, v) => span.setAttribute(k, v),\n              setStatus: (s) => span.setStatus(s),\n              recordException: (e) => span.recordException(e),\n              end: () => span.end(),\n            });\n            span.setStatus({ code: SPAN_STATUS_OK });\n            span.end();\n            resolve(result);\n          } catch (err) {\n            span.recordException(err);\n            span.setStatus({\n              code: SPAN_STATUS_ERROR,\n              message: err instanceof Error ? err.message : String(err),\n            });\n            span.end();\n            reject(err);\n          }\n        });\n      });\n    },\n  };\n}\n\n/** No-op Tracer：OTel 未安装时的兜底，保证业务代码不需要写 if 判断 */\nconst noopTracer: Tracer = {\n  startActiveSpan: async (_name, _attrs, fn) => {\n    return fn({\n      setAttribute: () => undefined,\n      setStatus: () => undefined,\n      recordException: () => undefined,\n      end: () => undefined,\n    });\n  },\n};\n\nexport interface CreateTracerOptions {\n  /** Tracer 名称，默认 'omni-api' */\n  name?: string;\n  /** 直接注入 OTel TracerProvider 中拿到的 tracer（高级用法） */\n  tracer?: { startActiveSpan: (name: string, fn: (s: Record<string, unknown>) => unknown) => unknown };\n}\n\n/**\n * 创建 Tracer。\n *\n * - 优先级：options.tracer > 动态加载 @opentelemetry/api > noopTracer\n * - OTel 未安装时返回 no-op，业务代码无需 if-else\n */\nexport async function createTracer(options: CreateTracerOptions = {}): Promise<Tracer> {\n  if (options.tracer) return adaptOtelTracer(options.tracer);\n\n  const otel = await tryRequire<{\n    trace: { getTracer: (name: string) => { startActiveSpan: (name: string, fn: (s: Record<string, unknown>) => unknown) => unknown } };\n  }>('@opentelemetry/api');\n\n  if (otel?.trace) {\n    // 把 OTel api 注册到全局，让 @omni-api/core 的 createTracedFetch 可以零依赖访问\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    (globalThis as any).__OMNI_OTEL_API__ = otel;\n    const tracer = otel.trace.getTracer(options.name ?? 'omni-api');\n    return adaptOtelTracer(tracer);\n  }\n\n  return noopTracer;\n}\n\nexport { noopTracer, SPAN_STATUS_OK, SPAN_STATUS_ERROR };\n","import { tryRequire } from './optional-require.js';\n\n/**\n * 一个最小的 Counter 接口（避开 prom-client 完整类型）。\n */\nexport interface Counter {\n  inc(labels?: Record<string, string | number>, value?: number): void;\n}\n\n/**\n * 一个最小的 Histogram 接口。\n */\nexport interface Histogram {\n  observe(labels: Record<string, string | number>, value: number): void;\n}\n\n/**\n * Metrics 接口：\n *   - procedureTotal: 累计调用数（按 status / source / name 维度）\n *   - procedureDuration: 调用耗时分布（histogram，秒为单位）\n *   - render(): 输出 Prometheus 文本（接 /_metrics 用）\n */\nexport interface Metrics {\n  procedureTotal: Counter;\n  procedureDuration: Histogram;\n  /** 渲染 Prometheus exposition 文本 */\n  render(): Promise<string>;\n}\n\ninterface PromClientLike {\n  Counter: new (config: { name: string; help: string; labelNames: string[]; registers?: unknown[] }) => Counter;\n  Histogram: new (config: {\n    name: string;\n    help: string;\n    labelNames: string[];\n    buckets?: number[];\n    registers?: unknown[];\n  }) => Histogram;\n  Registry: new () => { metrics(): Promise<string>; clear(): void };\n  register: { metrics(): Promise<string> };\n}\n\n/** No-op metrics（prom-client 未安装时的兜底） */\nconst noopCounter: Counter = { inc: () => undefined };\nconst noopHistogram: Histogram = { observe: () => undefined };\nconst noopMetrics: Metrics = {\n  procedureTotal: noopCounter,\n  procedureDuration: noopHistogram,\n  render: async () => '',\n};\n\nexport interface CreateMetricsOptions {\n  /** 指标名前缀，默认 'omni' */\n  prefix?: string;\n  /** Histogram 桶（秒），默认覆盖 1ms ~ 10s */\n  buckets?: number[];\n  /** 直接注入 prom-client（测试用） */\n  promClient?: PromClientLike;\n}\n\nconst DEFAULT_BUCKETS = [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];\n\n/**\n * 创建 metrics 实例。\n *\n * - prom-client 未安装则返回 no-op\n * - 装了的话，自动注册两个指标到 **新建的独立 Registry**（避免和业务原有 register 冲突）\n *   render() 输出该 Registry 的指标\n */\nexport async function createMetrics(options: CreateMetricsOptions = {}): Promise<Metrics> {\n  const prefix = options.prefix ?? 'omni';\n  const buckets = options.buckets ?? DEFAULT_BUCKETS;\n  const promClient =\n    options.promClient ?? (await tryRequire<PromClientLike>('prom-client'));\n\n  if (!promClient) return noopMetrics;\n\n  const registry = new promClient.Registry();\n  const procedureTotal = new promClient.Counter({\n    name: `${prefix}_procedure_total`,\n    help: 'Total number of procedure invocations',\n    labelNames: ['name', 'source', 'status', 'code'],\n    registers: [registry],\n  });\n  const procedureDuration = new promClient.Histogram({\n    name: `${prefix}_procedure_duration_seconds`,\n    help: 'Procedure execution duration in seconds',\n    labelNames: ['name', 'source', 'status'],\n    buckets,\n    registers: [registry],\n  });\n\n  return {\n    procedureTotal,\n    procedureDuration,\n    render: () => (registry as { metrics(): Promise<string> }).metrics(),\n  };\n}\n\nexport { noopMetrics };\n","import { OmniError, type Middleware } from '@omni-api/core';\nimport type { Logger } from '@omni-api/core';\nimport type { Metrics } from './metrics.js';\nimport type { Tracer } from './tracer.js';\n\nexport interface ObservabilityDeps {\n  logger: Logger;\n  tracer: Tracer;\n  metrics: Metrics;\n}\n\nexport interface ObservabilityOptions {\n  /** 是否在 info 级别打印每次成功调用（默认 true） */\n  logSuccess?: boolean;\n  /** 把 input 写到 log（默认 false，避免日志泄漏敏感信息） */\n  logInput?: boolean;\n  /** 把 output 写到 log（默认 false） */\n  logOutput?: boolean;\n}\n\n/**\n * 一体化可观测性中间件：自动包住 procedure 执行，产出 log + trace + metrics。\n *\n * 用法（作为全局中间件）：\n *   const deps = { logger, tracer, metrics };\n *   defineProcedure({ middleware: [observability(deps)], ... });\n *\n * 但更常见是放到 router 共享，或框架未来的 App.use 全局挂载。\n */\nexport function observability(\n  deps: ObservabilityDeps,\n  options: ObservabilityOptions = {},\n): Middleware {\n  const { logger: rootLogger, tracer, metrics } = deps;\n  const logSuccess = options.logSuccess ?? true;\n  const logInput = options.logInput ?? false;\n  const logOutput = options.logOutput ?? false;\n\n  return async (ctx, next) => {\n    const procName = ctx.procedure?.name ?? 'unknown';\n    const source = ctx.source;\n    const start = process.hrtime.bigint();\n\n    // 把 logger 切换为 child logger（带 procedure name），覆盖原 ctx.logger\n    // 这样下游中间件 / handler 打日志都自带 procedure 信息\n    const childLogger = rootLogger.child({ procedure: procName, source, requestId: ctx.requestId });\n    (ctx as { logger: Logger }).logger = childLogger;\n\n    return tracer.startActiveSpan(\n      `procedure ${procName}`,\n      {\n        'omni.procedure.name': procName,\n        'omni.source': source,\n        'omni.request_id': ctx.requestId,\n        'omni.user_id': ctx.user?.id ?? '',\n      },\n      async (span) => {\n        try {\n          if (logInput) {\n            childLogger.debug('procedure.start', { procedure: procName });\n          }\n\n          const result = await next();\n          const durationSec = Number(process.hrtime.bigint() - start) / 1e9;\n\n          metrics.procedureDuration.observe(\n            { name: procName, source, status: 'success' },\n            durationSec,\n          );\n          metrics.procedureTotal.inc({ name: procName, source, status: 'success', code: 'OK' });\n\n          span.setAttribute('omni.duration_ms', Math.round(durationSec * 1000));\n\n          if (logSuccess) {\n            childLogger.info('procedure.success', {\n              durationMs: Math.round(durationSec * 1000),\n              ...(logOutput ? { output: safeStringify(result) } : {}),\n            });\n          }\n\n          return result;\n        } catch (err) {\n          const durationSec = Number(process.hrtime.bigint() - start) / 1e9;\n          const code = err instanceof OmniError ? err.code : 'INTERNAL';\n          const status = err instanceof OmniError && err.status < 500 ? 'client_error' : 'server_error';\n\n          metrics.procedureDuration.observe({ name: procName, source, status }, durationSec);\n          metrics.procedureTotal.inc({ name: procName, source, status, code });\n\n          span.setAttribute('omni.error.code', code);\n          span.setAttribute('omni.duration_ms', Math.round(durationSec * 1000));\n\n          // 5xx / 非 OmniError 走 error；4xx 走 warn（业务可预期）\n          const isClientError = err instanceof OmniError && err.status < 500;\n          const logger = isClientError ? childLogger.warn : childLogger.error;\n          logger.call(childLogger, 'procedure.failure', {\n            code,\n            durationMs: Math.round(durationSec * 1000),\n            errorMessage: err instanceof Error ? err.message : String(err),\n          });\n\n          throw err;\n        }\n      },\n    );\n  };\n}\n\n/** 序列化但限制大小，防止巨大对象写满日志 */\nfunction safeStringify(value: unknown, maxBytes = 4096): string {\n  try {\n    const s = JSON.stringify(value);\n    if (s.length <= maxBytes) return s;\n    return s.slice(0, maxBytes) + '...[truncated]';\n  } catch {\n    return '[unserializable]';\n  }\n}\n","import { createLogger, type CreateLoggerOptions } from './logger.js';\nimport { createTracer, type CreateTracerOptions } from './tracer.js';\nimport { createMetrics, type CreateMetricsOptions } from './metrics.js';\nimport { observability, type ObservabilityDeps, type ObservabilityOptions } from './middleware.js';\nimport type { Middleware } from '@omni-api/core';\n\nexport interface ObservabilityFactoryOptions {\n  logger?: CreateLoggerOptions;\n  tracer?: CreateTracerOptions;\n  metrics?: CreateMetricsOptions;\n  middleware?: ObservabilityOptions;\n}\n\nexport interface ObservabilityFactory extends ObservabilityDeps {\n  /** 一体化中间件：放进 procedure.middleware 即生效 */\n  middleware: Middleware;\n}\n\n/**\n * 一站式工厂：创建好 logger / tracer / metrics 三件套，并产出对应中间件。\n *\n * 三个子模块都是 peer-optional：\n *   - 装了 pino → 走 pino；否则走 consoleLogger\n *   - 装了 @opentelemetry/api → 走 OTel；否则 no-op\n *   - 装了 prom-client → 走 prom；否则 no-op，render() 返回空字符串\n *\n * 用法：\n *   const obs = await createObservability({\n *     logger: { level: 'info', bindings: { service: 'orders' } },\n *     metrics: { prefix: 'myapp' },\n *   });\n *   defineProcedure({ middleware: [obs.middleware], ... });\n *\n *   // HTTP 暴露 /metrics\n *   app.get('/_metrics', async (req, reply) => {\n *     reply.header('content-type', 'text/plain; version=0.0.4');\n *     return obs.metrics.render();\n *   });\n */\nexport async function createObservability(\n  options: ObservabilityFactoryOptions = {},\n): Promise<ObservabilityFactory> {\n  const [logger, tracer, metrics] = await Promise.all([\n    createLogger(options.logger),\n    createTracer(options.tracer),\n    createMetrics(options.metrics),\n  ]);\n\n  const deps: ObservabilityDeps = { logger, tracer, metrics };\n  const middleware = observability(deps, options.middleware);\n\n  return { ...deps, middleware };\n}\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@omni-api/plugin-observability",
+  "version": "0.0.1",
+  "description": "Observability for OmniAPI: structured logger + OTel tracing + Prometheus metrics. All optional, all pluggable.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo coverage"
+  },
+  "dependencies": {
+    "@omni-api/core": "workspace:*"
+  },
+  "peerDependencies": {
+    "pino": "^9.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "prom-client": "^15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pino": { "optional": true },
+    "@opentelemetry/api": { "optional": true },
+    "prom-client": { "optional": true }
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "zod": "^3.23.8",
+    "@types/node": "^22.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}