@application-kit/observability 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @application-kit/observability
 
+## 0.5.0
+
+### Minor Changes
+
+- 0f930bf: `metric-names.json` в пакете (вход `@application-kit/observability/metric-names.json`): имена и типы всех метрик
+  реестра — гистограмм HTTP и GraphQL и метрик процесса. По нему чарт платформы сверяет VMRule и дашборды, не
+  запуская код пакета; совпадение файла с реестром держит тест пакета.
+
+## 0.4.0
+
+### Minor Changes
+
+- 29b4378: Вход `/tracing` (только ESM): `startTracing({ esmHookedModules, instrumentations, resolveClientIp })` — OpenTelemetry
+  NodeSDK для `node --import` с OTLP gRPC-экспортёром, спанами HTTP-сервера без служебных путей и с `client.address`,
+  ESM-хуком строго по списку модулей и флашем на `beforeExit`; без endpoint'а коллектора не делает ничего.
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -24,6 +24,7 @@ Peer-зависимости: `@nestjs/common`, `@prometheus-io/client`; оста
 | `@application-kit/observability/http` | `resolveClientIp` — IP клиента за прокси | ничего |
 | `@application-kit/observability/logging` | опции nestjs-pino, request-id, support-id, служебные пути, токен логгера | `@opentelemetry/api`, `class-validator`, `class-transformer`; типы — `nestjs-pino`, `pino` |
 | `@application-kit/observability/metrics` | реестр, гистограммы HTTP и GraphQL, `GET /metrics`, хуки Fastify, сервер `/metrics` | `@nestjs/common`, `@prometheus-io/client`; типы — `fastify`, `@nestjs/platform-fastify` |
+| `@application-kit/observability/tracing` | `startTracing` — OpenTelemetry NodeSDK для `node --import`, только ESM | `@opentelemetry/sdk-node`, `@opentelemetry/instrumentation`, `@opentelemetry/instrumentation-http`, `@opentelemetry/exporter-trace-otlp-grpc`, `@opentelemetry/semantic-conventions` |
 
 Корневого входа нет: каждый вход несёт свои peer-зависимости, и лишнего потребитель не ставит.
 
@@ -38,6 +39,9 @@ Peer-зависимости: `@nestjs/common`, `@prometheus-io/client`; оста
   `start(key)` → `describe(key, document)` → `finish(key, hasErrors)`, где `key` — объект контекста запроса;
   `asMercuriusHook` оборачивает синхронный обработчик в async-хук Mercurius.
 - `DURATION_BUCKETS_SECONDS` — общие границы гистограмм, от 5 мс до 10 с.
+- `@application-kit/observability/metric-names.json` — имена и типы всех метрик реестра (обе гистограммы и метрики
+  процесса на Linux) для тех, кто строит по ним алерты и дашборды, не запуская код: чарт платформы сверяет с ним
+  VMRule и дашборды. Файл совпадает с реестром — это держит тест пакета; переименование метрики — major.
 
 Web-процесс подключает `MetricsHttpModule.forRoot({ publicRoute })` — реестр, обе гистограммы и `GET /metrics`
 (путь — `METRICS_ROUTE` входа `/logging`), — и вешает хуки после создания приложения: HTTP — `onResponse` Fastify
@@ -137,3 +141,38 @@ export class WebModule {}
 ```ts
 const clientIp = resolveClientIp(request, { trustedHeaders: ['cf-connecting-ip'] })
 ```
+
+## Трейсинг (`/tracing`)
+
+`startTracing({ esmHookedModules, instrumentations, resolveClientIp })` поднимает OpenTelemetry NodeSDK: OTLP gRPC-экспортёр,
+спаны HTTP-сервера без служебных путей (`isInfrastructurePath` входа `/logging`) и с `client.address` корневого спана,
+хук import-in-the-middle строго по списку модулей, флаш спанов на `beforeExit`. Endpoint, sampling, `service.name` и
+атрибуты ресурса SDK читает из стандартных `OTEL_*`; без `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` (или
+`OTEL_EXPORTER_OTLP_ENDPOINT`) функция не делает ничего — ни хука, ни инструментаций — и отдаёт `undefined`.
+
+Вызов — в отдельном файле, который бандлер собирает в свой выход и который процесс грузит флагом рантайма
+`node --import ./tracing.mjs`: инструментации патчат модули в момент загрузки, а ESM выполняет все `import` бандла до
+его первой строки, поэтому импорт из кода приложения опоздал бы. Вход только ESM — `module.register` есть лишь у
+ESM-загрузчика.
+
+- `esmHookedModules` — пакеты, которые бандл импортирует как ESM (например `kafkajs`): до них не дотягивается
+  require-in-the-middle. Хук без списка обернул бы и чанки самого бандла и порвал бы им live-binding.
+- `instrumentations` — фабрика инструментаций продукта (фреймворк, драйвер БД, брокер): конструктор инструментации
+  сразу патчит модуль, поэтому вызывается фабрика, только когда трейсинг включён.
+- `resolveClientIp` — резолвер адреса клиента; дефолт — `resolveClientIp` входа `/http` без доверенных заголовков.
+
+```ts
+// src/tracing.ts → vite build --ssr src/tracing.ts → node --import ./tracing.mjs ./web.mjs
+startTracing({
+  esmHookedModules: ['kafkajs'],
+  instrumentations: () => [
+    new FastifyOtelInstrumentation({ registerOnInitialization: true }),
+    new PgInstrumentation(),
+    new KafkaJsInstrumentation(),
+  ],
+  resolveClientIp: (request) => resolveClientIp(request, { trustedHeaders: ['cf-connecting-ip'] }),
+})
+```
+
+Версии `@opentelemetry/*` с номером `0.x` выходят одним релизом и между собой совместимы только в пределах одного минора:
+`sdk-node`, `instrumentation`, `instrumentation-http` и `exporter-trace-otlp-grpc` ставятся одной версией `0.221.x`.

package/dist/esm/tracing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './start-tracing.js';
+export * from './tracing-options.interface.js';

package/dist/esm/tracing/index.js

@@ -0,0 +1,2 @@
+export * from './start-tracing.js';
+export * from './tracing-options.interface.js';

package/dist/esm/tracing/start-tracing.d.ts

@@ -0,0 +1,3 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import type { TracingOptionsInterface } from './tracing-options.interface.js';
+export declare const startTracing: (options: TracingOptionsInterface) => NodeSDK | undefined;

package/dist/esm/tracing/start-tracing.js

@@ -0,0 +1,55 @@
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ATTR_CLIENT_ADDRESS } from '@opentelemetry/semantic-conventions';
+import { register } from 'node:module';
+import nodeProcess from 'node:process';
+import { resolveClientIp } from '../http/resolve-client-ip.js';
+import { isInfrastructurePath } from '../logging/infrastructure-paths.js';
+const withoutQuery = (url) => {
+    const queryStart = url.indexOf('?');
+    return queryStart === -1 ? url : url.slice(0, queryStart);
+};
+const isServiceRequest = (request) => request.url !== undefined
+    && isInfrastructurePath(withoutQuery(request.url));
+const createHttpInstrumentation = (clientIp = resolveClientIp) => {
+    const clientAddressAttributes = (request) => {
+        const address = clientIp(request);
+        return address === '' ? {} : { [ATTR_CLIENT_ADDRESS]: address };
+    };
+    return new HttpInstrumentation({
+        ignoreIncomingRequestHook: isServiceRequest,
+        startIncomingSpanHook: clientAddressAttributes,
+    });
+};
+const flushSpans = async (sdk) => {
+    try {
+        await sdk.shutdown();
+    }
+    catch {
+    }
+};
+const tracesEndpoint = () => {
+    const { env } = nodeProcess;
+    return (env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? env.OTEL_EXPORTER_OTLP_ENDPOINT ?? '').trim();
+};
+export const startTracing = (options) => {
+    if (tracesEndpoint() === '') {
+        return undefined;
+    }
+    register('@opentelemetry/instrumentation/hook.mjs', import.meta.url, {
+        data: { include: options.esmHookedModules },
+    });
+    const sdk = new NodeSDK({
+        instrumentations: [
+            createHttpInstrumentation(options.resolveClientIp),
+            ...options.instrumentations?.() ?? [],
+        ],
+        traceExporter: new OTLPTraceExporter(),
+    });
+    sdk.start();
+    nodeProcess.once('beforeExit', () => {
+        void flushSpans(sdk);
+    });
+    return sdk;
+};

package/dist/esm/tracing/tracing-options.interface.d.ts

@@ -0,0 +1,8 @@
+import type { Instrumentation } from '@opentelemetry/instrumentation';
+import type { ClientIpResolver } from '../logging/pino-logger-options.interface.js';
+export type InstrumentationsFactory = () => Instrumentation[];
+export interface TracingOptionsInterface {
+    readonly esmHookedModules: readonly string[];
+    readonly instrumentations?: InstrumentationsFactory;
+    readonly resolveClientIp?: ClientIpResolver;
+}

package/dist/esm/tracing/tracing-options.interface.js

@@ -0,0 +1 @@
+export {};

package/metric-names.json

@@ -0,0 +1,142 @@
+[
+  {
+    "name": "graphql_operation_duration_seconds",
+    "type": "histogram"
+  },
+  {
+    "name": "http_request_duration_seconds",
+    "type": "histogram"
+  },
+  {
+    "name": "nodejs_active_handles",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_active_handles_total",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_active_requests",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_active_requests_total",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_active_resources",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_active_resources_total",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_max_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_mean_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_min_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_p50_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_p90_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_p99_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_lag_stddev_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_eventloop_utilization_histogram",
+    "type": "histogram"
+  },
+  {
+    "name": "nodejs_eventloop_utilization_summary",
+    "type": "summary"
+  },
+  {
+    "name": "nodejs_external_memory_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_gc_duration_seconds",
+    "type": "histogram"
+  },
+  {
+    "name": "nodejs_heap_size_total_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_heap_size_used_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_heap_space_size_available_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_heap_space_size_total_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_heap_space_size_used_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "nodejs_version_info",
+    "type": "gauge"
+  },
+  {
+    "name": "process_cpu_seconds_total",
+    "type": "counter"
+  },
+  {
+    "name": "process_cpu_system_seconds_total",
+    "type": "counter"
+  },
+  {
+    "name": "process_cpu_user_seconds_total",
+    "type": "counter"
+  },
+  {
+    "name": "process_heap_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "process_max_fds",
+    "type": "gauge"
+  },
+  {
+    "name": "process_open_fds",
+    "type": "gauge"
+  },
+  {
+    "name": "process_resident_memory_bytes",
+    "type": "gauge"
+  },
+  {
+    "name": "process_start_time_seconds",
+    "type": "gauge"
+  },
+  {
+    "name": "process_virtual_memory_bytes",
+    "type": "gauge"
+  }
+]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@application-kit/observability",
-  "version": "0.3.1",
-  "description": "Наблюдаемость NestJS-процесса: метрики Prometheus и RED-гистограммы, health-чеки и пробы, опции pino с request-id и trace-контекстом, логирование CQRS-шин, реальный IP клиента за прокси",
+  "version": "0.5.0",
+  "description": "Наблюдаемость NestJS-процесса: метрики Prometheus и RED-гистограммы, health-чеки и пробы, опции pino с request-id и trace-контекстом, логирование CQRS-шин, реальный IP клиента за прокси, трейсинг OpenTelemetry",
   "keywords": [
     "cqrs",
     "health",
@@ -9,9 +9,11 @@
     "metrics",
     "nestjs",
     "observability",
+    "opentelemetry",
     "pino",
     "prometheus",
-    "terminus"
+    "terminus",
+    "tracing"
   ],
   "homepage": "https://gitlab.com/application-kit/application-kit/-/tree/main/packages/observability",
   "bugs": "https://gitlab.com/application-kit/application-kit/-/issues",
@@ -87,6 +89,7 @@
         "default": "./dist/cjs/logging/index.js"
       }
     },
+    "./metric-names.json": "./metric-names.json",
     "./metrics": {
       "import": {
         "types": "./dist/esm/metrics/index.d.ts",
@@ -97,16 +100,23 @@
         "default": "./dist/cjs/metrics/index.js"
       }
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./tracing": {
+      "import": {
+        "types": "./dist/esm/tracing/index.d.ts",
+        "default": "./dist/esm/tracing/index.js"
+      }
+    }
   },
   "main": "./dist/cjs/metrics/index.js",
   "module": "./dist/esm/metrics/index.js",
   "types": "./dist/cjs/metrics/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "metric-names.json"
   ],
   "scripts": {
-    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/cqrs && node ../../scripts/barrels.mjs create ./src/health --entry-only=cli,graphql && node ../../scripts/barrels.mjs create ./src/http && node ../../scripts/barrels.mjs create ./src/logging && node ../../scripts/barrels.mjs create ./src/metrics && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
+    "build": "rm -rf ./dist && node ../../scripts/barrels.mjs create ./src/cqrs && node ../../scripts/barrels.mjs create ./src/health --entry-only=cli,graphql && node ../../scripts/barrels.mjs create ./src/http && node ../../scripts/barrels.mjs create ./src/logging && node ../../scripts/barrels.mjs create ./src/metrics && node ../../scripts/barrels.mjs create ./src/tracing && tsc --project tsconfig.build.json && tsc --project tsconfig.build.cjs.json && node ../../scripts/barrels.mjs clean ./src && node ../../scripts/mark-cjs.mjs ./dist/cjs",
     "lint:tsc": "tsc --noEmit --pretty --project .",
     "test:mutation": "stryker run",
     "test:unit": "vitest run"
@@ -124,6 +134,11 @@
     "@nestjs/testing": "^11.2.7",
     "@nestjs/typeorm": "^11.0.3",
     "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
+    "@opentelemetry/instrumentation": "^0.221.0",
+    "@opentelemetry/instrumentation-http": "^0.221.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
     "@prometheus-io/client": "^0.16.0",
     "@stryker-mutator/core": "^10.0.0",
     "@stryker-mutator/vitest-runner": "^10.0.0",
@@ -149,6 +164,11 @@
     "@nestjs/terminus": "^11.0.0",
     "@nestjs/typeorm": "^11.0.0",
     "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
+    "@opentelemetry/instrumentation": "^0.221.0",
+    "@opentelemetry/instrumentation-http": "^0.221.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0",
     "@prometheus-io/client": "^0.16.0",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.15.1",
@@ -178,6 +198,21 @@
     "@opentelemetry/api": {
       "optional": true
     },
+    "@opentelemetry/exporter-trace-otlp-grpc": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-http": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-node": {
+      "optional": true
+    },
+    "@opentelemetry/semantic-conventions": {
+      "optional": true
+    },
     "class-transformer": {
       "optional": true
     },