@0xchain/telemetry 1.1.0-beta.8 → 1.1.0-beta.80

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present 0xchain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,134 +4,144 @@
 
 ## 快速开始
 
-安装依赖：
+### 1. 安装依赖
 
 ```bash
 pnpm add @0xchain/telemetry
 ```
 
-Next.js App Router 接入：
+**Monorepo 内使用**：在应用包的 `package.json` 中添加 `"@0xchain/telemetry": "workspace:*"`，然后执行 `pnpm install`。使用前需先构建 telemetry 包：`pnpm nx run telemetry:build` 或 `cd packages/telemetry && pnpm exec vite build`。
+
+### 2. 初始化追踪 (instrumentation.ts)
+
+在项目根目录（或 `src` 目录）创建 `instrumentation.ts`，只需一行代码即可启用：
+
+> 注意：请从 `@0xchain/telemetry/instrumentation` 导入。此入口包含完整 Node SDK，仅在 `instrumentation.ts` 中加载，不影响 Edge 的 middleware bundle。
 
 ```ts
-import { registerTelemetry } from "@0xchain/telemetry/next";
+import { registerTelemetry } from "@0xchain/telemetry/instrumentation";
 
 export async function register() {
-  await registerTelemetry(() => ({
-    serviceName: "web-app",
-    environment: "production",
-    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
-    headers: {
-      Authorization: process.env.OTEL_EXPORTER_OTLP_HEADERS || "",
-    },
-    samplingRules: [
-      { name: "inspection", ratio: 1, when: { inspection: true } },
-      { name: "errors", ratio: 0.8, when: { minStatusCode: 500 } },
-      { name: "default", ratio: 0.1 },
-    ],
-  }));
+  // 自动从环境变量加载配置
+  await registerTelemetry();
 }
 ```
 
-`middleware.ts` 中启用请求上下文写入：
+或者自定义配置：
 
 ```ts
-import { createTelemetryMiddleware, defaultTelemetryMiddlewareConfig } from "@0xchain/telemetry/next";
+import { registerTelemetry } from "@0xchain/telemetry/instrumentation";
 
-export const config = defaultTelemetryMiddlewareConfig;
-export default createTelemetryMiddleware({
-  ignore: {
-    paths: ["/health", "/metrics"],
-    extensions: [".png", ".css"],
-  },
-});
+export async function register() {
+  await registerTelemetry({
+    serviceName: "my-web-app",
+    environment: "production",
+    // 更多配置...
+  });
+}
 ```
 
-## API 说明
+### 3. 注入中间件 (middleware.ts)
 
-### 核心入口
+在 `middleware.ts` 中使用 `withTelemetryMiddleware` 包裹现有中间件，实现低侵入式集成：
 
-- `registerTelemetry(configOrProvider)`：用于 `instrumentation.ts` 中初始化 OpenTelemetry。
-- `createTelemetryMiddleware(options)`：用于 `middleware.ts` 注入请求头与用户类型标记。
-- `startTelemetry(config)`：在 Node 环境中直接启动 SDK。
-- `updateTelemetryConfig(partial)`：运行时更新采样、忽略规则等配置。
-- `shutdownTelemetry()`：停止追踪 SDK。
+> 注意：请从 `@0xchain/telemetry/middleware` 或 `@0xchain/telemetry/next` 导入。此入口轻量，无 Node SDK 依赖，适用于 Edge Runtime。
 
-### 配置类型
+```ts
+import { NextResponse } from "next/server";
+import { withTelemetryMiddleware } from "@0xchain/telemetry/middleware";
+
+// 你的现有中间件逻辑
+const userMiddleware = async (req) => {
+  // ... 业务逻辑
+  return NextResponse.next();
+};
+
+// 使用 withTelemetryMiddleware 包裹
+export const middleware = withTelemetryMiddleware(userMiddleware);
+
+export const config = {
+  matcher: [
+    /* 你的 matcher 配置 */
+    '/((?!_next/static|_next/image|favicon.ico).*)',
+  ],
+};
+```
 
-`TelemetryConfig` 关键字段：
+如果你没有其他中间件，可以使用工厂方法：
 
-- `serviceName`：服务名称
-- `environment`：环境标识
-- `defaultSamplingRatio`：默认采样比例
-- `samplingRules`：多维采样规则
-- `ignore`：忽略规则
-- `inspectionHeader`：巡检标记请求头
-- `userTypeHeader`：用户类型请求头
-- `requestStartHeader`：请求开始时间请求头
+```ts
+import { createTelemetryMiddleware } from "@0xchain/telemetry/middleware";
 
-### 采样规则
+export const middleware = createTelemetryMiddleware();
 
-```json
-[
-  {
-    "name": "inspection",
-    "ratio": 1,
-    "when": { "inspection": true }
-  },
-  {
-    "name": "error",
-    "ratio": 0.8,
-    "when": { "minStatusCode": 500 }
-  },
-  {
-    "name": "api",
-    "ratio": 0.2,
-    "when": { "path": ["/api/**"], "method": ["POST"] }
-  }
-]
+export const config = {
+  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+};
 ```
 
-### 忽略规则
+## 环境变量配置
 
-```json
-{
-  "paths": ["/health", "/metrics", "/_next/**"],
-  "extensions": [".png", ".css", ".js"],
-  "methods": ["HEAD", "OPTIONS"]
-}
-```
+支持通过环境变量实现零代码配置：
 
-## 环境变量
+| 变量名 | 描述 | 默认值 |
+|---|---|---|
+| `OTEL_SERVICE_NAME` | 服务名称 | `unknown-service` |
+| `OTEL_SERVICE_VERSION` | 服务版本 | `1.0.0` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 上报地址 | - |
+| `OTEL_EXPORTER_OTLP_HEADERS` | OTLP Headers (k=v,k2=v2) | - |
+| `TELEMETRY_ENVIRONMENT` | 环境名称 (dev/prod) | `development`，在 Vercel 上自动使用 `VERCEL_ENV` |
+| `TELEMETRY_SAMPLING_RATIO` | 默认采样率 (0.0-1.0) | `0.01` |
+| `TELEMETRY_IGNORE_PATHS` | 忽略路径 (逗号分隔) | 默认忽略静态资源 |
+| `TELEMETRY_INSPECTION_HEADER` | 巡检请求头 | `x-inspection` |
+| `TELEMETRY_CONFIG_FILE` | 配置文件路径，支持 JSON，异步读取不阻塞启动 | - |
 
-- `TELEMETRY_CONFIG_FILE`：JSON 配置文件路径
-- `TELEMETRY_SAMPLING_RATIO`：默认采样比例
-- `TELEMETRY_SAMPLING_RULES`：采样规则 JSON 字符串
-- `TELEMETRY_IGNORE_PATHS`：逗号分隔的忽略路径
-- `TELEMETRY_IGNORE_EXTENSIONS`：逗号分隔的忽略扩展名
-- `TELEMETRY_IGNORE_METHODS`：逗号分隔的忽略方法
-- `TELEMETRY_INSPECTION_HEADER`：巡检请求头
-- `TELEMETRY_USER_TYPE_HEADER`：用户类型请求头
-- `TELEMETRY_REQUEST_START_HEADER`：请求开始时间请求头
-- `OTEL_EXPORTER_OTLP_ENDPOINT`：OTLP endpoint
-- `OTEL_EXPORTER_OTLP_HEADERS`：OTLP headers
-- `OTEL_SERVICE_NAME`：服务名称
+## Vercel 集成
 
-## 部署说明
+部署到 Vercel 时，将自动检测并注入以下 resource 属性：
 
-1. 配置 OTLP endpoint 与 headers。
-2. 在 `instrumentation.ts` 中调用 `registerTelemetry`。
-3. 在 `middleware.ts` 中加入 `createTelemetryMiddleware`。
-4. 确认生产环境可访问 APM 的 OTLP 接收端。
+- `vercel.region`、`vercel.runtime`、`vercel.sha`、`vercel.host`、`vercel.deployment_id`
+- `environment` 优先使用 `VERCEL_ENV`（production / preview / development）
 
-## 迁移指南
+## 核心特性
 
-- 旧 `startTelemetry` 初始化方式可直接替换为 `registerTelemetry`，配置项保持一致。
-- `ignorePaths` 替换为 `ignore` 配置对象以便使用扩展名与方法过滤。
-- 原巡检逻辑继续使用 `x-inspection` 请求头，默认保持兼容。
+1. **巡检识别**：自动识别 `x-inspection` 请求头，强制采样并全量记录。
+2. **智能过滤**：内置静态资源过滤规则，支持自定义路径、扩展名和方法过滤。
+3. **多维采样**：支持按路径、用户类型、状态码配置不同的采样率。
+4. **低侵入性**：通过 HOC 方式集成中间件，不破坏原有逻辑。
+5. **入口拆分**：`instrumentation` 含完整 Node SDK；`middleware` / `next` 轻量，仅注入请求头，适合 Edge。
+6. **按需加载**：仅启用 HTTP + Undici 检测，减少冷启动与内存占用。
 
-## 构建与测试
+## 常见问题
 
-```bash
-pnpm nx build @0xchain/telemetry
-pnpm nx test @0xchain/telemetry
+### Module not found: Can't resolve '@0xchain/telemetry/instrumentation'
+
+1. **确认依赖**：确保应用 `package.json` 中有 `@0xchain/telemetry` 依赖。
+2. **确认构建**：telemetry 包需先构建，`dist/` 目录需存在。在 monorepo 根目录执行 `pnpm nx run telemetry:build`。
+3. **Next.js 配置**：若仍有问题，可在 `next.config.js` 中添加 `transpilePackages: ['@0xchain/telemetry']`。
+
+## 高级配置
+
+### 采样规则配置 (Sampling Rules)
+
+可以通过 `samplingRules` 字段或 `TELEMETRY_SAMPLING_RULES` 环境变量（JSON 字符串）配置：
+
+```json
+[
+  {
+    "name": "critical-api",
+    "ratio": 1.0,
+    "when": { "path": ["/api/checkout", "/api/payment"] }
+  },
+  {
+    "name": "errors",
+    "ratio": 1.0,
+    "when": { "minStatusCode": 500 }
+  },
+  {
+    "name": "guest-users",
+    "ratio": 0.05,
+    "when": { "userType": ["guest"] }
+  }
+]
 ```

package/dist/Instrumentations.d.ts

@@ -1,4 +1,6 @@
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';
 import { TelemetryConfig } from './types';
-/** 生成 OpenTelemetry 自动检测配置 */
-export default function getInstrumentations(config: TelemetryConfig): any;
+/** 按需加载 HTTP + Undici 检测，避免全量 auto-instrumentations 的启动开销 */
+export default function getInstrumentations(config: TelemetryConfig): (HttpInstrumentation | UndiciInstrumentation)[];
 //# sourceMappingURL=Instrumentations.d.ts.map

package/dist/Instrumentations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Instrumentations.d.ts","sourceRoot":"","sources":["../src/Instrumentations.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA4B/C,8BAA8B;AAC9B,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,GAAG,CA0ExE"}
+{"version":3,"file":"Instrumentations.d.ts","sourceRoot":"","sources":["../src/Instrumentations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA4B/C,6DAA6D;AAC7D,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,MAAM,EAAE,eAAe,mDA2ElE"}

package/dist/Sampler.d.ts

@@ -16,7 +16,7 @@ export declare const matchSamplingRule: (rule: SamplingRule, context: SamplingCo
 export declare const resolveSamplingRatio: (rules: SamplingRule[] | undefined, context: SamplingContext, defaultRatio: number) => number;
 /** 创建基于规则的采样器 */
 export declare const createRuleBasedSampler: (runtime: TelemetryRuntime) => Sampler;
-/** 构建带采样过滤的导出器 */
-export declare const createFilteringTraceExporter: (exporter: SpanExporter, runtime: TelemetryRuntime) => SpanExporter;
+/** 导出器直接透传，采样决策由 createRuleBasedSampler 在 span 创建时统一完成，避免 export 阶段重复计算 */
+export declare const createFilteringTraceExporter: (exporter: SpanExporter) => SpanExporter;
 export default createRuleBasedSampler;
 //# sourceMappingURL=Sampler.d.ts.map

package/dist/Sampler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sampler.d.ts","sourceRoot":"","sources":["../src/Sampler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAIP,YAAY,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,UAAU,EAMX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAoCD,iCAAiC;AACjC,eAAO,MAAM,kCAAkC,GAAI,YAAY,UAAU,KAAG,eA4B3E,CAAC;AAcF,iBAAiB;AACjB,eAAO,MAAM,iBAAiB,GAAI,MAAM,YAAY,EAAE,SAAS,eAAe,YAiC7E,CAAC;AAKF,iBAAiB;AACjB,eAAO,MAAM,oBAAoB,GAC/B,OAAO,YAAY,EAAE,GAAG,SAAS,EACjC,SAAS,eAAe,EACxB,cAAc,MAAM,WASrB,CAAC;AAoBF,iBAAiB;AACjB,eAAO,MAAM,sBAAsB,GAAI,SAAS,gBAAgB,KAAG,OAyBlE,CAAC;AAwBF,kBAAkB;AAClB,eAAO,MAAM,4BAA4B,GAAI,UAAU,YAAY,EAAE,SAAS,gBAAgB,KAAG,YAehG,CAAC;AAEF,eAAe,sBAAsB,CAAC"}
+{"version":3,"file":"Sampler.d.ts","sourceRoot":"","sources":["../src/Sampler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EAIP,YAAY,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAY,UAAU,EAAoC,MAAM,oBAAoB,CAAC;AAC5F,OAAO,KAAK,EAAgB,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG5E,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAoCD,iCAAiC;AACjC,eAAO,MAAM,kCAAkC,GAAI,YAAY,UAAU,KAAG,eA4B3E,CAAC;AAcF,iBAAiB;AACjB,eAAO,MAAM,iBAAiB,GAAI,MAAM,YAAY,EAAE,SAAS,eAAe,YAiC7E,CAAC;AAKF,iBAAiB;AACjB,eAAO,MAAM,oBAAoB,GAC/B,OAAO,YAAY,EAAE,GAAG,SAAS,EACjC,SAAS,eAAe,EACxB,cAAc,MAAM,WASrB,CAAC;AAgCF,iBAAiB;AACjB,eAAO,MAAM,sBAAsB,GAAI,SAAS,gBAAgB,KAAG,OA6ClE,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B,GAAI,UAAU,YAAY,KAAG,YAAwB,CAAC;AAE/F,eAAe,sBAAsB,CAAC"}

package/dist/ignore-BvHZTNsF.js

@@ -0,0 +1,151 @@
+const defaultIgnorePaths = [
+  // 健康检查 & 监控
+  "/health",
+  "/api/health",
+  "/metrics",
+  "/api/metrics",
+  "/readyz",
+  "/livez",
+  "/monitoring",
+  // Next.js 内部路由
+  "/_next",
+  "/__nextjs_",
+  // Next.js App Router 元数据路由
+  "/opengraph-image",
+  "/twitter-image",
+  "/icon",
+  "/apple-icon",
+  // Vercel 内部路由
+  "/_vercel",
+  // 静态资源 & SEO
+  "/favicon.ico",
+  "/robots.txt",
+  "/sitemap.xml",
+  "/manifest.json",
+  "/manifest.webmanifest",
+  "/.well-known",
+  // 认证回调（NextAuth.js）
+  "/api/auth"
+];
+const defaultIgnoreSpanNames = [
+  // Next.js 内部服务端操作（非 HTTP 请求，由 Next.js OTel 自动产生）
+  /^NextNodeServer\./,
+  /^NextServer\./,
+  /^BaseServer\./,
+  /^AppRender\./,
+  /^AppRouteRouteHandlers\./,
+  // Next.js 中间件执行 span（如 "middleware GET /path"）
+  /^middleware /i,
+  // Next.js 元数据解析
+  /^resolveMetadata$/,
+  /^generateMetadata$/
+];
+const defaultIgnoreExtensions = [
+  ".css",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".svg",
+  ".ico",
+  ".webp",
+  ".avif",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".map",
+  ".txt",
+  ".xml"
+];
+const defaultIgnoreConfig = {
+  paths: defaultIgnorePaths,
+  extensions: defaultIgnoreExtensions,
+  methods: ["HEAD", "OPTIONS"],
+  spanNames: defaultIgnoreSpanNames
+};
+const normalizeExtensions = (extensions) => {
+  return extensions.map((ext) => {
+    const normalized = ext.trim().toLowerCase();
+    if (!normalized) return normalized;
+    return normalized.startsWith(".") ? normalized : `.${normalized}`;
+  });
+};
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const matchesPathPattern = (pattern, pathname) => {
+  if (pattern instanceof RegExp) {
+    return pattern.test(pathname);
+  }
+  const normalized = pattern.trim();
+  if (!normalized) return false;
+  const hasGlob = normalized.includes("*");
+  if (hasGlob) {
+    const escaped = escapeRegex(normalized);
+    const regexSource = `^${escaped.replace(/\\\*\\\*/g, ".*").replace(/\\\*/g, "[^/]*")}$`;
+    return new RegExp(regexSource).test(pathname);
+  }
+  if (pathname === normalized) return true;
+  if (normalized.endsWith("/")) {
+    return pathname.startsWith(normalized);
+  }
+  return pathname.startsWith(`${normalized}/`) || pathname.startsWith(normalized);
+};
+const hasIgnoredExtension = (extensions, pathname) => {
+  const lower = pathname.toLowerCase();
+  return extensions.some((ext) => ext && lower.endsWith(ext));
+};
+const getCacheKey = (config) => {
+  if (!config) return "default";
+  const hasRegExp = config.paths?.some((p) => p instanceof RegExp);
+  if (hasRegExp) return null;
+  const paths = (config.paths ?? []).map(String).sort().join(",");
+  const extensions = (config.extensions ?? []).map((e) => e.toLowerCase()).sort().join(",");
+  const methods = (config.methods ?? []).map((m) => m.toUpperCase()).sort().join(",");
+  return `p:${paths}|e:${extensions}|m:${methods}`;
+};
+const matcherCache = /* @__PURE__ */ new Map();
+const CACHE_MAX_SIZE = 16;
+const createSpanNameMatcher = (config) => {
+  const patterns = config?.spanNames?.length ? config.spanNames : defaultIgnoreConfig.spanNames;
+  return (spanName) => {
+    if (!spanName || !patterns.length) return false;
+    return patterns.some((pattern) => matchesPathPattern(pattern, spanName));
+  };
+};
+const createIgnoreMatcher = (config) => {
+  const cacheKey = getCacheKey(config);
+  if (cacheKey) {
+    const cached = matcherCache.get(cacheKey);
+    if (cached) return cached;
+  }
+  const paths = config?.paths?.length ? config.paths : defaultIgnoreConfig.paths;
+  const extensions = config?.extensions?.length ? normalizeExtensions(config.extensions) : defaultIgnoreConfig.extensions;
+  const methods = config?.methods?.length ? config.methods.map((method) => method.toUpperCase()) : defaultIgnoreConfig.methods;
+  const matcher = (pathname, method) => {
+    if (method && methods.includes(method.toUpperCase())) {
+      return true;
+    }
+    if (!pathname) return false;
+    if (hasIgnoredExtension(extensions, pathname)) {
+      return true;
+    }
+    return paths.some((pattern) => matchesPathPattern(pattern, pathname));
+  };
+  if (cacheKey) {
+    if (matcherCache.size >= CACHE_MAX_SIZE) {
+      const firstKey = matcherCache.keys().next().value;
+      if (firstKey) matcherCache.delete(firstKey);
+    }
+    matcherCache.set(cacheKey, matcher);
+  }
+  return matcher;
+};
+export {
+  createSpanNameMatcher as a,
+  createIgnoreMatcher as c,
+  defaultIgnoreConfig as d,
+  matchesPathPattern as m
+};

package/dist/ignore.d.ts

@@ -2,6 +2,8 @@ import { IgnoreConfig, PathPattern } from './types';
 export declare const defaultIgnoreConfig: Required<IgnoreConfig>;
 /** 判断路径是否匹配规则 */
 export declare const matchesPathPattern: (pattern: PathPattern, pathname: string) => boolean;
-/** 创建忽略规则匹配器 */
+/** 创建 span 名称忽略匹配器 */
+export declare const createSpanNameMatcher: (config?: IgnoreConfig) => (spanName: string) => boolean;
+/** 创建忽略规则匹配器（相同配置复用，减少重复创建） */
 export declare const createIgnoreMatcher: (config?: IgnoreConfig) => (pathname: string, method?: string) => boolean;
 //# sourceMappingURL=ignore.d.ts.map

package/dist/ignore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ignore.d.ts","sourceRoot":"","sources":["../src/ignore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAqCzD,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,YAAY,CAItD,CAAC;AAcF,iBAAiB;AACjB,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,EAAE,UAAU,MAAM,YAmBxE,CAAC;AAQF,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,GAAI,SAAS,YAAY,MAS/C,UAAU,MAAM,EAAE,SAAS,MAAM,YAU1C,CAAC"}
+{"version":3,"file":"ignore.d.ts","sourceRoot":"","sources":["../src/ignore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAyEzD,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,YAAY,CAKtD,CAAC;AAcF,iBAAiB;AACjB,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,EAAE,UAAU,MAAM,YAmBxE,CAAC;AAsBF,sBAAsB;AACtB,eAAO,MAAM,qBAAqB,GAAI,SAAS,YAAY,MAKjD,UAAU,MAAM,YAIzB,CAAC;AAEF,+BAA+B;AAC/B,eAAO,MAAM,mBAAmB,GAAI,SAAS,YAAY,gBAhBT,MAAM,WAAW,MAAM,KAAK,OAkD3E,CAAC"}

package/dist/index.d.ts

@@ -1,17 +1,16 @@
 import { buildSamplingContextFromAttributes, matchSamplingRule, resolveSamplingRatio } from './Sampler';
-import { createIgnoreMatcher, defaultIgnoreConfig } from './ignore';
+import { createIgnoreMatcher, createSpanNameMatcher, defaultIgnoreConfig } from './ignore';
 import { TelemetryConfig, TelemetryRuntime } from './types';
 export * from './types';
-export { buildSamplingContextFromAttributes, matchSamplingRule, resolveSamplingRatio, createIgnoreMatcher, defaultIgnoreConfig, };
-/** 从环境变量加载 Telemetry 配置 */
-/** 从环境变量加载 Telemetry 配置 */
-export declare const loadTelemetryConfigFromEnv: (env?: NodeJS.ProcessEnv) => Partial<TelemetryConfig>;
+export { buildSamplingContextFromAttributes, matchSamplingRule, resolveSamplingRatio, createIgnoreMatcher, createSpanNameMatcher, defaultIgnoreConfig, };
+/** 从环境变量加载 Telemetry 配置（异步读取配置文件，不阻塞主线程） */
+export declare const loadTelemetryConfigFromEnv: (env?: NodeJS.ProcessEnv) => Promise<Partial<TelemetryConfig>>;
 /** 合并环境变量与显式配置得到最终配置 */
-export declare const resolveTelemetryConfig: (options?: Partial<TelemetryConfig>, env?: NodeJS.ProcessEnv) => TelemetryConfig;
+export declare const resolveTelemetryConfig: (options?: Partial<TelemetryConfig>, env?: NodeJS.ProcessEnv) => Promise<TelemetryConfig>;
 /** 创建可运行时更新的配置容器 */
-export declare const createTelemetryRuntime: (initialConfig: TelemetryConfig) => TelemetryRuntime;
+export declare const createTelemetryRuntime: (initialConfig: Partial<TelemetryConfig>) => Promise<TelemetryRuntime>;
 /** 启动 OpenTelemetry SDK */
-export declare const startTelemetry: (options: TelemetryConfig) => Promise<TelemetryRuntime>;
+export declare const startTelemetry: (options: Partial<TelemetryConfig> | TelemetryConfig) => Promise<TelemetryRuntime>;
 /** 运行时更新 Telemetry 配置 */
 export declare const updateTelemetryConfig: (partial: Partial<TelemetryConfig>) => void;
 /** 注入 traceparent 等传播头 */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,kCAAkC,EAGlC,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpE,OAAO,KAAK,EAIV,eAAe,EACf,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,kCAAkC,EAClC,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,GACpB,CAAC;AA4EF,2BAA2B;AAC3B,2BAA2B;AAC3B,eAAO,MAAM,0BAA0B,GACrC,MAAK,MAAM,CAAC,UAAwB,KACnC,OAAO,CAAC,eAAe,CAuCzB,CAAC;AAoEF,wBAAwB;AACxB,eAAO,MAAM,sBAAsB,GACjC,UAAS,OAAO,CAAC,eAAe,CAAM,EACtC,MAAK,MAAM,CAAC,UAAwB,KACnC,eA4BF,CAAC;AAEF,oBAAoB;AACpB,eAAO,MAAM,sBAAsB,GAAI,eAAe,eAAe,KAAG,gBAYvE,CAAC;AAwDF,2BAA2B;AAC3B,eAAO,MAAM,cAAc,GAAU,SAAS,eAAe,8BAqC5D,CAAC;AAEF,yBAAyB;AACzB,eAAO,MAAM,qBAAqB,GAAI,SAAS,OAAO,CAAC,eAAe,CAAC,SAEtE,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,2BAGjE,CAAC;AAEF,gCAAgC;AAChC,eAAO,MAAM,sBAAsB,GAAI,YAAW,OAAO,KAAa,MACtD,OAAO,WAAW,GAAG,GAAG,EAAE,OAAO,WAAW,sBAY3D,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,iBAAiB,qBAI7B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,kCAAkC,EAGlC,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC3F,OAAO,KAAK,EAIV,eAAe,EACf,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB,cAAc,SAAS,CAAC;AACxB,OAAO,EACL,kCAAkC,EAClC,iBAAiB,EACjB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,GACpB,CAAC;AA8EF,4CAA4C;AAC5C,eAAO,MAAM,0BAA0B,GACrC,MAAK,MAAM,CAAC,UAAwB,KACnC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAuClC,CAAC;AAiGF,wBAAwB;AACxB,eAAO,MAAM,sBAAsB,GACjC,UAAS,OAAO,CAAC,eAAe,CAAM,EACtC,MAAK,MAAM,CAAC,UAAwB,KACnC,OAAO,CAAC,eAAe,CAGzB,CAAC;AAEF,oBAAoB;AACpB,eAAO,MAAM,sBAAsB,GACjC,eAAe,OAAO,CAAC,eAAe,CAAC,KACtC,OAAO,CAAC,gBAAgB,CAY1B,CAAC;AAuHF,2BAA2B;AAC3B,eAAO,MAAM,cAAc,GAAU,SAAS,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,8BAgDvF,CAAC;AAEF,yBAAyB;AACzB,eAAO,MAAM,qBAAqB,GAAI,SAAS,OAAO,CAAC,eAAe,CAAC,SAEtE,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,2BAGjE,CAAC;AAEF,gCAAgC;AAChC,eAAO,MAAM,sBAAsB,GAAI,YAAW,OAAO,KAAa,MACtD,OAAO,WAAW,GAAG,GAAG,EAAE,OAAO,WAAW,sBAY3D,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,iBAAiB,qBAI7B,CAAC"}