@rare0619/nestjs-tracing 1.2.0

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 rare0619
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,212 @@
+# @rare0619/nestjs-tracing
+
+NestJS 全链路追踪插件 — 基于 OpenTelemetry，兼容 Elastic APM / Jaeger / 任何 OTLP 后端。
+
+## 特性
+
+- **零配置启动**：`main.ts` 第一行 import 即可，自动推断服务名
+- **白名单插桩**：仅启用项目实际使用的插桩库（HTTP、Express、PostgreSQL、Redis），避免冗余开销
+- **NestJS 适配**：修复 NestJS + Express 场景下 transaction name 只显示 `GET`/`HEAD` 的问题，自动设为 `METHOD /path` 格式
+- **噪音过滤**：自动过滤 health check（incoming）和 ES/APM/OTLP 基础设施请求（outgoing），保持 trace waterfall 干净
+- **日志关联**：提供 `otelLogFormat()` winston format，自动注入 `trace.id` / `span.id`
+- **手动打点**：`@Span()` 装饰器支持自定义 span
+- **优雅关机**：SIGTERM/SIGINT 时自动 flush 缓冲区中的 span
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+npm install @rare0619/nestjs-tracing
+```
+
+### 2. 初始化（main.ts 第一行）
+
+```typescript
+// ⚠️ 必须是第一行 import，在 @nestjs/core 之前
+import '@rare0619/nestjs-tracing/tracer';
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+> **为什么必须第一行**：OTel 通过 monkey-patch Node.js 的 `http`、`pg`、`ioredis` 等模块实现插桩。如果这些模块在 OTel 初始化之前被 `require()`，patch 将无效。
+
+### 3. 环境变量
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `OTEL_SERVICE_NAME` | 自动推断 | 服务名（优先级：此变量 > `SERVICE_NAME` > 从 `dist/apps/{name}/main.js` 路径推断） |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | APM Server / OTLP Collector 地址（自动追加 `/v1/traces`） |
+| `OTEL_TRACES_SAMPLER_ARG` | `1.0` | 采样率（开发环境 `1.0` 100%，生产环境建议 `0.1` 10%） |
+| `OTEL_SDK_DISABLED` | — | 设为 `true` 禁用 SDK（无 APM Server 时避免报错） |
+| `NODE_ENV` | `development` | 部署环境标识（写入 `deployment.environment` resource attribute） |
+| `ELASTICSEARCH_PORT` | `9200` | ES 端口（用于 outgoing 请求过滤） |
+| `APM_PORT` | `8200` | APM Server 端口（用于 outgoing 请求过滤） |
+
+tracer 会自动加载项目根目录的 `.env` 文件（无需 `dotenv` 依赖）。
+
+## 插桩覆盖
+
+采用**白名单模式**，仅启用项目实际使用的插桩库：
+
+| 插桩库 | 覆盖组件 | 说明 |
+|--------|---------|------|
+| `HttpInstrumentation` | HTTP 请求（含 axios 出站） | 含 incoming/outgoing 过滤和 server span 重命名 |
+| `ExpressInstrumentation` | Express 路由（NestJS 底层） | |
+| `PgInstrumentation` | PostgreSQL（TypeORM 底层驱动 `pg`） | trace 中可见 `pg.query:SELECT` |
+| `IORedisInstrumentation` | Redis（`ioredis`） | trace 中可见 `sismember`/`get` 等 |
+
+> **关于 axios / typeorm**：无需单独插桩——`axios` 底层走 `http` 模块，`typeorm` 底层走 `pg` 驱动，已被自动追踪。
+
+### 噪音过滤
+
+#### Incoming 过滤（`ignoreIncomingRequestHook`）
+
+自动忽略 K8s 健康检查等高频低价值请求：
+- URL 包含 `/health` 或 `/readiness`
+
+#### Outgoing 过滤（`ignoreOutgoingRequestHook`）
+
+三重过滤策略，防止 ES/APM/OTLP 基础设施请求产生噪音 span：
+
+1. **端口匹配**：ES（9200）、APM（8200）、OTLP（4317/4318）
+2. **Path 匹配**：`/_cluster/`、`/_bulk`、`/_template/` 等 ES 内部 API
+3. **URL 匹配**：href 中包含 `:9200` 或 `:8200`
+
+#### NestJS Transaction Name 修复
+
+NestJS + Express 场景下，`ExpressInstrumentation` 无法正确捕获路由 pattern，导致 transaction name 只显示 `GET` / `HEAD`。通过 `applyCustomAttributesOnSpan` 自动重命名为 `GET /user/v1/userinfo` 格式。
+
+### 扩展插桩
+
+如需添加更多插桩库，修改 `src/tracer.ts` 中的 `instrumentations` 数组：
+
+```typescript
+// MySQL / Doris（MySQL 协议兼容）
+npm install @opentelemetry/instrumentation-mysql2
+// 在 tracer.ts 中添加：
+const { MySQL2Instrumentation } = require('@opentelemetry/instrumentation-mysql2');
+// instrumentations: [..., new MySQL2Instrumentation()]
+
+// RabbitMQ
+npm install @opentelemetry/instrumentation-amqplib
+// 在 tracer.ts 中添加：
+const { AmqplibInstrumentation } = require('@opentelemetry/instrumentation-amqplib');
+```
+
+## 日志关联
+
+将 Winston 日志与 Trace 关联，实现 Kibana APM Transaction → Logs 一键跳转：
+
+```typescript
+import { otelLogFormat } from '@rare0619/nestjs-tracing';
+
+const logger = winston.createLogger({
+  format: winston.format.combine(
+    otelLogFormat(),          // ← 自动注入 trace.id / span.id
+    winston.format.json(),
+  ),
+});
+```
+
+> **winston-elasticsearch 用户注意**：如果使用 `winston-elasticsearch` 直写 ES，需要额外处理：
+> 1. 创建自定义 ES Client 并禁用 `diagnostic.removeAllListeners()`（防止 `bulk`/`cluster.health` 噪音 span）
+> 2. 用 `api.context.with(ROOT_CONTEXT, ...)` 包裹 `origLog()` 调用（防止 BulkWriter 定时 flush 成为请求 span 的子 span）
+>
+> 详见 [kibana-apm-tracing-guide.md](../doc/kibana-apm-tracing-guide.md) 中问题 6 和问题 7。
+
+### 生产环境：Filebeat 采集日志
+
+生产环境推荐用 Filebeat 采集 JSON 日志文件（解耦应用与 ES，避免性能影响）：
+
+```yaml
+# filebeat.yml
+filebeat.inputs:
+  - type: log
+    enabled: true
+    paths:
+      - /app/logs/gateway-*.log
+      - /app/logs/user-service-*.log
+      - /app/logs/social-service-*.log
+    # JSON 解析：将日志字段提升到文档根级（trace.id 等字段需要在根级才能被 Kibana APM 关联）
+    json.keys_under_root: true
+    json.add_error_key: true
+    json.overwrite_keys: true
+    # 排除 error/exceptions 独立文件（避免重复采集）
+    exclude_files: ['error-.*', 'exceptions-.*', 'rejections-.*']
+
+  # 单独采集 error 日志
+  - type: log
+    enabled: true
+    paths:
+      - /app/logs/error-*.log
+    json.keys_under_root: true
+    json.add_error_key: true
+    json.overwrite_keys: true
+    fields:
+      log.level: error
+    fields_under_root: true
+
+output.elasticsearch:
+  hosts: ["${ELASTICSEARCH_HOSTS:localhost:9200}"]
+  username: "${ELASTICSEARCH_USER:elastic}"
+  password: "${ELASTICSEARCH_PASS:changeme}"
+  index: "app-logs-%{+yyyy.MM.dd}"
+
+setup.template.name: "app-logs"
+setup.template.pattern: "app-logs-*"
+setup.ilm.enabled: false
+
+processors:
+  - drop_fields:
+      fields: ["agent", "ecs", "host", "input", "log.offset"]
+      ignore_missing: true
+```
+
+> **关键点**：`json.keys_under_root: true` 会把 JSON 日志中的 `trace.id` 字段提升到文档根级，这样 Kibana APM 的 Logs 标签才能通过 `trace.id` 自动关联日志。
+
+## 手动打点
+
+```typescript
+import { Span } from '@rare0619/nestjs-tracing';
+
+export class OrderService {
+  @Span('create-order')
+  async createOrder(dto: CreateOrderDto) {
+    // 自动创建 Span，异常自动记录
+  }
+}
+```
+
+## 中间件（可选）
+
+自动将 OTel traceId 写入 `x-request-id` / `x-trace-id` 响应头：
+
+```typescript
+import { TracingModule } from '@rare0619/nestjs-tracing';
+
+@Module({
+  imports: [TracingModule],
+})
+export class AppModule {}
+```
+
+## 已知问题与注意事项
+
+| 问题 | 说明 |
+|------|------|
+| `@elastic/elasticsearch` v8+ 噪音 | ES Client 内置 OTel diagnostic channel，会产生 `bulk`/`cluster.health` 噪音 span。需在创建 Client 时调用 `diagnostic.removeAllListeners()` |
+| `NetInstrumentation` | 产生大量 `tcp.connect` 噪音 span，不建议启用 |
+| `requestHook` vs `applyCustomAttributesOnSpan` | 前者只对 outgoing 请求生效，后者对 incoming/outgoing 都生效。NestJS 场景下 server span 重命名必须用后者 |
+| webpack 打包兼容 | OTel 的 monkey-patch 在 webpack `target: 'node'` 下正常工作（NestJS CLI 默认配置） |
+
+## License
+
+Apache-2.0

package/dist/decorators/span.decorator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 方法装饰器：自动为方法创建 OTel Span
+ *
+ * 功能：
+ *   - 方法调用时自动创建 active span
+ *   - 异常自动 recordException + 标记 ERROR 状态
+ *   - 方法结束时自动 end span
+ *   - 同步方法不会被强制异步化（避免不必要的事件循环延迟）
+ *
+ * 使用方式：
+ *   import { Span } from '@rare0619/nestjs-tracing';
+ *
+ *   @Span('create-order')
+ *   async createOrder(dto: CreateOrderDto) {
+ *     // 自动创建名为 'create-order' 的 Span
+ *     // 异常自动捕获
+ *   }
+ *
+ *   @Span()  // 默认使用 类名.方法名
+ *   async getUser(id: string) { ... }
+ */
+export declare function Span(name?: string): MethodDecorator;
+//# sourceMappingURL=span.decorator.d.ts.map

package/dist/decorators/span.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/span.decorator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,eAAe,CAsDnD"}

package/dist/decorators/span.decorator.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Span = Span;
+const api_1 = require("@opentelemetry/api");
+/**
+ * 方法装饰器：自动为方法创建 OTel Span
+ *
+ * 功能：
+ *   - 方法调用时自动创建 active span
+ *   - 异常自动 recordException + 标记 ERROR 状态
+ *   - 方法结束时自动 end span
+ *   - 同步方法不会被强制异步化（避免不必要的事件循环延迟）
+ *
+ * 使用方式：
+ *   import { Span } from '@rare0619/nestjs-tracing';
+ *
+ *   @Span('create-order')
+ *   async createOrder(dto: CreateOrderDto) {
+ *     // 自动创建名为 'create-order' 的 Span
+ *     // 异常自动捕获
+ *   }
+ *
+ *   @Span()  // 默认使用 类名.方法名
+ *   async getUser(id: string) { ... }
+ */
+function Span(name) {
+    return (target, propertyKey, descriptor) => {
+        const originalMethod = descriptor.value;
+        const spanName = name || `${target.constructor.name}.${String(propertyKey)}`;
+        descriptor.value = function (...args) {
+            const tracer = api_1.trace.getTracer('@rare0619/nestjs-tracing');
+            return tracer.startActiveSpan(spanName, (span) => {
+                try {
+                    const result = originalMethod.apply(this, args);
+                    // 异步方法：返回 Promise
+                    if (result instanceof Promise) {
+                        return result.then((val) => {
+                            span.end();
+                            return val;
+                        }, (err) => {
+                            span.recordException(err);
+                            span.setStatus({
+                                code: api_1.SpanStatusCode.ERROR,
+                                message: err?.message || 'Unknown error',
+                            });
+                            span.end();
+                            throw err;
+                        });
+                    }
+                    // 同步方法：直接结束（不引入 async 开销）
+                    span.end();
+                    return result;
+                }
+                catch (err) {
+                    // 同步方法抛出异常
+                    span.recordException(err);
+                    span.setStatus({
+                        code: api_1.SpanStatusCode.ERROR,
+                        message: err?.message || 'Unknown error',
+                    });
+                    span.end();
+                    throw err;
+                }
+            });
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=span.decorator.js.map

package/dist/decorators/span.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"span.decorator.js","sourceRoot":"","sources":["../../src/decorators/span.decorator.ts"],"names":[],"mappings":";;AAuBA,oBAsDC;AA7ED,4CAA2D;AAE3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,IAAI,CAAC,IAAa;IAC9B,OAAO,CACH,MAAW,EACX,WAA4B,EAC5B,UAA8B,EAChC,EAAE;QACA,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAC;QACxC,MAAM,QAAQ,GACV,IAAI,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,IAAI,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC;QAEhE,UAAU,CAAC,KAAK,GAAG,UAAqB,GAAG,IAAW;YAClD,MAAM,MAAM,GAAG,WAAK,CAAC,SAAS,CAAC,0BAA0B,CAAC,CAAC;YAE3D,OAAO,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC7C,IAAI,CAAC;oBACD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;oBAEhD,kBAAkB;oBAClB,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;wBAC5B,OAAO,MAAM,CAAC,IAAI,CACd,CAAC,GAAG,EAAE,EAAE;4BACJ,IAAI,CAAC,GAAG,EAAE,CAAC;4BACX,OAAO,GAAG,CAAC;wBACf,CAAC,EACD,CAAC,GAAG,EAAE,EAAE;4BACJ,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;4BAC1B,IAAI,CAAC,SAAS,CAAC;gCACX,IAAI,EAAE,oBAAc,CAAC,KAAK;gCAC1B,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,eAAe;6BAC3C,CAAC,CAAC;4BACH,IAAI,CAAC,GAAG,EAAE,CAAC;4BACX,MAAM,GAAG,CAAC;wBACd,CAAC,CACJ,CAAC;oBACN,CAAC;oBAED,0BAA0B;oBAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;oBACX,OAAO,MAAM,CAAC;gBAClB,CAAC;gBAAC,OAAO,GAAQ,EAAE,CAAC;oBAChB,WAAW;oBACX,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;oBAC1B,IAAI,CAAC,SAAS,CAAC;wBACX,IAAI,EAAE,oBAAc,CAAC,KAAK;wBAC1B,OAAO,EAAE,GAAG,EAAE,OAAO,IAAI,eAAe;qBAC3C,CAAC,CAAC;oBACH,IAAI,CAAC,GAAG,EAAE,CAAC;oBACX,MAAM,GAAG,CAAC;gBACd,CAAC;YACL,CAAC,CAAC,CAAC;QACP,CAAC,CAAC;QAEF,OAAO,UAAU,CAAC;IACtB,CAAC,CAAC;AACN,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @rare0619/nestjs-tracing
+ *
+ * NestJS 全链路追踪插件（OpenTelemetry + Elastic APM）
+ *
+ * 快速开始：
+ *   // main.ts 第一行（必须在所有 import 之前）
+ *   import '@rare0619/nestjs-tracing/tracer';
+ *
+ *   // 日志关联（winston format 链）
+ *   import { otelLogFormat } from '@rare0619/nestjs-tracing';
+ *
+ *   // 手动打点装饰器
+ *   import { Span } from '@rare0619/nestjs-tracing';
+ */
+export { otelLogFormat } from './winston/otel-log-format';
+export { TraceSyncMiddleware } from './middleware/trace-sync.middleware';
+export { Span } from './decorators/span.decorator';
+export { TracingModule } from './tracing.module';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAGzE,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AAGnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * @rare0619/nestjs-tracing
+ *
+ * NestJS 全链路追踪插件（OpenTelemetry + Elastic APM）
+ *
+ * 快速开始：
+ *   // main.ts 第一行（必须在所有 import 之前）
+ *   import '@rare0619/nestjs-tracing/tracer';
+ *
+ *   // 日志关联（winston format 链）
+ *   import { otelLogFormat } from '@rare0619/nestjs-tracing';
+ *
+ *   // 手动打点装饰器
+ *   import { Span } from '@rare0619/nestjs-tracing';
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracingModule = exports.Span = exports.TraceSyncMiddleware = exports.otelLogFormat = void 0;
+// 日志关联
+var otel_log_format_1 = require("./winston/otel-log-format");
+Object.defineProperty(exports, "otelLogFormat", { enumerable: true, get: function () { return otel_log_format_1.otelLogFormat; } });
+// 中间件
+var trace_sync_middleware_1 = require("./middleware/trace-sync.middleware");
+Object.defineProperty(exports, "TraceSyncMiddleware", { enumerable: true, get: function () { return trace_sync_middleware_1.TraceSyncMiddleware; } });
+// 装饰器
+var span_decorator_1 = require("./decorators/span.decorator");
+Object.defineProperty(exports, "Span", { enumerable: true, get: function () { return span_decorator_1.Span; } });
+// NestJS Module
+var tracing_module_1 = require("./tracing.module");
+Object.defineProperty(exports, "TracingModule", { enumerable: true, get: function () { return tracing_module_1.TracingModule; } });
+// 注意：tracer.ts 不在此导出
+// 必须通过 import '@rare0619/nestjs-tracing/tracer' 在 main.ts 第一行单独导入
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,OAAO;AACP,6DAA0D;AAAjD,gHAAA,aAAa,OAAA;AAEtB,MAAM;AACN,4EAAyE;AAAhE,4HAAA,mBAAmB,OAAA;AAE5B,MAAM;AACN,8DAAmD;AAA1C,sGAAA,IAAI,OAAA;AAEb,gBAAgB;AAChB,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AAEtB,qBAAqB;AACrB,kEAAkE"}

package/dist/middleware/trace-sync.middleware.d.ts

@@ -0,0 +1,24 @@
+import { NestMiddleware } from '@nestjs/common';
+import { Request, Response, NextFunction } from 'express';
+/**
+ * 中间件：将 OTel traceId 同步到 HTTP 响应头
+ *
+ * 功能：
+ *   1. 从 OTel active span 提取 W3C 标准 traceId (32 位 hex)
+ *   2. 写入 x-request-id 和 x-trace-id 响应头
+ *   3. 兼容已有的 x-request-id 机制（向后兼容）
+ *
+ * 使用方式：
+ *   import { TraceSyncMiddleware } from '@rare0619/nestjs-tracing';
+ *
+ *   // 在 AppModule 中注册
+ *   export class AppModule implements NestModule {
+ *     configure(consumer: MiddlewareConsumer) {
+ *       consumer.apply(TraceSyncMiddleware).forRoutes('*');
+ *     }
+ *   }
+ */
+export declare class TraceSyncMiddleware implements NestMiddleware {
+    use(req: Request, res: Response, next: NextFunction): void;
+}
+//# sourceMappingURL=trace-sync.middleware.d.ts.map

package/dist/middleware/trace-sync.middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-sync.middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/trace-sync.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG1D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,mBAAoB,YAAW,cAAc;IACtD,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI;CAU7D"}

package/dist/middleware/trace-sync.middleware.js

@@ -0,0 +1,46 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TraceSyncMiddleware = void 0;
+const common_1 = require("@nestjs/common");
+const api_1 = require("@opentelemetry/api");
+/**
+ * 中间件：将 OTel traceId 同步到 HTTP 响应头
+ *
+ * 功能：
+ *   1. 从 OTel active span 提取 W3C 标准 traceId (32 位 hex)
+ *   2. 写入 x-request-id 和 x-trace-id 响应头
+ *   3. 兼容已有的 x-request-id 机制（向后兼容）
+ *
+ * 使用方式：
+ *   import { TraceSyncMiddleware } from '@rare0619/nestjs-tracing';
+ *
+ *   // 在 AppModule 中注册
+ *   export class AppModule implements NestModule {
+ *     configure(consumer: MiddlewareConsumer) {
+ *       consumer.apply(TraceSyncMiddleware).forRoutes('*');
+ *     }
+ *   }
+ */
+let TraceSyncMiddleware = class TraceSyncMiddleware {
+    use(req, res, next) {
+        const activeSpan = api_1.trace.getActiveSpan();
+        if (activeSpan) {
+            const traceId = activeSpan.spanContext().traceId;
+            // 向后兼容旧 x-request-id + 新标准 x-trace-id
+            res.header('x-request-id', traceId);
+            res.header('x-trace-id', traceId);
+        }
+        next();
+    }
+};
+exports.TraceSyncMiddleware = TraceSyncMiddleware;
+exports.TraceSyncMiddleware = TraceSyncMiddleware = __decorate([
+    (0, common_1.Injectable)()
+], TraceSyncMiddleware);
+//# sourceMappingURL=trace-sync.middleware.js.map

package/dist/middleware/trace-sync.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-sync.middleware.js","sourceRoot":"","sources":["../../src/middleware/trace-sync.middleware.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4D;AAE5D,4CAA2C;AAE3C;;;;;;;;;;;;;;;;;GAiBG;AAEI,IAAM,mBAAmB,GAAzB,MAAM,mBAAmB;IAC5B,GAAG,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QAC/C,MAAM,UAAU,GAAG,WAAK,CAAC,aAAa,EAAE,CAAC;QACzC,IAAI,UAAU,EAAE,CAAC;YACb,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC;YACjD,sCAAsC;YACtC,GAAG,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;YACpC,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,EAAE,CAAC;IACX,CAAC;CACJ,CAAA;AAXY,kDAAmB;8BAAnB,mBAAmB;IAD/B,IAAA,mBAAU,GAAE;GACA,mBAAmB,CAW/B"}

package/dist/tracer.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @rare0619/nestjs-tracing — OTel SDK 自动初始化
+ *
+ * ⚠️ 必须在 main.ts 第一行 import（在任何 NestJS/Express 导入之前）
+ *
+ * 使用方式：
+ *   import '@rare0619/nestjs-tracing/tracer';
+ *   import { NestFactory } from '@nestjs/core';
+ *
+ * 环境变量（均为可选，有智能默认值）：
+ *   OTEL_SERVICE_NAME              服务名（不设则从入口路径自动推断）
+ *   OTEL_EXPORTER_OTLP_ENDPOINT    APM Server 地址（默认 http://localhost:4318/v1/traces）
+ *   OTEL_TRACES_SAMPLER            采样器（默认 parentbased_traceidratio）
+ *   OTEL_TRACES_SAMPLER_ARG        采样率（开发 1.0 / 生产 0.1）
+ *   OTEL_SDK_DISABLED              设为 'true' 禁用 SDK（无 APM 时使用）
+ *   NODE_ENV                       环境标识
+ */
+/**
+ * 智能推断服务名
+ *
+ * 优先级：
+ *   1. OTEL_SERVICE_NAME 环境变量（显式指定）
+ *   2. SERVICE_NAME 环境变量（Docker/K8s 注入）
+ *   3. 从入口路径自动推断（NestJS monorepo: dist/apps/{service-name}/main.js）
+ *   4. 'unknown-service' 兜底
+ */
+export declare function detectServiceName(): string;
+/**
+ * 构建 OTLP Traces 完整 URL
+ * OTLPTraceExporter 的 `url` 参数不会自动追加 /v1/traces，需手动处理
+ */
+export declare function buildTracesUrl(endpoint?: string): string;
+/** 判断 incoming 请求是否应被忽略（health check 等高频低价值请求） */
+export declare function shouldIgnoreIncoming(url: string): boolean;
+/** ES / APM 等基础设施的端口，用于过滤 outgoing 噪音 span */
+export declare function getInfraPorts(): Set<number>;
+/** ES 内部 API 路径前缀 */
+export declare const ES_PATH_PREFIXES: string[];
+/** 判断 outgoing 请求是否应被忽略（ES/APM/OTLP 基础设施请求） */
+export declare function shouldIgnoreOutgoing(opts: {
+    port?: number | string;
+    path?: string;
+    href?: string;
+    hostname?: string;
+}): boolean;
+//# sourceMappingURL=tracer.d.ts.map

package/dist/tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.d.ts","sourceRoot":"","sources":["../src/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgCH;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAS1C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED,kDAAkD;AAClD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,CAAC,CAO3C;AAED,qBAAqB;AACrB,eAAO,MAAM,gBAAgB,UAAiF,CAAC;AAE/G,+CAA+C;AAC/C,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAQ/H"}

package/dist/tracer.js

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * @rare0619/nestjs-tracing — OTel SDK 自动初始化
+ *
+ * ⚠️ 必须在 main.ts 第一行 import（在任何 NestJS/Express 导入之前）
+ *
+ * 使用方式：
+ *   import '@rare0619/nestjs-tracing/tracer';
+ *   import { NestFactory } from '@nestjs/core';
+ *
+ * 环境变量（均为可选，有智能默认值）：
+ *   OTEL_SERVICE_NAME              服务名（不设则从入口路径自动推断）
+ *   OTEL_EXPORTER_OTLP_ENDPOINT    APM Server 地址（默认 http://localhost:4318/v1/traces）
+ *   OTEL_TRACES_SAMPLER            采样器（默认 parentbased_traceidratio）
+ *   OTEL_TRACES_SAMPLER_ARG        采样率（开发 1.0 / 生产 0.1）
+ *   OTEL_SDK_DISABLED              设为 'true' 禁用 SDK（无 APM 时使用）
+ *   NODE_ENV                       环境标识
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ES_PATH_PREFIXES = void 0;
+exports.detectServiceName = detectServiceName;
+exports.buildTracesUrl = buildTracesUrl;
+exports.shouldIgnoreIncoming = shouldIgnoreIncoming;
+exports.getInfraPorts = getInfraPorts;
+exports.shouldIgnoreOutgoing = shouldIgnoreOutgoing;
+// ============ 可导出的纯函数（供单元测试使用）============
+// 在 SDK 初始化之前先加载 .env
+// （因为 tracer 在 main.ts 第一行执行，NestJS 的 dotenv 尚未加载）
+// 使用 fs 手动解析，避免 webpack 打包对 require('dotenv') 的干扰
+try {
+    const fs = require('fs');
+    const path = require('path');
+    const envPath = path.resolve(process.cwd(), '.env');
+    if (fs.existsSync(envPath)) {
+        const envContent = fs.readFileSync(envPath, 'utf8');
+        for (const line of envContent.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            const eqIdx = trimmed.indexOf('=');
+            if (eqIdx === -1)
+                continue;
+            const key = trimmed.slice(0, eqIdx).trim();
+            const value = trimmed.slice(eqIdx + 1).trim();
+            // 不覆盖已有的系统环境变量
+            if (!process.env[key]) {
+                process.env[key] = value;
+            }
+        }
+    }
+}
+catch {
+    // 静默忽略：靠系统环境变量即可
+}
+// ============ 可导出的纯函数（供单元测试使用）============
+/**
+ * 智能推断服务名
+ *
+ * 优先级：
+ *   1. OTEL_SERVICE_NAME 环境变量（显式指定）
+ *   2. SERVICE_NAME 环境变量（Docker/K8s 注入）
+ *   3. 从入口路径自动推断（NestJS monorepo: dist/apps/{service-name}/main.js）
+ *   4. 'unknown-service' 兜底
+ */
+function detectServiceName() {
+    if (process.env.OTEL_SERVICE_NAME)
+        return process.env.OTEL_SERVICE_NAME;
+    if (process.env.SERVICE_NAME)
+        return process.env.SERVICE_NAME;
+    const entryFile = process.argv[1] || '';
+    const match = entryFile.match(/dist[\/\\]apps[\/\\]([^\/\\]+)/);
+    if (match)
+        return match[1];
+    return 'unknown-service';
+}
+/**
+ * 构建 OTLP Traces 完整 URL
+ * OTLPTraceExporter 的 `url` 参数不会自动追加 /v1/traces，需手动处理
+ */
+function buildTracesUrl(endpoint) {
+    const rawEndpoint = endpoint || 'http://localhost:4318';
+    return rawEndpoint.endsWith('/v1/traces')
+        ? rawEndpoint
+        : `${rawEndpoint.replace(/\/+$/, '')}/v1/traces`;
+}
+/** 判断 incoming 请求是否应被忽略（health check 等高频低价值请求） */
+function shouldIgnoreIncoming(url) {
+    return url.includes('/health') || url.includes('/readiness');
+}
+/** ES / APM 等基础设施的端口，用于过滤 outgoing 噪音 span */
+function getInfraPorts() {
+    return new Set([
+        parseInt(process.env.ELASTICSEARCH_PORT || '9200', 10),
+        parseInt(process.env.APM_PORT || '8200', 10),
+        4317,
+        4318,
+    ]);
+}
+/** ES 内部 API 路径前缀 */
+exports.ES_PATH_PREFIXES = ['/_cluster/', '/_bulk', '/_template/', '/_index_template/', '/_data_stream/'];
+/** 判断 outgoing 请求是否应被忽略（ES/APM/OTLP 基础设施请求） */
+function shouldIgnoreOutgoing(opts) {
+    const port = Number(opts.port);
+    if (port && getInfraPorts().has(port))
+        return true;
+    const reqPath = opts.path || '';
+    if (exports.ES_PATH_PREFIXES.some((prefix) => reqPath.startsWith(prefix)))
+        return true;
+    const href = opts.href || opts.hostname || '';
+    if (typeof href === 'string' && (href.includes(':9200') || href.includes(':8200')))
+        return true;
+    return false;
+}
+// ============ SDK 初始化（仅在未禁用时执行）============
+if (process.env.OTEL_SDK_DISABLED !== 'true') {
+    const { NodeSDK } = require('@opentelemetry/sdk-node');
+    const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
+    const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
+    const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
+    const { PgInstrumentation } = require('@opentelemetry/instrumentation-pg');
+    const { IORedisInstrumentation } = require('@opentelemetry/instrumentation-ioredis');
+    const { Resource } = require('@opentelemetry/resources');
+    const { SEMRESATTRS_SERVICE_NAME, SEMRESATTRS_DEPLOYMENT_ENVIRONMENT, } = require('@opentelemetry/semantic-conventions');
+    const { W3CTraceContextPropagator } = require('@opentelemetry/core');
+    const serviceName = detectServiceName();
+    const tracesUrl = buildTracesUrl(process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+    const sdk = new NodeSDK({
+        resource: new Resource({
+            [SEMRESATTRS_SERVICE_NAME]: serviceName,
+            [SEMRESATTRS_DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'development',
+        }),
+        traceExporter: new OTLPTraceExporter({
+            url: tracesUrl,
+            timeoutMillis: 10000,
+        }),
+        textMapPropagator: new W3CTraceContextPropagator(),
+        instrumentations: [
+            // ——— HTTP & Express ———
+            new HttpInstrumentation({
+                ignoreIncomingRequestHook: (req) => shouldIgnoreIncoming(req.url || ''),
+                ignoreOutgoingRequestHook: (opts) => shouldIgnoreOutgoing(opts),
+                // 重命名 incoming server span：NestJS + Express 默认只有 METHOD，改为 METHOD /path
+                applyCustomAttributesOnSpan: (span, request, _response) => {
+                    // IncomingMessage（server span）有 httpVersion 属性，ClientRequest（client span）没有
+                    if (request?.httpVersion && request.method && request.url) {
+                        const path = (request.url || '').split('?')[0];
+                        span.updateName(`${request.method} ${path}`);
+                    }
+                },
+            }),
+            new ExpressInstrumentation(),
+            // ——— 数据库 ———
+            new PgInstrumentation(), // PostgreSQL（TypeORM 底层驱动 pg）
+            new IORedisInstrumentation(), // Redis (ioredis)
+            // NetInstrumentation 产生大量 tcp.connect 噪音，不启用
+            // Doris 使用 MySQL 协议 — 项目中暂未安装 mysql/mysql2 驱动
+            // 如需启用：npm install @opentelemetry/instrumentation-mysql2
+        ],
+    });
+    sdk.start();
+    console.log(`[@rare0619/tracing] initialized: service=${serviceName}, endpoint=${tracesUrl}`);
+    // 优雅关机：确保缓冲区中的 Span 被冲刷到网络
+    const shutdown = async () => {
+        await sdk.shutdown();
+        console.log('[@rare0619/tracing] shutdown complete');
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+    // @ts-ignore — 导出供外部访问（可选）
+    module.exports = { sdk };
+}
+//# sourceMappingURL=tracer.js.map

package/dist/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../src/tracer.ts"],"names":[],"mappings":"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"}

package/dist/tracing.module.d.ts

@@ -0,0 +1,21 @@
+import { MiddlewareConsumer, NestModule } from '@nestjs/common';
+/**
+ * NestJS 追踪模块
+ *
+ * 导入此模块将自动注册 TraceSyncMiddleware（全局路由）
+ *
+ * 使用方式：
+ *   import { TracingModule } from '@rare0619/nestjs-tracing';
+ *
+ *   @Module({
+ *     imports: [TracingModule],
+ *   })
+ *   export class AppModule {}
+ *
+ * 注意：tracer.ts 的 import 必须在 main.ts 第一行单独完成，
+ * 不能依赖 NestJS DI 容器（因为初始化必须早于所有模块加载）。
+ */
+export declare class TracingModule implements NestModule {
+    configure(consumer: MiddlewareConsumer): void;
+}
+//# sourceMappingURL=tracing.module.d.ts.map

package/dist/tracing.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.module.d.ts","sourceRoot":"","sources":["../src/tracing.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGxE;;;;;;;;;;;;;;;GAeG;AACH,qBAIa,aAAc,YAAW,UAAU;IAC5C,SAAS,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI;CAGhD"}

package/dist/tracing.module.js

@@ -0,0 +1,40 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TracingModule = void 0;
+const common_1 = require("@nestjs/common");
+const trace_sync_middleware_1 = require("./middleware/trace-sync.middleware");
+/**
+ * NestJS 追踪模块
+ *
+ * 导入此模块将自动注册 TraceSyncMiddleware（全局路由）
+ *
+ * 使用方式：
+ *   import { TracingModule } from '@rare0619/nestjs-tracing';
+ *
+ *   @Module({
+ *     imports: [TracingModule],
+ *   })
+ *   export class AppModule {}
+ *
+ * 注意：tracer.ts 的 import 必须在 main.ts 第一行单独完成，
+ * 不能依赖 NestJS DI 容器（因为初始化必须早于所有模块加载）。
+ */
+let TracingModule = class TracingModule {
+    configure(consumer) {
+        consumer.apply(trace_sync_middleware_1.TraceSyncMiddleware).forRoutes('*');
+    }
+};
+exports.TracingModule = TracingModule;
+exports.TracingModule = TracingModule = __decorate([
+    (0, common_1.Module)({
+        providers: [trace_sync_middleware_1.TraceSyncMiddleware],
+        exports: [trace_sync_middleware_1.TraceSyncMiddleware],
+    })
+], TracingModule);
+//# sourceMappingURL=tracing.module.js.map

package/dist/tracing.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.module.js","sourceRoot":"","sources":["../src/tracing.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwE;AACxE,8EAAyE;AAEzE;;;;;;;;;;;;;;;GAeG;AAKI,IAAM,aAAa,GAAnB,MAAM,aAAa;IACtB,SAAS,CAAC,QAA4B;QAClC,QAAQ,CAAC,KAAK,CAAC,2CAAmB,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;CACJ,CAAA;AAJY,sCAAa;wBAAb,aAAa;IAJzB,IAAA,eAAM,EAAC;QACJ,SAAS,EAAE,CAAC,2CAAmB,CAAC;QAChC,OAAO,EAAE,CAAC,2CAAmB,CAAC;KACjC,CAAC;GACW,aAAa,CAIzB"}

package/dist/winston/otel-log-format.d.ts

@@ -0,0 +1,29 @@
+import * as winston from 'winston';
+/**
+ * Winston format：自动注入 OTel trace.id / span.id 到每条日志
+ *
+ * 注入字段（符合 Elastic Common Schema）：
+ *   trace.id    — 32 位 hex，全局唯一链路 ID
+ *   span.id     — 16 位 hex，当前操作 Span ID
+ *   trace.flags — 采样标记（1=已采样, 0=未采样）
+ *
+ * 使用方式：
+ *   import { otelLogFormat } from '@rare0619/nestjs-tracing';
+ *
+ *   const format = winston.format.combine(
+ *     otelLogFormat(),         // ← 加入 format 链即可
+ *     winston.format.json(),
+ *   );
+ *
+ * 输出效果：
+ *   {
+ *     "message": "GET /api/user 200",
+ *     "trace.id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
+ *     "span.id": "1234567890abcdef",
+ *     "trace.flags": 1
+ *   }
+ *
+ * Kibana APM 自动识别 trace.id → Transaction 详情页 "View Logs" 一键跳转
+ */
+export declare const otelLogFormat: winston.Logform.FormatWrap;
+//# sourceMappingURL=otel-log-format.d.ts.map

package/dist/winston/otel-log-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-log-format.d.ts","sourceRoot":"","sources":["../../src/winston/otel-log-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,SAAS,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,aAAa,4BASxB,CAAC"}

package/dist/winston/otel-log-format.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.otelLogFormat = void 0;
+const winston = __importStar(require("winston"));
+const api_1 = require("@opentelemetry/api");
+/**
+ * Winston format：自动注入 OTel trace.id / span.id 到每条日志
+ *
+ * 注入字段（符合 Elastic Common Schema）：
+ *   trace.id    — 32 位 hex，全局唯一链路 ID
+ *   span.id     — 16 位 hex，当前操作 Span ID
+ *   trace.flags — 采样标记（1=已采样, 0=未采样）
+ *
+ * 使用方式：
+ *   import { otelLogFormat } from '@rare0619/nestjs-tracing';
+ *
+ *   const format = winston.format.combine(
+ *     otelLogFormat(),         // ← 加入 format 链即可
+ *     winston.format.json(),
+ *   );
+ *
+ * 输出效果：
+ *   {
+ *     "message": "GET /api/user 200",
+ *     "trace.id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
+ *     "span.id": "1234567890abcdef",
+ *     "trace.flags": 1
+ *   }
+ *
+ * Kibana APM 自动识别 trace.id → Transaction 详情页 "View Logs" 一键跳转
+ */
+exports.otelLogFormat = winston.format((info) => {
+    const activeSpan = api_1.trace.getSpan(api_1.context.active());
+    if (activeSpan) {
+        const spanCtx = activeSpan.spanContext();
+        info['trace.id'] = spanCtx.traceId;
+        info['span.id'] = spanCtx.spanId;
+        info['trace.flags'] = spanCtx.traceFlags;
+    }
+    return info;
+});
+//# sourceMappingURL=otel-log-format.js.map

package/dist/winston/otel-log-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel-log-format.js","sourceRoot":"","sources":["../../src/winston/otel-log-format.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iDAAmC;AACnC,4CAAoD;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACU,QAAA,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;IACjD,MAAM,UAAU,GAAG,WAAK,CAAC,OAAO,CAAC,aAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACnD,IAAI,UAAU,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;QACnC,IAAI,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;QACjC,IAAI,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+    "name": "@rare0619/nestjs-tracing",
+    "version": "1.2.0",
+    "description": "NestJS 全链路追踪插件（OpenTelemetry + Elastic APM）— 自动插桩、日志关联、跨服务传播、Monorepo 零配置",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./tracer": {
+            "types": "./dist/tracer.d.ts",
+            "default": "./dist/tracer.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist",
+        "prepublishOnly": "npm run clean && npm run build",
+        "test": "jest --forceExit --detectOpenHandles",
+        "test:cov": "jest --coverage --forceExit --detectOpenHandles"
+    },
+    "keywords": [
+        "nestjs",
+        "opentelemetry",
+        "tracing",
+        "elastic-apm",
+        "distributed-tracing",
+        "observability",
+        "monorepo"
+    ],
+    "author": "rare0619",
+    "license": "Apache-2.0",
+    "peerDependencies": {
+        "@opentelemetry/api": "^1.9.0",
+        "winston": "^3.0.0"
+    },
+    "peerDependenciesMeta": {
+        "winston": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "@opentelemetry/core": "^1.30.0",
+        "@opentelemetry/exporter-trace-otlp-proto": "^0.57.2",
+        "@opentelemetry/instrumentation-express": "^0.46.0",
+        "@opentelemetry/instrumentation-http": "^0.57.0",
+        "@opentelemetry/instrumentation-ioredis": "^0.61.0",
+        "@opentelemetry/instrumentation-pg": "^0.65.0",
+        "@opentelemetry/resources": "^1.30.0",
+        "@opentelemetry/sdk-node": "^0.57.0",
+        "@opentelemetry/semantic-conventions": "^1.30.0"
+    },
+    "devDependencies": {
+        "@nestjs/common": "^10.0.0",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/express": "^4.17.21",
+        "@types/jest": "^29.5.0",
+        "@types/node": "^20.11.0",
+        "express": "^4.18.0",
+        "jest": "^29.7.0",
+        "reflect-metadata": "^0.2.0",
+        "ts-jest": "^29.2.0",
+        "typescript": "^5.3.0",
+        "winston": "^3.17.0"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ]
+}