@rsdk/core 5.11.5 → 5.11.6

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.
Files changed (39) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/dist/index.d.ts +1 -1
  3. package/dist/index.js +2 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/logging/logger-initializing.module.js +3 -2
  6. package/dist/logging/logger-initializing.module.js.map +1 -1
  7. package/dist/logging/otel-logs.transport.d.ts +12 -0
  8. package/dist/logging/otel-logs.transport.js +39 -0
  9. package/dist/logging/otel-logs.transport.js.map +1 -0
  10. package/dist/metrics/metrics-http.service.d.ts +13 -0
  11. package/dist/metrics/metrics-http.service.js +98 -0
  12. package/dist/metrics/metrics-http.service.js.map +1 -0
  13. package/dist/metrics/metrics.config.d.ts +4 -0
  14. package/dist/metrics/metrics.config.js +32 -0
  15. package/dist/metrics/metrics.config.js.map +1 -1
  16. package/dist/metrics/metrics.module.js +2 -0
  17. package/dist/metrics/metrics.module.js.map +1 -1
  18. package/dist/platform.context.js +5 -0
  19. package/dist/platform.context.js.map +1 -1
  20. package/dist/tracing/opentelemetry/index.d.ts +1 -0
  21. package/dist/tracing/opentelemetry/index.js +3 -0
  22. package/dist/tracing/opentelemetry/index.js.map +1 -1
  23. package/dist/tracing/opentelemetry/opentelemetry.instrumentation.d.ts +57 -0
  24. package/dist/tracing/opentelemetry/opentelemetry.instrumentation.js +118 -0
  25. package/dist/tracing/opentelemetry/opentelemetry.instrumentation.js.map +1 -0
  26. package/package.json +2 -2
  27. package/src/index.ts +8 -1
  28. package/src/logging/logger-factory.lifecycle.spec.ts +21 -0
  29. package/src/logging/logger-initializing.module.spec.ts +7 -8
  30. package/src/logging/logger-initializing.module.ts +3 -2
  31. package/src/logging/otel-logs.transport.spec.ts +76 -0
  32. package/src/logging/otel-logs.transport.ts +41 -0
  33. package/src/metrics/metrics-http.service.ts +115 -0
  34. package/src/metrics/metrics.config.ts +32 -1
  35. package/src/metrics/metrics.module.ts +2 -0
  36. package/src/platform.context.ts +6 -0
  37. package/src/tracing/opentelemetry/index.ts +5 -0
  38. package/src/tracing/opentelemetry/opentelemetry.instrumentation.spec.ts +114 -0
  39. package/src/tracing/opentelemetry/opentelemetry.instrumentation.ts +194 -0
package/src/index.ts CHANGED
@@ -6,7 +6,14 @@ export { Manifest } from './manifest/manifest';
6
6
 
7
7
  export { ProtocolDetector } from './transport/protocol.detector';
8
8
 
9
- export { TracingHeaderMappings, Span, NoSpan } from './tracing';
9
+ export {
10
+ TracingHeaderMappings,
11
+ Span,
12
+ NoSpan,
13
+ OtelInstrumentation,
14
+ OtelSpanKind,
15
+ OtelSpanOptions,
16
+ } from './tracing';
10
17
 
11
18
  export {
12
19
  FileSystemCheckOptions,
@@ -88,4 +88,25 @@ describe('LoggerFactory — жизненный цикл worker-транспор
88
88
 
89
89
  expect(created.end).toHaveBeenCalled();
90
90
  });
91
+
92
+ it('на shutdown держит процесс, пока воркер не закрылся', async () => {
93
+ LoggerFactory.reconfigure({ ...base, transport: transport(1) });
94
+ const created = transportSpy.mock.results[0].value;
95
+ const setTimeoutSpy = jest.spyOn(globalThis, 'setTimeout');
96
+ const clearTimeoutSpy = jest.spyOn(globalThis, 'clearTimeout');
97
+
98
+ const shutdown = LoggerFactory.shutdown(1000);
99
+ const timer = setTimeoutSpy.mock.results[0].value as NodeJS.Timeout;
100
+
101
+ expect(timer.hasRef()).toBe(true);
102
+ expect(created.end).toHaveBeenCalled();
103
+
104
+ const [, onClose] = created.on.mock.calls.find(
105
+ ([event]: [string]) => event === 'close',
106
+ );
107
+ onClose();
108
+ await shutdown;
109
+
110
+ expect(clearTimeoutSpy).toHaveBeenCalledWith(timer);
111
+ });
91
112
  });
@@ -51,20 +51,19 @@ function targetOf(delivery: Delivery, name: string): Delivery | undefined {
51
51
  return delivery.transport?.targets?.find((t: Delivery) => t.target === name);
52
52
  }
53
53
 
54
- /** OTEL-таргет — это pipeline [time-transform → pino-opentelemetry-transport]. */
54
+ const isOtelStage = (s: Delivery): boolean =>
55
+ /otel-logs\.transport\.js$/.test(s.target);
56
+
57
+ /** OTEL-таргет — это pipeline [time-transform → otel-logs.transport]. */
55
58
  function otelPipeline(delivery: Delivery): Delivery | undefined {
56
59
  return delivery.transport?.targets?.find((t: Delivery) =>
57
- t.pipeline?.some(
58
- (s: Delivery) => s.target === 'pino-opentelemetry-transport',
59
- ),
60
+ t.pipeline?.some(isOtelStage),
60
61
  );
61
62
  }
62
63
 
63
64
  /** Стейдж OTEL-экспортёра внутри pipeline. */
64
65
  function otelStage(delivery: Delivery): Delivery | undefined {
65
- return otelPipeline(delivery)?.pipeline?.find(
66
- (s: Delivery) => s.target === 'pino-opentelemetry-transport',
67
- );
66
+ return otelPipeline(delivery)?.pipeline?.find(isOtelStage);
68
67
  }
69
68
 
70
69
  describe('LoggerInitializingModule — выбор доставки', () => {
@@ -130,7 +129,7 @@ describe('LoggerInitializingModule — выбор доставки', () => {
130
129
 
131
130
  expect(pipeline).toHaveLength(2);
132
131
  expect(pipeline[0].target).toMatch(/otel-time\.transform\.js$/);
133
- expect(pipeline[1].target).toBe('pino-opentelemetry-transport');
132
+ expect(pipeline[1].target).toMatch(/otel-logs\.transport\.js$/);
134
133
  });
135
134
 
136
135
  it('httpEndpoint задан → transport (stdout + http)', () => {
@@ -12,10 +12,11 @@ import pino, {
12
12
  import { LoggingConfig } from './logging.config';
13
13
 
14
14
  /**
15
- * Абсолютный путь к скомпилированному pipeline-трансформу (рядом в dist).
15
+ * Абсолютные пути к скомпилированным шагам OTEL-pipeline (рядом в dist).
16
16
  * Воркер pino грузит таргет по пути, поэтому ссылаемся на .js, а не на модуль.
17
17
  */
18
18
  const OTEL_TIME_TRANSFORM = path.join(__dirname, 'otel-time.transform.js');
19
+ const OTEL_LOGS_TRANSPORT = path.join(__dirname, 'otel-logs.transport.js');
19
20
 
20
21
  @Module({})
21
22
  export class LoggerInitializingModule implements OnApplicationShutdown {
@@ -138,7 +139,7 @@ export class LoggerInitializingModule implements OnApplicationShutdown {
138
139
  level: config.level,
139
140
  pipeline: [
140
141
  { target: OTEL_TIME_TRANSFORM },
141
- { target: 'pino-opentelemetry-transport', options },
142
+ { target: OTEL_LOGS_TRANSPORT, options },
142
143
  ],
143
144
  };
144
145
  }
@@ -0,0 +1,76 @@
1
+ import { once } from 'node:events';
2
+ import { Writable } from 'node:stream';
3
+ import createOtelTransport from 'pino-opentelemetry-transport';
4
+
5
+ import buildOtelLogsTransport from './otel-logs.transport';
6
+
7
+ jest.mock('pino-opentelemetry-transport', () => jest.fn());
8
+
9
+ const options = { loggerName: 'app', serviceVersion: '1.0.0' };
10
+ const noop = (): void => {};
11
+
12
+ /** Транспорт, который закрывается, только когда тест вызовет release. */
13
+ function fakeTransport(): {
14
+ stream: Writable;
15
+ written: string[];
16
+ release: () => void;
17
+ } {
18
+ const written: string[] = [];
19
+ let release = noop;
20
+
21
+ const stream = new Writable({
22
+ write(chunk: Buffer, _encoding, callback): void {
23
+ written.push(chunk.toString());
24
+ callback();
25
+ },
26
+ final(callback): void {
27
+ release = (): void => callback();
28
+ },
29
+ });
30
+
31
+ return { stream, written, release: () => release() };
32
+ }
33
+
34
+ describe('otel-logs.transport', () => {
35
+ it('передает опции в pino-opentelemetry-transport', async () => {
36
+ const fake = fakeTransport();
37
+
38
+ jest.mocked(createOtelTransport).mockResolvedValue(fake.stream as any);
39
+ await buildOtelLogsTransport(options);
40
+
41
+ expect(createOtelTransport).toHaveBeenCalledWith(options);
42
+ });
43
+
44
+ it('завершается только после close транспорта', async () => {
45
+ const fake = fakeTransport();
46
+
47
+ jest.mocked(createOtelTransport).mockResolvedValue(fake.stream as any);
48
+
49
+ const stream = await buildOtelLogsTransport(options);
50
+ const finished = jest.fn();
51
+
52
+ stream.on('finish', finished);
53
+ stream.end('{"msg":"x"}\n');
54
+ await new Promise(setImmediate);
55
+
56
+ expect(fake.written).toEqual(['{"msg":"x"}\n']);
57
+ expect(finished).not.toHaveBeenCalled();
58
+
59
+ fake.release();
60
+ await once(stream, 'finish');
61
+ });
62
+
63
+ it('пробрасывает ошибку транспорта', async () => {
64
+ const fake = fakeTransport();
65
+
66
+ jest.mocked(createOtelTransport).mockResolvedValue(fake.stream as any);
67
+
68
+ const stream = await buildOtelLogsTransport(options);
69
+ const error = new Error('export failed');
70
+
71
+ fake.stream.destroy(error);
72
+ const [received] = await once(stream, 'error');
73
+
74
+ expect(received).toBe(error);
75
+ });
76
+ });
@@ -0,0 +1,41 @@
1
+ import { Writable } from 'node:stream';
2
+ import createOtelTransport from 'pino-opentelemetry-transport';
3
+
4
+ type OtelTransportOptions = Parameters<typeof createOtelTransport>[0];
5
+
6
+ /**
7
+ * Последний шаг OTEL-pipeline вместо pino-opentelemetry-transport. pino
8
+ * считает pipeline закрытым по 'finish' последнего шага, а транспорт
9
+ * отправляет последний батч позже, в асинхронном close. thread-stream по
10
+ * закрытию pipeline сразу завершает воркер, и логи перед остановкой
11
+ * терялись. Обертка завершается только после 'close' транспорта.
12
+ */
13
+ export default async function buildOtelLogsTransport(
14
+ options: OtelTransportOptions,
15
+ ): Promise<Writable> {
16
+ const transport = await createOtelTransport(options);
17
+
18
+ const stream = new Writable({
19
+ write(chunk: Buffer, _encoding, callback): void {
20
+ if (transport.write(chunk)) {
21
+ callback();
22
+ } else {
23
+ transport.once('drain', () => callback());
24
+ }
25
+ },
26
+ final(callback): void {
27
+ if (transport.closed) {
28
+ callback();
29
+
30
+ return;
31
+ }
32
+
33
+ transport.once('close', () => callback());
34
+ transport.end();
35
+ },
36
+ });
37
+
38
+ transport.on('error', (error) => stream.destroy(error));
39
+
40
+ return stream;
41
+ }
@@ -0,0 +1,115 @@
1
+ import { Injectable, type OnApplicationShutdown } from '@nestjs/common';
2
+ import {
3
+ createServer,
4
+ type IncomingMessage,
5
+ type Server,
6
+ type ServerResponse,
7
+ } from 'node:http';
8
+ import { register } from 'prom-client';
9
+
10
+ import { ILogger, InjectLogger } from '../logging';
11
+
12
+ import { MetricsModuleConfig } from './metrics.config';
13
+
14
+ /**
15
+ * Приводит путь к виду с ведущим слешем и без слеша в конце,
16
+ * чтобы `metrics`, `/metrics` и `/metrics/` считались одним путем
17
+ */
18
+ const normalizePath = (path: string): string => {
19
+ const trimmed = path.replace(/\/+$/, '');
20
+
21
+ return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
22
+ };
23
+
24
+ @Injectable()
25
+ export class MetricsHttpService implements OnApplicationShutdown {
26
+ private server?: Server | undefined;
27
+
28
+ constructor(
29
+ @InjectLogger(MetricsHttpService)
30
+ private readonly logger: ILogger,
31
+ private readonly config: MetricsModuleConfig,
32
+ ) {}
33
+
34
+ async start(): Promise<void> {
35
+ if (this.server) {
36
+ throw new Error('Metrics http server is already running');
37
+ }
38
+
39
+ const server = createServer((req, res) => {
40
+ this.handleRequest(req, res).catch((error) => {
41
+ this.logger.error('Metrics http handler error', error as Error);
42
+
43
+ if (!res.headersSent) {
44
+ res.writeHead(500, { 'Content-Type': 'text/plain' });
45
+ }
46
+ res.end('Internal Server Error');
47
+ });
48
+ });
49
+
50
+ await new Promise<void>((resolve, reject) => {
51
+ server.once('error', reject);
52
+ server.listen(
53
+ this.config.metricsHttpPort,
54
+ this.config.metricsHttpHost,
55
+ () => {
56
+ server.off('error', reject);
57
+ resolve();
58
+ },
59
+ );
60
+ });
61
+
62
+ // Ошибки запуска отклоняют start(), а после запуска их достаточно логировать
63
+ server.on('error', (error) =>
64
+ this.logger.error('Metrics http server error', error),
65
+ );
66
+ this.server = server;
67
+
68
+ this.logger.info(
69
+ `Metrics http server listening on ${this.config.metricsHttpHost}:${this.config.metricsHttpPort}`,
70
+ );
71
+ }
72
+
73
+ async stop(): Promise<void> {
74
+ const server = this.server;
75
+
76
+ if (!server) {
77
+ return;
78
+ }
79
+
80
+ await new Promise<void>((resolve, reject) => {
81
+ server.close((error) => (error ? reject(error) : resolve()));
82
+ });
83
+
84
+ this.server = undefined;
85
+ this.logger.info('Metrics http server stopped');
86
+ }
87
+
88
+ async onApplicationShutdown(): Promise<void> {
89
+ await this.stop();
90
+ }
91
+
92
+ private async handleRequest(
93
+ req: IncomingMessage,
94
+ res: ServerResponse,
95
+ ): Promise<void> {
96
+ const { pathname } = new URL(req.url ?? '/', 'http://localhost');
97
+
98
+ if (
99
+ req.method === 'GET' &&
100
+ normalizePath(pathname) === normalizePath(this.config.metricsHttpPath)
101
+ ) {
102
+ const metrics = await register.metrics();
103
+
104
+ res.writeHead(200, {
105
+ 'Content-Type': register.contentType,
106
+ 'Content-Length': Buffer.byteLength(metrics),
107
+ });
108
+ res.end(metrics);
109
+ return;
110
+ }
111
+
112
+ res.writeHead(404, { 'Content-Type': 'text/plain' });
113
+ res.end('Not Found');
114
+ }
115
+ }
@@ -1,4 +1,11 @@
1
- import { BoolParser, Config, ConfigSection, Property } from '../config';
1
+ import {
2
+ BoolParser,
3
+ Config,
4
+ ConfigSection,
5
+ IntParser,
6
+ Property,
7
+ StringParser,
8
+ } from '../config';
2
9
  import { ConfigTag } from '../config/config.const';
3
10
 
4
11
  @ConfigSection({
@@ -17,4 +24,28 @@ export class MetricsModuleConfig extends Config {
17
24
  description: 'Indicates that default Node.js metrics should be included',
18
25
  })
19
26
  includeDefault!: boolean;
27
+
28
+ @Property('METRICS_HTTP_ENABLED', new BoolParser(), {
29
+ defaultValue: false,
30
+ description: 'Indicates that http metrics server should be enabled',
31
+ })
32
+ metricsHttpEnabled!: boolean;
33
+
34
+ @Property('METRICS_HTTP_HOST', new StringParser(), {
35
+ defaultValue: '0.0.0.0',
36
+ description: 'Http metrics server host',
37
+ })
38
+ metricsHttpHost!: string;
39
+
40
+ @Property('METRICS_HTTP_PORT', new IntParser(), {
41
+ defaultValue: 9464,
42
+ description: 'Http metrics server port',
43
+ })
44
+ metricsHttpPort!: number;
45
+
46
+ @Property('METRICS_HTTP_PATH', new StringParser(), {
47
+ defaultValue: '/metrics',
48
+ description: 'Http metrics server endpoint',
49
+ })
50
+ metricsHttpPath!: string;
20
51
  }
@@ -7,6 +7,7 @@ import { METRIC_RSDK_METADATA_SCOPE } from './metadata/constants';
7
7
  import type { MetricRsdkMetadata } from './metadata';
8
8
  import { MetricStorage } from './metric.storage';
9
9
  import { MetricInitializingModule } from './metric-initializing.module';
10
+ import { MetricsHttpService } from './metrics-http.service';
10
11
  import type { AnyMetric, MetricsModuleOptions } from './types';
11
12
 
12
13
  /**
@@ -42,6 +43,7 @@ export class MetricsModule {
42
43
  provide: MetricStorage,
43
44
  useValue: new MetricStorage(),
44
45
  },
46
+ MetricsHttpService,
45
47
  ],
46
48
  exports: [MetricStorage],
47
49
  imports: [MetricInitializingModule],
@@ -11,6 +11,8 @@ import { APP_NAME_PATTERN } from './app-metadata/app-name.const';
11
11
  import { InvalidAppNameException } from './app-metadata/exceptions';
12
12
  import { ConfigMetadataProvider } from './config/metadata/config-metadata.provider';
13
13
  import { Manifest } from './manifest/manifest';
14
+ import { MetricsModuleConfig } from './metrics/metrics.config';
15
+ import { MetricsHttpService } from './metrics/metrics-http.service';
14
16
  import { assertAppName } from './app-metadata';
15
17
  import type { Config, ConfigContext, SectionMetadata } from './config';
16
18
  import { ContextAggregator } from './context.aggregator';
@@ -212,6 +214,10 @@ export class PlatformContext {
212
214
  await app.init();
213
215
  }
214
216
 
217
+ if (app.get(MetricsModuleConfig, { strict: false }).metricsHttpEnabled) {
218
+ await app.get(MetricsHttpService, { strict: false }).start();
219
+ }
220
+
215
221
  if (this.microservices.size > 0) {
216
222
  for (const [microservice, transport] of this.microservices) {
217
223
  await microservice.listen();
@@ -1 +1,6 @@
1
1
  export * from './decorators';
2
+ export {
3
+ OtelInstrumentation,
4
+ OtelSpanKind,
5
+ OtelSpanOptions,
6
+ } from './opentelemetry.instrumentation';
@@ -0,0 +1,114 @@
1
+ import { context, SpanStatusCode, trace } from '@opentelemetry/api';
2
+ import {
3
+ InMemorySpanExporter,
4
+ NodeTracerProvider,
5
+ SimpleSpanProcessor,
6
+ } from '@opentelemetry/sdk-trace-node';
7
+
8
+ import { OtelInstrumentation } from './opentelemetry.instrumentation';
9
+
10
+ describe('OtelInstrumentation', () => {
11
+ const exporter = new InMemorySpanExporter();
12
+ const provider = new NodeTracerProvider({
13
+ spanProcessors: [new SimpleSpanProcessor(exporter)],
14
+ });
15
+ const otel = new OtelInstrumentation('test');
16
+
17
+ beforeAll(() => {
18
+ provider.register();
19
+ });
20
+
21
+ afterEach(() => {
22
+ exporter.reset();
23
+ });
24
+
25
+ afterAll(async () => {
26
+ await provider.shutdown();
27
+ trace.disable();
28
+ context.disable();
29
+ });
30
+
31
+ it('does nothing when disabled', async () => {
32
+ const disabled = new OtelInstrumentation('test', { enabled: false });
33
+
34
+ expect(disabled.isEnabled()).toBe(false);
35
+ expect(disabled.startSpan('op', { kind: 'CLIENT' })).toBeNull();
36
+ await expect(
37
+ disabled.traceAsync('op', { kind: 'CLIENT' }, async (span) => {
38
+ expect(span).toBeNull();
39
+
40
+ return 'result';
41
+ }),
42
+ ).resolves.toBe('result');
43
+ expect(exporter.getFinishedSpans()).toEqual([]);
44
+ });
45
+
46
+ describe('traceAsync', () => {
47
+ it('runs callback with active span and ends it with OK', async () => {
48
+ let activeInside: unknown;
49
+
50
+ const result = await otel.traceAsync(
51
+ 'op',
52
+ { kind: 'CLIENT', attributes: { 'messaging.system': 'nats' } },
53
+ async (span) => {
54
+ activeInside = trace.getActiveSpan();
55
+ expect(activeInside).toBe(span);
56
+
57
+ return 42;
58
+ },
59
+ );
60
+
61
+ const [finished] = exporter.getFinishedSpans();
62
+
63
+ expect(result).toBe(42);
64
+ expect(finished.name).toBe('op');
65
+ expect(finished.attributes['messaging.system']).toBe('nats');
66
+ expect(finished.status.code).toBe(SpanStatusCode.OK);
67
+ });
68
+
69
+ it('records exception, sets ERROR and rethrows', async () => {
70
+ await expect(
71
+ otel.traceAsync('op', { kind: 'CLIENT' }, async () => {
72
+ throw new Error('boom');
73
+ }),
74
+ ).rejects.toThrow('boom');
75
+
76
+ const [finished] = exporter.getFinishedSpans();
77
+
78
+ expect(finished.status).toEqual({
79
+ code: SpanStatusCode.ERROR,
80
+ message: 'boom',
81
+ });
82
+ expect(finished.attributes['error.type']).toBe('Error');
83
+ expect(finished.events.map((x) => x.name)).toContain('exception');
84
+ });
85
+ });
86
+
87
+ describe('endSpan', () => {
88
+ it('marks non-Error rpc errors as ERROR', () => {
89
+ const span = otel.startSpan('op', { kind: 'SERVER' });
90
+
91
+ otel.endSpan(span, { code: 5, details: 'not found' });
92
+
93
+ const [finished] = exporter.getFinishedSpans();
94
+
95
+ expect(finished.status).toEqual({
96
+ code: SpanStatusCode.ERROR,
97
+ message: 'not found',
98
+ });
99
+ expect(finished.attributes['error.type']).toBe('5');
100
+ });
101
+
102
+ it('ignores repeated end', () => {
103
+ const span = otel.startSpan('op', { kind: 'SERVER' });
104
+
105
+ otel.endSpan(span);
106
+ otel.endSpan(span, new Error('late'));
107
+
108
+ const [finished] = exporter.getFinishedSpans();
109
+
110
+ expect(exporter.getFinishedSpans()).toHaveLength(1);
111
+ expect(finished.status.code).toBe(SpanStatusCode.OK);
112
+ });
113
+ });
114
+ });