@generazioneai/telemetry

中文文档
0.2.0发布于 2026/11/11UNLICENSEDTypeScriptCommonJS近 30 天下载 2298

Osservabilità comune dei servizi Node (ADR-013): OpenTelemetry con esportazione OTLP, JsonLogger con trace_id, span dei comandi NATS con traceparent negli header, attributi a lista bianca e redazione dei dati personali.

原始使用文档
文档目录4 节
  1. Uso
  2. Cosa fa
  3. Compatibilità delle versioni OpenTelemetry
  4. Prove

@generazioneai/telemetry

Osservabilità comune dei servizi Node (ADR-013, spec «Fondamenta enterprise» §5): tracce e metriche OpenTelemetry verso il collector, log JSON con trace_id, span dei comandi NATS, nessun dato personale.

npm i @generazioneai/telemetry

Uso

// main.ts — PRIMA riga
import '@generazioneai/telemetry/register';
import { createLogger } from '@generazioneai/telemetry/logger';

const app = await NestFactory.create(AppModule, { logger: createLogger('hr') });

// app.module.ts
TelemetryModule.forRoot({ service: 'hr' })
VariabileValoriDi serie
OTEL_EXPORTER_OTLP_ENDPOINTbase OTLP/HTTPhttp://otel-collector.observability:4318 (in sviluppo locale: vuota); vuota = spento (il processo non carica l'SDK, nessuna connessione)
TELEMETRY_MODEon0.2 (decisione del 2026-11-10): accesa se c'è l'endpoint. off conta solo in sviluppo locale e nei test (SKILLERA_ENV dev/local o NODE_ENV development/test, fuori da un cluster); altrove si ignora con un avviso
OTEL_SERVICE_NAMEnomename del package.json (senza scope)
SKILLERA_ENV→ deployment.environment
LOG_FORMATtext | jsontext
APP_LOGGER_LEVELlog,error,warn,debug,verbose | nonelog,error,warn (fatal segue error)
TELEMETRY_SAMPLE_RATIO0..11 (il campionamento in coda è del collector)
OTEL_METRIC_EXPORT_INTERVALms60000

Impostare OTEL_SERVICE_NAME nei manifest: register parte prima di Nest e non conosce l'opzione service del modulo.

Cosa fa

  • /register: Node SDK con OTLP/HTTP per tracce e metriche; strumentazioni HTTP (senza health/metrics), pg, ioredis, Prisma (le ultime tre opzionali). Nessun gestore di SIGTERM: lo spegnimento ordinato lo fa TelemetryModule (o beforeExit).
  • NATS: l'interceptor globale (solo contesto rpc) apre nats.server <cmd> (kind consumer) come figlio del traceparent negli header, mette cmd e juridicalId nel contesto dei log, conta nats_server_requests_total{cmd,outcome} e nats_server_request_duration_seconds{cmd}. juridicalId viene dall'header Gen-Tenant o da auth.juridicalId/auth.tenantId/dto.juridicalId, solo se è un UUID.
  • Invio: traceparentHeadersHook scrive traceparent negli header. TelemetryModule.forRoot lo registra con setNatsHeadersHook di @generazioneai/authz ≥ 0.7 se c'è (altrimenti nulla); si può passare il modulo con authz: … o spegnere con authz: false. Per gli eventi di JetStream ci pensa @generazioneai/events con injectTraceContext/extractTraceContext.
  • Log (JsonLogger): level, ts, service, msg, trace_id, span_id, cmd, juridicalId (+ context, err, campi del messaggio-oggetto, mai in conflitto con quelli del contratto).
  • Dati personali (decisione 35): gli span escono da SanitizingSpanExporter, che tiene solo gli attributi della lista bianca (ALLOWED_ATTRIBUTES: metodo, rotta come modello, comando, esito, durata, dimensioni, id di azienda UUID, db.statement senza letterali, redis solo il comando), stato senza messaggio, IP solo come hash (client.ip_hash). redact()/maskString() (usate dal logger) azzerano i valori di chiavi come authorization, cookie, body, dto, email, *name, fiscalCode, iban, password, *token e mascherano nel testo email, codici fiscali (anche omocodici), IBAN, JWT, Bearer ….

Compatibilità delle versioni OpenTelemetry

Le strumentazioni sono fissate alla famiglia 0.219 con @opentelemetry/api 1.9 (la 0.300 richiede api ≥ 1.10, che gli SDK 2.x non accettano ancora). Il servizio non deve avere un proprio @opentelemetry/api diverso.

Prove

npm test. La prova dell'SDK acceso gira in un processo Node figlio (le strumentazioni usano import() dinamici, che Jest non esegue) e costruisce il pacchetto in .test-dist/.

版本与发布记录

@generazioneai/telemetry 共发布 4 个版本,首次发布于 2026/10/26;过去 12 个月发布了 4 个版本。

版本发布日期距今
0.2.0latest2026/11/114 天前
0.1.02026/10/2720 天前
0.0.12026/10/2620 天前
0.0.0-stage2026/10/2620 天前

关于 @generazioneai/telemetry 的常见问题

@generazioneai/telemetry 是什么?

Osservabilità comune dei servizi Node (ADR-013): OpenTelemetry con esportazione OTLP, JsonLogger con trace_id, span dei comandi NATS con traceparent negli header, attributi a lista bianca e redazione dei dati personali.

如何安装 @generazioneai/telemetry?

在项目目录运行 npm install @generazioneai/telemetry,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:rxjs(^7.8.0)、@nestjs/core(^11.0.0 || ^12.0.0)、@nestjs/common(^11.0.0 || ^12.0.0)、reflect-metadata(^0.2.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@generazioneai/telemetry 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@generazioneai/telemetry 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@generazioneai/telemetry 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@generazioneai/telemetry 可以商用吗?

@generazioneai/telemetry 使用 UNLICENSED 许可。作者声明为 UNLICENSED,即不授予公开使用许可(与公共领域的 Unlicense 不同)。使用前需获得作者授权。以上为概括,不构成法律意见,请以许可原文为准。

@generazioneai/telemetry 的下载量有多少?

根据 npm 官方下载统计,@generazioneai/telemetry 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,298 次,日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@generazioneai/telemetry 还在维护吗?

最新版本 0.2.0 发布于 2026/11/11(4 天前);至今共发布 4 个版本,其中过去 12 个月发布了 4 个;首次发布于 2026/10/26。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。