@rsdk/core 5.15.0-next.7 → 5.15.0-next.8

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/dist/index.d.ts CHANGED
@@ -2,7 +2,7 @@ import './unhandled-rejection.handler';
2
2
  export { APP_SCOPE } from './app-metadata/app-metadata.const';
3
3
  export { Manifest } from './manifest/manifest';
4
4
  export { ProtocolDetector } from './transport/protocol.detector';
5
- export { TracingHeaderMappings, Span, NoSpan } from './tracing';
5
+ export { TracingHeaderMappings, Span, NoSpan, OtelInstrumentation, OtelSpanKind, OtelSpanOptions, } from './tracing';
6
6
  export { FileSystemCheckOptions, FileSystemIndicator, PingCheckOptions, PingIndicator, } from './health/indicators.abstract';
7
7
  export { HealthChecksService } from './health/health.service';
8
8
  export { HealthChecksConfig } from './health/health.config';
package/dist/index.js CHANGED
@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
- exports.TracingHeaders = exports.PlatformApp = exports.register = exports.Summary = exports.MetricsModule = exports.Metric = exports.Histogram = exports.Gauge = exports.Counter = exports.InjectLogger = exports.PlatformContext = exports.ConfigTag = exports.CheckResult = exports.Indicator = exports.getLoggerToken = exports.HealthChecksConfig = exports.HealthChecksService = exports.PingIndicator = exports.FileSystemIndicator = exports.NoSpan = exports.Span = exports.ProtocolDetector = exports.Manifest = exports.APP_SCOPE = void 0;
17
+ exports.TracingHeaders = exports.PlatformApp = exports.register = exports.Summary = exports.MetricsModule = exports.Metric = exports.Histogram = exports.Gauge = exports.Counter = exports.InjectLogger = exports.PlatformContext = exports.ConfigTag = exports.CheckResult = exports.Indicator = exports.getLoggerToken = exports.HealthChecksConfig = exports.HealthChecksService = exports.PingIndicator = exports.FileSystemIndicator = exports.OtelInstrumentation = exports.NoSpan = exports.Span = exports.ProtocolDetector = exports.Manifest = exports.APP_SCOPE = void 0;
18
18
  require("./unhandled-rejection.handler");
19
19
  var app_metadata_const_1 = require("./app-metadata/app-metadata.const");
20
20
  Object.defineProperty(exports, "APP_SCOPE", { enumerable: true, get: function () { return app_metadata_const_1.APP_SCOPE; } });
@@ -25,6 +25,7 @@ Object.defineProperty(exports, "ProtocolDetector", { enumerable: true, get: func
25
25
  var tracing_1 = require("./tracing");
26
26
  Object.defineProperty(exports, "Span", { enumerable: true, get: function () { return tracing_1.Span; } });
27
27
  Object.defineProperty(exports, "NoSpan", { enumerable: true, get: function () { return tracing_1.NoSpan; } });
28
+ Object.defineProperty(exports, "OtelInstrumentation", { enumerable: true, get: function () { return tracing_1.OtelInstrumentation; } });
28
29
  var indicators_abstract_1 = require("./health/indicators.abstract");
29
30
  Object.defineProperty(exports, "FileSystemIndicator", { enumerable: true, get: function () { return indicators_abstract_1.FileSystemIndicator; } });
30
31
  Object.defineProperty(exports, "PingIndicator", { enumerable: true, get: function () { return indicators_abstract_1.PingIndicator; } });
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yCAAuC;AAEvC,wEAA8D;AAArD,+GAAA,SAAS,OAAA;AAElB,gDAA+C;AAAtC,oGAAA,QAAQ,OAAA;AAEjB,mEAAiE;AAAxD,qHAAA,gBAAgB,OAAA;AAEzB,qCAAgE;AAAhC,+FAAA,IAAI,OAAA;AAAE,iGAAA,MAAM,OAAA;AAE5C,oEAKsC;AAHpC,0HAAA,mBAAmB,OAAA;AAEnB,oHAAA,aAAa,OAAA;AAGf,0DAA8D;AAArD,qHAAA,mBAAmB,OAAA;AAE5B,wDAA4D;AAAnD,mHAAA,kBAAkB,OAAA;AAI3B,6CAAmD;AAA1C,yGAAA,cAAc,OAAA;AAEvB,6EAAkE;AAAzD,gHAAA,SAAS,OAAA;AAIlB,4CAA+C;AAAtC,sGAAA,WAAW,OAAA;AAEpB,sDAAkD;AAAzC,yGAAA,SAAS,OAAA;AAElB,uDAAqD;AAA5C,mHAAA,eAAe,OAAA;AAExB,2CAAyB;AAEzB,+CAA6B;AAE7B,wDAAsC;AAEtC,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AAErB,qCASmB;AAPjB,kGAAA,OAAO,OAAA;AACP,gGAAA,KAAK,OAAA;AACL,oGAAA,SAAS,OAAA;AACT,iGAAA,MAAM,OAAA;AACN,wGAAA,aAAa,OAAA;AACb,kGAAA,OAAO,OAAA;AACP,mGAAA,QAAQ,OAAA;AAGV,mDAAiD;AAAxC,2GAAA,WAAW,OAAA;AAEpB,0CAAwB;AAExB,4DAA0C;AAE1C,oEAAkD;AAElD,qCAA2C;AAAlC,yGAAA,cAAc,OAAA"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,yCAAuC;AAEvC,wEAA8D;AAArD,+GAAA,SAAS,OAAA;AAElB,gDAA+C;AAAtC,oGAAA,QAAQ,OAAA;AAEjB,mEAAiE;AAAxD,qHAAA,gBAAgB,OAAA;AAEzB,qCAOmB;AALjB,+FAAA,IAAI,OAAA;AACJ,iGAAA,MAAM,OAAA;AACN,8GAAA,mBAAmB,OAAA;AAKrB,oEAKsC;AAHpC,0HAAA,mBAAmB,OAAA;AAEnB,oHAAA,aAAa,OAAA;AAGf,0DAA8D;AAArD,qHAAA,mBAAmB,OAAA;AAE5B,wDAA4D;AAAnD,mHAAA,kBAAkB,OAAA;AAI3B,6CAAmD;AAA1C,yGAAA,cAAc,OAAA;AAEvB,6EAAkE;AAAzD,gHAAA,SAAS,OAAA;AAIlB,4CAA+C;AAAtC,sGAAA,WAAW,OAAA;AAEpB,sDAAkD;AAAzC,yGAAA,SAAS,OAAA;AAElB,uDAAqD;AAA5C,mHAAA,eAAe,OAAA;AAExB,2CAAyB;AAEzB,+CAA6B;AAE7B,wDAAsC;AAEtC,qCAAyC;AAAhC,uGAAA,YAAY,OAAA;AAErB,qCASmB;AAPjB,kGAAA,OAAO,OAAA;AACP,gGAAA,KAAK,OAAA;AACL,oGAAA,SAAS,OAAA;AACT,iGAAA,MAAM,OAAA;AACN,wGAAA,aAAa,OAAA;AACb,kGAAA,OAAO,OAAA;AACP,mGAAA,QAAQ,OAAA;AAGV,mDAAiD;AAAxC,2GAAA,WAAW,OAAA;AAEpB,0CAAwB;AAExB,4DAA0C;AAE1C,oEAAkD;AAElD,qCAA2C;AAAlC,yGAAA,cAAc,OAAA"}
@@ -1 +1,2 @@
1
1
  export * from './decorators';
2
+ export { OtelInstrumentation, OtelSpanKind, OtelSpanOptions, } from './opentelemetry.instrumentation';
@@ -14,5 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
14
14
  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
15
15
  };
16
16
  Object.defineProperty(exports, "__esModule", { value: true });
17
+ exports.OtelInstrumentation = void 0;
17
18
  __exportStar(require("./decorators"), exports);
19
+ var opentelemetry_instrumentation_1 = require("./opentelemetry.instrumentation");
20
+ Object.defineProperty(exports, "OtelInstrumentation", { enumerable: true, get: function () { return opentelemetry_instrumentation_1.OtelInstrumentation; } });
18
21
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tracing/opentelemetry/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tracing/opentelemetry/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,iFAIyC;AAHvC,oIAAA,mBAAmB,OAAA"}
@@ -0,0 +1,57 @@
1
+ import type { Attributes, Context, ContextAPI, Link, PropagationAPI, Span, SpanKind, SpanStatusCode, TraceAPI } from '@opentelemetry/api';
2
+ /**
3
+ * Часть @opentelemetry/api, которая нужна инструментации.
4
+ * Сам пакет подгружается в рантайме, так как он опциональный.
5
+ */
6
+ export type OtelApi = {
7
+ context: ContextAPI;
8
+ propagation: PropagationAPI;
9
+ trace: TraceAPI;
10
+ ROOT_CONTEXT: Context;
11
+ SpanKind: typeof SpanKind;
12
+ SpanStatusCode: typeof SpanStatusCode;
13
+ };
14
+ export type OtelSpanKind = 'INTERNAL' | 'CLIENT' | 'SERVER' | 'PRODUCER' | 'CONSUMER';
15
+ export interface OtelSpanOptions {
16
+ kind: OtelSpanKind;
17
+ attributes?: Attributes | undefined;
18
+ links?: Link[] | undefined;
19
+ /**
20
+ * Родительский контекст. По умолчанию — активный контекст.
21
+ */
22
+ parent?: Context | undefined;
23
+ }
24
+ /**
25
+ * Спаны операций OpenTelemetry без привязки к транспорту. Инструментации
26
+ * пакетов наследуют этот класс и добавляют проброс контекста.
27
+ *
28
+ * Graceful degradation: если `@opentelemetry/api` не установлен или
29
+ * передано `enabled: false` — ничего не делает, а методы, возвращающие спан,
30
+ * возвращают `null`.
31
+ */
32
+ export declare class OtelInstrumentation {
33
+ private readonly tracerName;
34
+ protected readonly api: OtelApi | null;
35
+ /**
36
+ * @param tracerName имя трейсера, например `rsdk:nats.kv`
37
+ */
38
+ constructor(tracerName: string, { enabled }?: {
39
+ enabled?: boolean;
40
+ });
41
+ isEnabled(): boolean;
42
+ startSpan(name: string, options: OtelSpanOptions): Span | null;
43
+ /**
44
+ * Выполняет callback с активным спаном.
45
+ * Если otel недоступен или span равен null — вызывает callback напрямую.
46
+ */
47
+ runInSpan<T>(span: Span | null, callback: () => T, parent?: Context): T;
48
+ /**
49
+ * Завершает спан. При наличии ошибки записывает её и ставит статус ERROR.
50
+ */
51
+ endSpan(span: Span | null, error?: unknown): void;
52
+ /**
53
+ * Оборачивает асинхронную операцию в спан: callback выполняется с активным
54
+ * спаном, спан завершается по результату операции.
55
+ */
56
+ traceAsync<T>(name: string, options: OtelSpanOptions, callback: (span: Span | null) => Promise<T>): Promise<T>;
57
+ }
@@ -0,0 +1,118 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.OtelInstrumentation = void 0;
4
+ const loadOtelApi = () => {
5
+ try {
6
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
7
+ return require('@opentelemetry/api');
8
+ }
9
+ catch {
10
+ return null;
11
+ }
12
+ };
13
+ const describeError = (error) => {
14
+ if (error instanceof Error)
15
+ return error.message;
16
+ if (typeof error === 'object' && error !== null) {
17
+ // Ошибка Nest RPC: { code, details, metadata }
18
+ const { message, details } = error;
19
+ if (typeof message === 'string')
20
+ return message;
21
+ if (typeof details === 'string')
22
+ return details;
23
+ }
24
+ return typeof error === 'string' ? error : undefined;
25
+ };
26
+ /**
27
+ * Значение `error.type` по semantic conventions: класс ошибки или её код
28
+ */
29
+ const errorType = (error) => {
30
+ if (error instanceof Error)
31
+ return error.constructor.name;
32
+ const code = error?.code;
33
+ return typeof code === 'string' || typeof code === 'number'
34
+ ? String(code)
35
+ : '_OTHER';
36
+ };
37
+ /**
38
+ * Спаны операций OpenTelemetry без привязки к транспорту. Инструментации
39
+ * пакетов наследуют этот класс и добавляют проброс контекста.
40
+ *
41
+ * Graceful degradation: если `@opentelemetry/api` не установлен или
42
+ * передано `enabled: false` — ничего не делает, а методы, возвращающие спан,
43
+ * возвращают `null`.
44
+ */
45
+ class OtelInstrumentation {
46
+ tracerName;
47
+ api;
48
+ /**
49
+ * @param tracerName имя трейсера, например `rsdk:nats.kv`
50
+ */
51
+ constructor(tracerName, { enabled = true } = {}) {
52
+ this.tracerName = tracerName;
53
+ this.api = enabled ? loadOtelApi() : null;
54
+ }
55
+ isEnabled() {
56
+ return this.api !== null;
57
+ }
58
+ startSpan(name, options) {
59
+ if (!this.api)
60
+ return null;
61
+ const { context, SpanKind, trace } = this.api;
62
+ return trace.getTracer(this.tracerName).startSpan(name, {
63
+ kind: SpanKind[options.kind],
64
+ attributes: options.attributes ?? {},
65
+ links: options.links ?? [],
66
+ }, options.parent ?? context.active());
67
+ }
68
+ /**
69
+ * Выполняет callback с активным спаном.
70
+ * Если otel недоступен или span равен null — вызывает callback напрямую.
71
+ */
72
+ runInSpan(span, callback, parent) {
73
+ if (!this.api || !span)
74
+ return callback();
75
+ const { context, trace } = this.api;
76
+ return context.with(trace.setSpan(parent ?? context.active(), span), callback);
77
+ }
78
+ /**
79
+ * Завершает спан. При наличии ошибки записывает её и ставит статус ERROR.
80
+ */
81
+ endSpan(span, error) {
82
+ if (!this.api || !span?.isRecording())
83
+ return;
84
+ const { SpanStatusCode } = this.api;
85
+ if (error == null) {
86
+ span.setStatus({ code: SpanStatusCode.OK });
87
+ }
88
+ else {
89
+ if (error instanceof Error) {
90
+ span.recordException(error);
91
+ }
92
+ span.setAttribute('error.type', errorType(error));
93
+ const message = describeError(error);
94
+ span.setStatus(message === undefined
95
+ ? { code: SpanStatusCode.ERROR }
96
+ : { code: SpanStatusCode.ERROR, message });
97
+ }
98
+ span.end();
99
+ }
100
+ /**
101
+ * Оборачивает асинхронную операцию в спан: callback выполняется с активным
102
+ * спаном, спан завершается по результату операции.
103
+ */
104
+ async traceAsync(name, options, callback) {
105
+ const span = this.startSpan(name, options);
106
+ try {
107
+ const result = await this.runInSpan(span, () => callback(span), options.parent);
108
+ this.endSpan(span);
109
+ return result;
110
+ }
111
+ catch (error) {
112
+ this.endSpan(span, error);
113
+ throw error;
114
+ }
115
+ }
116
+ }
117
+ exports.OtelInstrumentation = OtelInstrumentation;
118
+ //# sourceMappingURL=opentelemetry.instrumentation.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"opentelemetry.instrumentation.js","sourceRoot":"","sources":["../../../src/tracing/opentelemetry/opentelemetry.instrumentation.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rsdk/core",
3
- "version": "5.15.0-next.7",
3
+ "version": "5.15.0-next.8",
4
4
  "description": "Nestjs based microservice chassis",
5
5
  "license": "Apache License 2.0",
6
6
  "publishConfig": {
@@ -54,5 +54,5 @@
54
54
  "optional": true
55
55
  }
56
56
  },
57
- "gitHead": "2178d5a4b05b6d2663202712ab364e83f5177cbd"
57
+ "gitHead": "3da629f7dbb0db6a2bfe04f31b510ab3a3d5fd0c"
58
58
  }
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,
@@ -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
+ });
@@ -0,0 +1,194 @@
1
+ import type {
2
+ Attributes,
3
+ Context,
4
+ ContextAPI,
5
+ Link,
6
+ PropagationAPI,
7
+ Span,
8
+ SpanKind,
9
+ SpanStatusCode,
10
+ TraceAPI,
11
+ } from '@opentelemetry/api';
12
+
13
+ /**
14
+ * Часть @opentelemetry/api, которая нужна инструментации.
15
+ * Сам пакет подгружается в рантайме, так как он опциональный.
16
+ */
17
+ export type OtelApi = {
18
+ context: ContextAPI;
19
+ propagation: PropagationAPI;
20
+ trace: TraceAPI;
21
+ ROOT_CONTEXT: Context;
22
+ SpanKind: typeof SpanKind;
23
+ SpanStatusCode: typeof SpanStatusCode;
24
+ };
25
+
26
+ export type OtelSpanKind =
27
+ | 'INTERNAL'
28
+ | 'CLIENT'
29
+ | 'SERVER'
30
+ | 'PRODUCER'
31
+ | 'CONSUMER';
32
+
33
+ export interface OtelSpanOptions {
34
+ kind: OtelSpanKind;
35
+ attributes?: Attributes | undefined;
36
+ links?: Link[] | undefined;
37
+
38
+ /**
39
+ * Родительский контекст. По умолчанию — активный контекст.
40
+ */
41
+ parent?: Context | undefined;
42
+ }
43
+
44
+ const loadOtelApi = (): OtelApi | null => {
45
+ try {
46
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
47
+ return require('@opentelemetry/api');
48
+ } catch {
49
+ return null;
50
+ }
51
+ };
52
+
53
+ const describeError = (error: unknown): string | undefined => {
54
+ if (error instanceof Error) return error.message;
55
+
56
+ if (typeof error === 'object' && error !== null) {
57
+ // Ошибка Nest RPC: { code, details, metadata }
58
+ const { message, details } = error as {
59
+ message?: unknown;
60
+ details?: unknown;
61
+ };
62
+
63
+ if (typeof message === 'string') return message;
64
+ if (typeof details === 'string') return details;
65
+ }
66
+
67
+ return typeof error === 'string' ? error : undefined;
68
+ };
69
+
70
+ /**
71
+ * Значение `error.type` по semantic conventions: класс ошибки или её код
72
+ */
73
+ const errorType = (error: unknown): string => {
74
+ if (error instanceof Error) return error.constructor.name;
75
+
76
+ const code = (error as { code?: unknown } | null)?.code;
77
+
78
+ return typeof code === 'string' || typeof code === 'number'
79
+ ? String(code)
80
+ : '_OTHER';
81
+ };
82
+
83
+ /**
84
+ * Спаны операций OpenTelemetry без привязки к транспорту. Инструментации
85
+ * пакетов наследуют этот класс и добавляют проброс контекста.
86
+ *
87
+ * Graceful degradation: если `@opentelemetry/api` не установлен или
88
+ * передано `enabled: false` — ничего не делает, а методы, возвращающие спан,
89
+ * возвращают `null`.
90
+ */
91
+ export class OtelInstrumentation {
92
+ protected readonly api: OtelApi | null;
93
+
94
+ /**
95
+ * @param tracerName имя трейсера, например `rsdk:nats.kv`
96
+ */
97
+ constructor(
98
+ private readonly tracerName: string,
99
+ { enabled = true }: { enabled?: boolean } = {},
100
+ ) {
101
+ this.api = enabled ? loadOtelApi() : null;
102
+ }
103
+
104
+ isEnabled(): boolean {
105
+ return this.api !== null;
106
+ }
107
+
108
+ startSpan(name: string, options: OtelSpanOptions): Span | null {
109
+ if (!this.api) return null;
110
+
111
+ const { context, SpanKind, trace } = this.api;
112
+
113
+ return trace.getTracer(this.tracerName).startSpan(
114
+ name,
115
+ {
116
+ kind: SpanKind[options.kind],
117
+ attributes: options.attributes ?? {},
118
+ links: options.links ?? [],
119
+ },
120
+ options.parent ?? context.active(),
121
+ );
122
+ }
123
+
124
+ /**
125
+ * Выполняет callback с активным спаном.
126
+ * Если otel недоступен или span равен null — вызывает callback напрямую.
127
+ */
128
+ runInSpan<T>(span: Span | null, callback: () => T, parent?: Context): T {
129
+ if (!this.api || !span) return callback();
130
+
131
+ const { context, trace } = this.api;
132
+
133
+ return context.with(
134
+ trace.setSpan(parent ?? context.active(), span),
135
+ callback,
136
+ );
137
+ }
138
+
139
+ /**
140
+ * Завершает спан. При наличии ошибки записывает её и ставит статус ERROR.
141
+ */
142
+ endSpan(span: Span | null, error?: unknown): void {
143
+ if (!this.api || !span?.isRecording()) return;
144
+
145
+ const { SpanStatusCode } = this.api;
146
+
147
+ if (error == null) {
148
+ span.setStatus({ code: SpanStatusCode.OK });
149
+ } else {
150
+ if (error instanceof Error) {
151
+ span.recordException(error);
152
+ }
153
+
154
+ span.setAttribute('error.type', errorType(error));
155
+
156
+ const message = describeError(error);
157
+
158
+ span.setStatus(
159
+ message === undefined
160
+ ? { code: SpanStatusCode.ERROR }
161
+ : { code: SpanStatusCode.ERROR, message },
162
+ );
163
+ }
164
+
165
+ span.end();
166
+ }
167
+
168
+ /**
169
+ * Оборачивает асинхронную операцию в спан: callback выполняется с активным
170
+ * спаном, спан завершается по результату операции.
171
+ */
172
+ async traceAsync<T>(
173
+ name: string,
174
+ options: OtelSpanOptions,
175
+ callback: (span: Span | null) => Promise<T>,
176
+ ): Promise<T> {
177
+ const span = this.startSpan(name, options);
178
+
179
+ try {
180
+ const result = await this.runInSpan(
181
+ span,
182
+ () => callback(span),
183
+ options.parent,
184
+ );
185
+
186
+ this.endSpan(span);
187
+
188
+ return result;
189
+ } catch (error) {
190
+ this.endSpan(span, error);
191
+ throw error;
192
+ }
193
+ }
194
+ }