@0xchain/telemetry 1.1.0-beta.9 → 1.1.0-beta.91

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

@@ -10,6 +10,8 @@
 pnpm add @0xchain/telemetry
 ```
 
+**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`，只需一行代码即可启用：
@@ -110,6 +112,14 @@ export const config = {
 5. **入口拆分**：`instrumentation` 含完整 Node SDK；`middleware` / `next` 轻量，仅注入请求头，适合 Edge。
 6. **按需加载**：仅启用 HTTP + Undici 检测，减少冷启动与内存占用。
 
+## 常见问题
+
+### 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)

package/dist/Instrumentations.d.ts.map

@@ -1 +1 @@
-{"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,mDAoElE"}
+{"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.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,EAAY,UAAU,EAAoC,MAAM,oBAAoB,CAAC;AAC5F,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;AAEF,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B,GAAI,UAAU,YAAY,KAAG,YAAwB,CAAC;AAE/F,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;AAsCzD,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,YAAY,CAItD,CAAC;AAcF,iBAAiB;AACjB,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,EAAE,UAAU,MAAM,YAmBxE,CAAC;AAsBF,+BAA+B;AAC/B,eAAO,MAAM,mBAAmB,GAAI,SAAS,YAAY,gBAJT,MAAM,WAAW,MAAM,KAAK,OAsC3E,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,8 +1,8 @@
 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, };
+export { buildSamplingContextFromAttributes, matchSamplingRule, resolveSamplingRatio, createIgnoreMatcher, createSpanNameMatcher, defaultIgnoreConfig, };
 /** 从环境变量加载 Telemetry 配置（异步读取配置文件，不阻塞主线程） */
 export declare const loadTelemetryConfigFromEnv: (env?: NodeJS.ProcessEnv) => Promise<Partial<TelemetryConfig>>;
 /** 合并环境变量与显式配置得到最终配置 */

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,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;AAwDF,2BAA2B;AAC3B,eAAO,MAAM,cAAc,GAAU,SAAS,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,8BA+CvF,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"}