@0xchain/telemetry 1.1.0-beta.2 → 1.1.0-beta.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-present 0xchain
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,11 +1,147 @@
1
1
  # telemetry
2
2
 
3
- This library was generated with [Nx](https://nx.dev).
3
+ 面向 Next.js 16 App Router 的链路追踪方案,提供巡检识别、请求过滤与多维采样能力,基于 OpenTelemetry 输出。
4
4
 
5
- ## Building
5
+ ## 快速开始
6
6
 
7
- Run `nx build telemetry` to build the library.
7
+ ### 1. 安装依赖
8
8
 
9
- ## Running unit tests
9
+ ```bash
10
+ pnpm add @0xchain/telemetry
11
+ ```
10
12
 
11
- Run `nx test telemetry` to execute the unit tests via [Vitest](https://vitest.dev/).
13
+ **Monorepo 内使用**:在应用包的 `package.json` 中添加 `"@0xchain/telemetry": "workspace:*"`,然后执行 `pnpm install`。使用前需先构建 telemetry 包:`pnpm nx run telemetry:build` `cd packages/telemetry && pnpm exec vite build`。
14
+
15
+ ### 2. 初始化追踪 (instrumentation.ts)
16
+
17
+ 在项目根目录(或 `src` 目录)创建 `instrumentation.ts`,只需一行代码即可启用:
18
+
19
+ > 注意:请从 `@0xchain/telemetry/instrumentation` 导入。此入口包含完整 Node SDK,仅在 `instrumentation.ts` 中加载,不影响 Edge 的 middleware bundle。
20
+
21
+ ```ts
22
+ import { registerTelemetry } from "@0xchain/telemetry/instrumentation";
23
+
24
+ export async function register() {
25
+ // 自动从环境变量加载配置
26
+ await registerTelemetry();
27
+ }
28
+ ```
29
+
30
+ 或者自定义配置:
31
+
32
+ ```ts
33
+ import { registerTelemetry } from "@0xchain/telemetry/instrumentation";
34
+
35
+ export async function register() {
36
+ await registerTelemetry({
37
+ serviceName: "my-web-app",
38
+ environment: "production",
39
+ // 更多配置...
40
+ });
41
+ }
42
+ ```
43
+
44
+ ### 3. 注入中间件 (middleware.ts)
45
+
46
+ 在 `middleware.ts` 中使用 `withTelemetryMiddleware` 包裹现有中间件,实现低侵入式集成:
47
+
48
+ > 注意:请从 `@0xchain/telemetry/middleware` 或 `@0xchain/telemetry/next` 导入。此入口轻量,无 Node SDK 依赖,适用于 Edge Runtime。
49
+
50
+ ```ts
51
+ import { NextResponse } from "next/server";
52
+ import { withTelemetryMiddleware } from "@0xchain/telemetry/middleware";
53
+
54
+ // 你的现有中间件逻辑
55
+ const userMiddleware = async (req) => {
56
+ // ... 业务逻辑
57
+ return NextResponse.next();
58
+ };
59
+
60
+ // 使用 withTelemetryMiddleware 包裹
61
+ export const middleware = withTelemetryMiddleware(userMiddleware);
62
+
63
+ export const config = {
64
+ matcher: [
65
+ /* 你的 matcher 配置 */
66
+ '/((?!_next/static|_next/image|favicon.ico).*)',
67
+ ],
68
+ };
69
+ ```
70
+
71
+ 如果你没有其他中间件,可以使用工厂方法:
72
+
73
+ ```ts
74
+ import { createTelemetryMiddleware } from "@0xchain/telemetry/middleware";
75
+
76
+ export const middleware = createTelemetryMiddleware();
77
+
78
+ export const config = {
79
+ matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
80
+ };
81
+ ```
82
+
83
+ ## 环境变量配置
84
+
85
+ 支持通过环境变量实现零代码配置:
86
+
87
+ | 变量名 | 描述 | 默认值 |
88
+ |---|---|---|
89
+ | `OTEL_SERVICE_NAME` | 服务名称 | `unknown-service` |
90
+ | `OTEL_SERVICE_VERSION` | 服务版本 | `1.0.0` |
91
+ | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP 上报地址 | - |
92
+ | `OTEL_EXPORTER_OTLP_HEADERS` | OTLP Headers (k=v,k2=v2) | - |
93
+ | `TELEMETRY_ENVIRONMENT` | 环境名称 (dev/prod) | `development`,在 Vercel 上自动使用 `VERCEL_ENV` |
94
+ | `TELEMETRY_SAMPLING_RATIO` | 默认采样率 (0.0-1.0) | `0.01` |
95
+ | `TELEMETRY_IGNORE_PATHS` | 忽略路径 (逗号分隔) | 默认忽略静态资源 |
96
+ | `TELEMETRY_INSPECTION_HEADER` | 巡检请求头 | `x-inspection` |
97
+ | `TELEMETRY_CONFIG_FILE` | 配置文件路径,支持 JSON,异步读取不阻塞启动 | - |
98
+
99
+ ## Vercel 集成
100
+
101
+ 部署到 Vercel 时,将自动检测并注入以下 resource 属性:
102
+
103
+ - `vercel.region`、`vercel.runtime`、`vercel.sha`、`vercel.host`、`vercel.deployment_id`
104
+ - `environment` 优先使用 `VERCEL_ENV`(production / preview / development)
105
+
106
+ ## 核心特性
107
+
108
+ 1. **巡检识别**:自动识别 `x-inspection` 请求头,强制采样并全量记录。
109
+ 2. **智能过滤**:内置静态资源过滤规则,支持自定义路径、扩展名和方法过滤。
110
+ 3. **多维采样**:支持按路径、用户类型、状态码配置不同的采样率。
111
+ 4. **低侵入性**:通过 HOC 方式集成中间件,不破坏原有逻辑。
112
+ 5. **入口拆分**:`instrumentation` 含完整 Node SDK;`middleware` / `next` 轻量,仅注入请求头,适合 Edge。
113
+ 6. **按需加载**:仅启用 HTTP + Undici 检测,减少冷启动与内存占用。
114
+
115
+ ## 常见问题
116
+
117
+ ### Module not found: Can't resolve '@0xchain/telemetry/instrumentation'
118
+
119
+ 1. **确认依赖**:确保应用 `package.json` 中有 `@0xchain/telemetry` 依赖。
120
+ 2. **确认构建**:telemetry 包需先构建,`dist/` 目录需存在。在 monorepo 根目录执行 `pnpm nx run telemetry:build`。
121
+ 3. **Next.js 配置**:若仍有问题,可在 `next.config.js` 中添加 `transpilePackages: ['@0xchain/telemetry']`。
122
+
123
+ ## 高级配置
124
+
125
+ ### 采样规则配置 (Sampling Rules)
126
+
127
+ 可以通过 `samplingRules` 字段或 `TELEMETRY_SAMPLING_RULES` 环境变量(JSON 字符串)配置:
128
+
129
+ ```json
130
+ [
131
+ {
132
+ "name": "critical-api",
133
+ "ratio": 1.0,
134
+ "when": { "path": ["/api/checkout", "/api/payment"] }
135
+ },
136
+ {
137
+ "name": "errors",
138
+ "ratio": 1.0,
139
+ "when": { "minStatusCode": 500 }
140
+ },
141
+ {
142
+ "name": "guest-users",
143
+ "ratio": 0.05,
144
+ "when": { "userType": ["guest"] }
145
+ }
146
+ ]
147
+ ```
@@ -1,2 +1,6 @@
1
- export default function getInstrumentations(ignoredPaths: string[]): any;
1
+ import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
2
+ import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';
3
+ import { TelemetryConfig } from './types';
4
+ /** 按需加载 HTTP + Undici 检测,避免全量 auto-instrumentations 的启动开销 */
5
+ export default function getInstrumentations(config: TelemetryConfig): (HttpInstrumentation | UndiciInstrumentation)[];
2
6
  //# sourceMappingURL=Instrumentations.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Instrumentations.d.ts","sourceRoot":"","sources":["../src/Instrumentations.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,GAAG,CAiCvE"}
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,mDA2ElE"}
package/dist/Sampler.d.ts CHANGED
@@ -1,11 +1,22 @@
1
- import { Sampler, SamplingResult } from '@opentelemetry/sdk-trace-base';
2
- import { SpanKind, Attributes, Link, Context } from '@opentelemetry/api';
3
- declare class InspectionSampler implements Sampler {
4
- private defaultSampler;
5
- private inspectionSampler;
6
- constructor(ratio: number);
7
- shouldSample(context: Context, traceId: string, spanName: string, spanKind: SpanKind, attributes: Attributes, links: Link[]): SamplingResult;
8
- toString(): string;
1
+ import { Sampler, SpanExporter } from '@opentelemetry/sdk-trace-base';
2
+ import { Attributes } from '@opentelemetry/api';
3
+ import { SamplingRule, TelemetryRuntime } from './types';
4
+ export interface SamplingContext {
5
+ path?: string;
6
+ method?: string;
7
+ userType?: string;
8
+ statusCode?: number;
9
+ inspection?: boolean;
9
10
  }
10
- export default InspectionSampler;
11
+ /** 基于 span attributes 构建采样上下文 */
12
+ export declare const buildSamplingContextFromAttributes: (attributes: Attributes) => SamplingContext;
13
+ /** 判断采样规则是否命中 */
14
+ export declare const matchSamplingRule: (rule: SamplingRule, context: SamplingContext) => boolean;
15
+ /** 根据规则解析采样比例 */
16
+ export declare const resolveSamplingRatio: (rules: SamplingRule[] | undefined, context: SamplingContext, defaultRatio: number) => number;
17
+ /** 创建基于规则的采样器 */
18
+ export declare const createRuleBasedSampler: (runtime: TelemetryRuntime) => Sampler;
19
+ /** 导出器直接透传,采样决策由 createRuleBasedSampler 在 span 创建时统一完成,避免 export 阶段重复计算 */
20
+ export declare const createFilteringTraceExporter: (exporter: SpanExporter) => SpanExporter;
21
+ export default createRuleBasedSampler;
11
22
  //# sourceMappingURL=Sampler.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Sampler.d.ts","sourceRoot":"","sources":["../src/Sampler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,cAAc,EAA+D,MAAM,+BAA+B,CAAC;AACrI,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAqB,MAAM,oBAAoB,CAAC;AAG5F,cAAM,iBAAkB,YAAW,OAAO;IACtC,OAAO,CAAC,cAAc,CAAU;IAChC,OAAO,CAAC,iBAAiB,CAAU;gBAEvB,KAAK,EAAE,MAAM;IAKzB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,cAAc;IAuB5I,QAAQ;CAGT;AAED,eAAe,iBAAiB,CAAC"}
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,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"}
@@ -0,0 +1,151 @@
1
+ const defaultIgnorePaths = [
2
+ // 健康检查 & 监控
3
+ "/health",
4
+ "/api/health",
5
+ "/metrics",
6
+ "/api/metrics",
7
+ "/readyz",
8
+ "/livez",
9
+ "/monitoring",
10
+ // Next.js 内部路由
11
+ "/_next",
12
+ "/__nextjs_",
13
+ // Next.js App Router 元数据路由
14
+ "/opengraph-image",
15
+ "/twitter-image",
16
+ "/icon",
17
+ "/apple-icon",
18
+ // Vercel 内部路由
19
+ "/_vercel",
20
+ // 静态资源 & SEO
21
+ "/favicon.ico",
22
+ "/robots.txt",
23
+ "/sitemap.xml",
24
+ "/manifest.json",
25
+ "/manifest.webmanifest",
26
+ "/.well-known",
27
+ // 认证回调(NextAuth.js)
28
+ "/api/auth"
29
+ ];
30
+ const defaultIgnoreSpanNames = [
31
+ // Next.js 内部服务端操作(非 HTTP 请求,由 Next.js OTel 自动产生)
32
+ /^NextNodeServer\./,
33
+ /^NextServer\./,
34
+ /^BaseServer\./,
35
+ /^AppRender\./,
36
+ /^AppRouteRouteHandlers\./,
37
+ // Next.js 中间件执行 span(如 "middleware GET /path")
38
+ /^middleware /i,
39
+ // Next.js 元数据解析
40
+ /^resolveMetadata$/,
41
+ /^generateMetadata$/
42
+ ];
43
+ const defaultIgnoreExtensions = [
44
+ ".css",
45
+ ".js",
46
+ ".mjs",
47
+ ".cjs",
48
+ ".png",
49
+ ".jpg",
50
+ ".jpeg",
51
+ ".gif",
52
+ ".svg",
53
+ ".ico",
54
+ ".webp",
55
+ ".avif",
56
+ ".woff",
57
+ ".woff2",
58
+ ".ttf",
59
+ ".eot",
60
+ ".map",
61
+ ".txt",
62
+ ".xml"
63
+ ];
64
+ const defaultIgnoreConfig = {
65
+ paths: defaultIgnorePaths,
66
+ extensions: defaultIgnoreExtensions,
67
+ methods: ["HEAD", "OPTIONS"],
68
+ spanNames: defaultIgnoreSpanNames
69
+ };
70
+ const normalizeExtensions = (extensions) => {
71
+ return extensions.map((ext) => {
72
+ const normalized = ext.trim().toLowerCase();
73
+ if (!normalized) return normalized;
74
+ return normalized.startsWith(".") ? normalized : `.${normalized}`;
75
+ });
76
+ };
77
+ const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
78
+ const matchesPathPattern = (pattern, pathname) => {
79
+ if (pattern instanceof RegExp) {
80
+ return pattern.test(pathname);
81
+ }
82
+ const normalized = pattern.trim();
83
+ if (!normalized) return false;
84
+ const hasGlob = normalized.includes("*");
85
+ if (hasGlob) {
86
+ const escaped = escapeRegex(normalized);
87
+ const regexSource = `^${escaped.replace(/\\\*\\\*/g, ".*").replace(/\\\*/g, "[^/]*")}$`;
88
+ return new RegExp(regexSource).test(pathname);
89
+ }
90
+ if (pathname === normalized) return true;
91
+ if (normalized.endsWith("/")) {
92
+ return pathname.startsWith(normalized);
93
+ }
94
+ return pathname.startsWith(`${normalized}/`) || pathname.startsWith(normalized);
95
+ };
96
+ const hasIgnoredExtension = (extensions, pathname) => {
97
+ const lower = pathname.toLowerCase();
98
+ return extensions.some((ext) => ext && lower.endsWith(ext));
99
+ };
100
+ const getCacheKey = (config) => {
101
+ if (!config) return "default";
102
+ const hasRegExp = config.paths?.some((p) => p instanceof RegExp);
103
+ if (hasRegExp) return null;
104
+ const paths = (config.paths ?? []).map(String).sort().join(",");
105
+ const extensions = (config.extensions ?? []).map((e) => e.toLowerCase()).sort().join(",");
106
+ const methods = (config.methods ?? []).map((m) => m.toUpperCase()).sort().join(",");
107
+ return `p:${paths}|e:${extensions}|m:${methods}`;
108
+ };
109
+ const matcherCache = /* @__PURE__ */ new Map();
110
+ const CACHE_MAX_SIZE = 16;
111
+ const createSpanNameMatcher = (config) => {
112
+ const patterns = config?.spanNames?.length ? config.spanNames : defaultIgnoreConfig.spanNames;
113
+ return (spanName) => {
114
+ if (!spanName || !patterns.length) return false;
115
+ return patterns.some((pattern) => matchesPathPattern(pattern, spanName));
116
+ };
117
+ };
118
+ const createIgnoreMatcher = (config) => {
119
+ const cacheKey = getCacheKey(config);
120
+ if (cacheKey) {
121
+ const cached = matcherCache.get(cacheKey);
122
+ if (cached) return cached;
123
+ }
124
+ const paths = config?.paths?.length ? config.paths : defaultIgnoreConfig.paths;
125
+ const extensions = config?.extensions?.length ? normalizeExtensions(config.extensions) : defaultIgnoreConfig.extensions;
126
+ const methods = config?.methods?.length ? config.methods.map((method) => method.toUpperCase()) : defaultIgnoreConfig.methods;
127
+ const matcher = (pathname, method) => {
128
+ if (method && methods.includes(method.toUpperCase())) {
129
+ return true;
130
+ }
131
+ if (!pathname) return false;
132
+ if (hasIgnoredExtension(extensions, pathname)) {
133
+ return true;
134
+ }
135
+ return paths.some((pattern) => matchesPathPattern(pattern, pathname));
136
+ };
137
+ if (cacheKey) {
138
+ if (matcherCache.size >= CACHE_MAX_SIZE) {
139
+ const firstKey = matcherCache.keys().next().value;
140
+ if (firstKey) matcherCache.delete(firstKey);
141
+ }
142
+ matcherCache.set(cacheKey, matcher);
143
+ }
144
+ return matcher;
145
+ };
146
+ export {
147
+ createSpanNameMatcher as a,
148
+ createIgnoreMatcher as c,
149
+ defaultIgnoreConfig as d,
150
+ matchesPathPattern as m
151
+ };
@@ -0,0 +1,9 @@
1
+ import { IgnoreConfig, PathPattern } from './types';
2
+ export declare const defaultIgnoreConfig: Required<IgnoreConfig>;
3
+ /** 判断路径是否匹配规则 */
4
+ export declare const matchesPathPattern: (pattern: PathPattern, pathname: string) => boolean;
5
+ /** 创建 span 名称忽略匹配器 */
6
+ export declare const createSpanNameMatcher: (config?: IgnoreConfig) => (spanName: string) => boolean;
7
+ /** 创建忽略规则匹配器(相同配置复用,减少重复创建) */
8
+ export declare const createIgnoreMatcher: (config?: IgnoreConfig) => (pathname: string, method?: string) => boolean;
9
+ //# sourceMappingURL=ignore.d.ts.map
@@ -0,0 +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;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 CHANGED
@@ -1,12 +1,22 @@
1
- import { OTLPExporterNodeConfigBase } from '@opentelemetry/otlp-exporter-base';
2
- interface TelemetryOptions extends OTLPExporterNodeConfigBase {
3
- serviceName: string;
4
- serviceVersion?: string;
5
- environment: string;
6
- ignorePaths?: string[];
7
- inspectionRatio?: number;
8
- }
9
- export declare function startTelemetry(otlpOptions: TelemetryOptions): void;
10
- export declare function shutdownTelemetry(): void;
11
- export {};
1
+ import { buildSamplingContextFromAttributes, matchSamplingRule, resolveSamplingRatio } from './Sampler';
2
+ import { createIgnoreMatcher, createSpanNameMatcher, defaultIgnoreConfig } from './ignore';
3
+ import { TelemetryConfig, TelemetryRuntime } from './types';
4
+ export * from './types';
5
+ export { buildSamplingContextFromAttributes, matchSamplingRule, resolveSamplingRatio, createIgnoreMatcher, createSpanNameMatcher, defaultIgnoreConfig, };
6
+ /** 从环境变量加载 Telemetry 配置(异步读取配置文件,不阻塞主线程) */
7
+ export declare const loadTelemetryConfigFromEnv: (env?: NodeJS.ProcessEnv) => Promise<Partial<TelemetryConfig>>;
8
+ /** 合并环境变量与显式配置得到最终配置 */
9
+ export declare const resolveTelemetryConfig: (options?: Partial<TelemetryConfig>, env?: NodeJS.ProcessEnv) => Promise<TelemetryConfig>;
10
+ /** 创建可运行时更新的配置容器 */
11
+ export declare const createTelemetryRuntime: (initialConfig: Partial<TelemetryConfig>) => Promise<TelemetryRuntime>;
12
+ /** 启动 OpenTelemetry SDK */
13
+ export declare const startTelemetry: (options: Partial<TelemetryConfig> | TelemetryConfig) => Promise<TelemetryRuntime>;
14
+ /** 运行时更新 Telemetry 配置 */
15
+ export declare const updateTelemetryConfig: (partial: Partial<TelemetryConfig>) => void;
16
+ /** 注入 traceparent 等传播头 */
17
+ export declare const injectTraceHeaders: (headers: Record<string, string>) => Record<string, string>;
18
+ /** 创建带 traceparent 注入的 fetch */
19
+ export declare const createPropagatingFetch: (fetchImpl?: typeof fetch) => (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
20
+ /** 停止并释放 Telemetry SDK */
21
+ export declare const shutdownTelemetry: () => Promise<void>;
12
22
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAY/E,UAAU,gBAAiB,SAAQ,0BAA0B;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,wBAAgB,cAAc,CAAC,WAAW,EAAE,gBAAgB,QAiC3D;AAED,wBAAgB,iBAAiB,SAIhC"}
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,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"}