@rsdk/core 4.0.0-next.13 → 4.0.0-next.14

package/src/tracing/services/request-metadata.injector.ts

@@ -0,0 +1,153 @@
+import type { ExecutionContext } from '@nestjs/common';
+import { redecorate } from '@rsdk/decorators';
+import { LoggerFactory } from '@rsdk/logging';
+import assert from 'node:assert';
+import { randomUUID } from 'node:crypto';
+
+import { Constants, X_REQUEST_ID } from '../constants';
+
+import { RequestMetadataStorage } from './request-metadata.storage';
+
+const logger = LoggerFactory.create('RequestMetadataInjector');
+
+export class RequestMetadataInjector {
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  static wrap(
+    cls: any,
+    // eslint-disable-next-line @typescript-eslint/ban-types
+    original: Function,
+  ): void {
+    /**
+     * Означает, что данный метод уже обёрнут
+     */
+    if (RequestMetadataInjector.isWrapped(original)) {
+      return;
+    }
+
+    logger.trace(`Wrapping method: ${cls.constructor.name}.${original.name}()`);
+
+    const wrapped = RequestMetadataInjector.createWrapper(original);
+
+    redecorate(original, wrapped);
+
+    cls[original.name] = wrapped;
+
+    /**
+     * Отмечает метод, как обёрнутый (чтобы избежать повторного оборачивания)
+     */
+    RequestMetadataInjector.setWrapped(wrapped);
+  }
+
+  private static createWrapper(original: any): any {
+    return {
+      [original.name](...args: any[]): any {
+        const executionContext: ExecutionContext = args[0];
+
+        /**
+         * Переменный для хранения значений
+         */
+        let requestId: string | undefined;
+
+        /**
+         * Переменная для хранения Request/виртуального Request
+         */
+        let req: any;
+
+        /**
+         * В зависимости от типа контекста запускаем парсинг переданной Metadata
+         */
+        if (executionContext.getType() === 'rpc') {
+          const metadata = executionContext.switchToRpc().getContext();
+          /**
+           * Если мы пришли в GRPC и у нас есть методы для работы с Metadata
+           * то мы конвертируем Metadata в некий виртуальный request с заголовками (заголовки выбраны как общий стандарт проброса мета информации)
+           */
+          if (metadata?.get) {
+            req = {
+              headers: {
+                /**
+                 * Пробрасываем текущий ид запроса
+                 */
+                ...(metadata.get(X_REQUEST_ID).length > 0
+                  ? {
+                      [X_REQUEST_ID]: metadata.get(X_REQUEST_ID)[0],
+                    }
+                  : {}),
+              },
+            };
+          }
+        }
+
+        if (executionContext.getType() === 'http') {
+          req = executionContext.switchToHttp().getRequest();
+        }
+
+        if (executionContext.getType<string>() === 'graphql') {
+          req = executionContext.getArgs()[2]?.req; // аналог GqlExecutionContext.create(executionContext).getContext().req
+
+          if (req.connectionInitReceived) {
+            /**
+             * При работе с сабскрипшен через веб сокет, заголовки передаются в опции подключения к сабскрипшен в переменную connectionParams
+             * и мы перегоняем эти данные в request заголовки
+             */
+            req.headers = {
+              ...req?.headers,
+              ...Object.entries(req?.connectionParams?.headers || {}).reduce(
+                (acc, [key, value]) => {
+                  acc[key] = value;
+                  return acc;
+                },
+                {},
+              ),
+            };
+          }
+        }
+
+        if (req?.headers) {
+          /**
+           * Мы приводим все ключи заголовков к одному **lower_case** регистру, так как у разных транспортов разные регистры в именовании ключей для заголовков
+           */
+          req.headers = {
+            ...Object.entries(req.headers).reduce((acc, [key, value]) => {
+              acc[key.toLowerCase()] = req.headers[key.toLowerCase()] || value;
+              return acc;
+            }, {}),
+          };
+
+          /**
+           * Идентификатор запроса, если не передали то генерируем рандомный
+           */
+          requestId = req.headers[X_REQUEST_ID] || randomUUID();
+        }
+
+        return (
+          RequestMetadataStorage.getInstance()?.run({ requestId }, async () => {
+            return original.apply(this, args);
+          }) ?? original.apply(this, args)
+        );
+      },
+    }[original.name];
+  }
+
+  private static isWrapped(prototype: object): boolean {
+    assert.ok(prototype);
+
+    return Reflect.hasMetadata(
+      Constants.REQUEST_METADATA_ASYNC_LOCAL_STORAGE_ACTIVE,
+      prototype,
+    );
+  }
+
+  private static setWrapped(prototype: object): void {
+    assert.ok(prototype);
+
+    // Value doesn't matter
+    const NOOP = 1;
+
+    Reflect.defineMetadata(
+      Constants.REQUEST_METADATA_ASYNC_LOCAL_STORAGE_ACTIVE,
+      NOOP,
+      prototype,
+    );
+  }
+}

package/src/tracing/services/request-metadata.storage.ts

@@ -0,0 +1,69 @@
+import { Injectable } from '@nestjs/common';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export type RequestMetadata = {
+  requestId: string | undefined;
+};
+
+/**
+ * Обертка вокруг `AsyncLocalStorage`
+ * В теории можно запустить с пустым `payload`, для того чтобы добавлять
+ * значения в процессе
+ */
+@Injectable()
+export class RequestMetadataStorage {
+  /**
+   * Так как этот сервис используется в разных местах, чтобы не усложнять существующий код путем проксирования модулей и сервисов
+   * после создания ложим инстанс в эту статик переменную
+   */
+  private static instance: RequestMetadataStorage | undefined;
+
+  private asyncLocalStorage = new AsyncLocalStorage<{
+    requestMetadata: RequestMetadata;
+  }>();
+
+  constructor() {
+    if (!RequestMetadataStorage.instance) {
+      RequestMetadataStorage.instance = this;
+    }
+  }
+
+  static getInstance(): RequestMetadataStorage | undefined {
+    return RequestMetadataStorage.instance;
+  }
+
+  /**
+   * Получает новое значение из контекста
+   */
+  async getRequestMetadata(): Promise<RequestMetadata> {
+    return (
+      RequestMetadataStorage.instance?.asyncLocalStorage.getStore()
+        ?.requestMetadata ?? {
+        requestId: undefined,
+      }
+    );
+  }
+
+  /**
+   * Запускает переданную фунцию в контексте
+   * @template TResult
+   * @template TArgs
+   * @param context Контекст исполнения (данные)
+   * @param fn Функция для запуска
+   * @param args Аргументы функции
+   * @returns Результат выполнения функции
+   */
+  run<TResult, TArgs extends any[]>(
+    requestMetadata: RequestMetadata,
+    fn: (...args: TArgs) => TResult,
+    ...args: TArgs
+  ): TResult {
+    return (
+      RequestMetadataStorage?.instance?.asyncLocalStorage.run(
+        { requestMetadata },
+        fn,
+        ...args,
+      ) ?? fn(...args)
+    );
+  }
+}

package/src/tracing/services/trace.injector.ts

@@ -1,10 +1,19 @@
+import type { ExecutionContext } from '@nestjs/common';
 import type { AttributeValue, Span } from '@opentelemetry/api';
 import { SpanStatusCode, trace } from '@opentelemetry/api';
+import {
+  X_B3_PARENT_SPAN_ID,
+  X_B3_SPAN_ID,
+  X_B3_TRACE_ID,
+} from '@opentelemetry/propagator-b3';
+import { api } from '@opentelemetry/sdk-node';
+import { SemanticAttributes } from '@opentelemetry/semantic-conventions';
 import type { ErrorLike } from '@rsdk/common';
 import { isPrimitive, isRecord, normalizer } from '@rsdk/common';
 import { redecorate } from '@rsdk/decorators';
 import { LoggerFactory } from '@rsdk/logging';
 import assert from 'node:assert';
+import { catchError, mergeMap, Observable, of, throwError } from 'rxjs';
 
 import { Constants, MAX_BYTES } from '../constants';
 
@@ -17,6 +26,7 @@ export class TraceInjector {
     // eslint-disable-next-line @typescript-eslint/ban-types
     original: Function,
     descriptor?: TypedPropertyDescriptor<any>,
+    isTracingInterceptor?: boolean,
   ): void {
     /**
      * Означает, что данный метод уже обёрнут
@@ -27,8 +37,15 @@ export class TraceInjector {
 
     logger.trace(`Wrapping method: ${cls.constructor.name}.${original.name}()`);
 
-    const spanName = TraceInjector.createSpanName(cls, original.name);
-    const wrapped = TraceInjector.createWrapper(original, spanName);
+    const spanName = TraceInjector.createSpanName(
+      cls.constructor.name,
+      original.name,
+    );
+    const wrapped = TraceInjector.createWrapper(
+      original,
+      spanName,
+      isTracingInterceptor,
+    );
 
     redecorate(original, wrapped);
 
@@ -54,46 +71,275 @@ export class TraceInjector {
     if (isRecord(data) || Array.isArray(data)) {
       const serialized = JSON.stringify(normalizer()(data));
 
-      return serialized.length <= MAX_BYTES
+      return serialized.length <= MAX_BYTES.bytes()
         ? serialized
-        : `data exceeds limit of ${MAX_BYTES} bytes`;
+        : `data exceeds limit of ${MAX_BYTES.bytes()} bytes`;
     }
 
     return 'data is undefined';
   }
 
-  private static createWrapper(original: any, spanName: string): any {
+  private static createWrapper(
+    original: any,
+    spanName: string,
+    isTracingInterceptor?: boolean,
+  ): any {
     return {
       [original.name](...args: any[]): any {
         const tracer = trace.getTracer('@rsdk/open-telemetry', '1.0.0');
+        const executionContext: ExecutionContext = args[0];
 
-        return tracer.startActiveSpan(spanName, (span) => {
+        /**
+         * Переменный для хранения значений которые получаем для опен телеметрии
+         */
+        let traceId: string | undefined;
+        let spanId: string | undefined;
+        let parentSpanId: string | undefined;
+        /**
+         * Этот флаг нужен для детекта первого входа и старта трейсинга, логика использования ниже в контексте
+         */
+        let hasParentSpanId = false;
+
+        /**
+         * Переменная для хранения Request/виртуального рекRequestвеста
+         */
+        let req: any;
+
+        /**
+         * Первый вход обычно происходит в глобальном интерцепторе
+         * он оборачивается в некий свой интернал тип спана который и передает этот флаг isTracingInterceptor=true
+         */
+        if (isTracingInterceptor) {
+          if (executionContext.getType() === 'rpc') {
+            const metadata = executionContext.switchToRpc().getContext();
+            /**
+             * Если мы пришли в GRPC и у нас есть методы для работы с Metadata
+             * то мы конвертируем Metadata в некий виртуальный request с заголовками (заголовки выбраны как общий стандарт проброса мета информации)
+             */
+            if (metadata?.get) {
+              req = {
+                headers: {
+                  /**
+                   * Пробрасываем текущий трейс ид запроса
+                   */
+                  ...(metadata.get(X_B3_TRACE_ID).length > 0
+                    ? {
+                        [X_B3_TRACE_ID]: metadata.get(X_B3_TRACE_ID)[0],
+                      }
+                    : {}),
+                  /**
+                   * Пробрасываем текущий спан ид, он нужен чтобы установить цепочку с парентами и могли видеть правильную вложенность в графане
+                   */
+                  ...(metadata.get(X_B3_SPAN_ID).length > 0
+                    ? {
+                        [X_B3_SPAN_ID]: metadata.get(X_B3_SPAN_ID)[0],
+                      }
+                    : {}),
+                  /**
+                   * Вот это не обычная переменная, она нужна для определения общего входа и детекта рутового спан ид,
+                   * эта переменная нужна для работы флага hasParentSpanId
+                   */
+                  ...(metadata.get(X_B3_PARENT_SPAN_ID).length > 0
+                    ? {
+                        [X_B3_PARENT_SPAN_ID]:
+                          metadata.get(X_B3_PARENT_SPAN_ID)[0],
+                      }
+                    : {}),
+                },
+              };
+            }
+          }
+
+          if (executionContext.getType() === 'http') {
+            req = executionContext.switchToHttp().getRequest();
+          }
+
+          if (executionContext.getType<string>() === 'graphql') {
+            req = executionContext.getArgs()[2]?.req; // аналог GqlExecutionContext.create(executionContext).getContext().req
+
+            if (req.connectionInitReceived) {
+              /**
+               * При работе с сабскрипшен через веб сокет, заголовки передаются в опции подключения к сабскрипшен в переменную connectionParams
+               * и мы перегоняем эти данные в request заголовки
+               */
+              req.headers = {
+                ...req?.headers,
+                ...Object.entries(req?.connectionParams?.headers || {}).reduce(
+                  (acc, [key, value]) => {
+                    acc[key] = value;
+                    return acc;
+                  },
+                  {},
+                ),
+              };
+            }
+          }
+        }
+
+        if (req?.headers) {
+          /**
+           * Мы приводим все ключи заголовков к одному **lower_case** регистру, так как у разных транспортов разные регистры в именовании ключей для заголовков
+           */
+          req.headers = {
+            ...Object.entries(req.headers).reduce((acc, [key, value]) => {
+              acc[key.toLowerCase()] = req.headers[key.toLowerCase()] || value;
+              return acc;
+            }, {}),
+          };
+
+          /**
+           * Трейс ид - входящий рутовый идентификатор, он по всем цепочкам идет
+           */
+          traceId = req.headers[X_B3_TRACE_ID];
+          /**
+           * Спан ид - идентификатор который нужен для построения цепочки вызовов
+           */
+          spanId = req.headers[X_B3_SPAN_ID];
+          /**
+           * Флаг определяет находимся ли мы на рутовой позиции (самая первая точка входа)
+           * определяется просто - если с клиента не передали заголовок X_B3_PARENT_SPAN_ID то значит мы в точке входа,
+           * иначе мы являемся частью другой общей цепочки
+           */
+          hasParentSpanId = !!Object.getOwnPropertyDescriptor(
+            req.headers,
+            X_B3_PARENT_SPAN_ID,
+          );
+          /**
+           * Идентификатор родительского спана - больше нужен для определения рутового состояния в различных кодах по опен телеметрии
+           */
+          parentSpanId = req.headers[X_B3_PARENT_SPAN_ID];
+        }
+
+        if (isTracingInterceptor) {
+          /**
+           * Когда мы находимся в интерцепторе, то названием спана является название класса + метод интерцептора
+           * мы перебиваем на название класса + метод который трекаем
+           */
+          spanName = TraceInjector.createSpanName(
+            executionContext.getClass().name,
+            executionContext.getHandler().name,
+          );
+        }
+
+        /**
+         * Создаем новый спан
+         */
+        const span = tracer.startSpan(spanName, {});
+
+        // path parentSpanId for correct link to parent span
+        if (isTracingInterceptor && hasParentSpanId && parentSpanId) {
+          /**
+           * Так как опентелеметрия ставит свой некий парент спан ид, то наш слетает
+           * если мы работаем в рамках монолита то ничего не слетает
+           * как только мы перемещаемся между приложениями - он слетает
+           * чтобы иметь корректный парент спан ид - мы патчим его жестко (из коробки нельзя это сделать)
+           */
+          (span as any).parentSpanId = parentSpanId;
+        }
+
+        /**
+         * После создания контекста ранее при входе в приложение, у нас новый спан ид
+         * мы перетираем значением которе получили через заголовок
+         * в рамках приложения он корректный, но при переходе из одного приложения в другой - слетает
+         * и чтобы 100% все было норм, мы всегда патчим его
+         */
+        if (spanId) {
+          span.spanContext().spanId = spanId;
+        }
+
+        /**
+         * Патчим трайс ид, причина выше
+         */
+        if (traceId) {
+          span.spanContext().traceId = traceId;
+        }
+
+        if (req?.headers) {
+          /**
+           * Обычно самая первая точка входа это фронтовый запрос, который содержит некие заголовки хттп
+           * мы их кладем в рутовый спан
+           */
+          span.setAttribute(SemanticAttributes.HTTP_METHOD, req.method);
+          span.setAttribute(
+            SemanticAttributes.HTTP_URL,
+            req.originalUrl || req.url,
+          );
+          span.setAttribute(
+            SemanticAttributes.HTTP_ROUTE,
+            req.route?.path || req.routeOptions?.url || req.routerPath,
+          );
+        }
+
+        /**
+         * Чтобы пробросить пропатченный спан нужно запустить две строчки ниже:
+         * 1) создаем контекст в котором активный спан перебиваем новым
+         * 2) созданный контекст ставим основным и в нем запускаем под процесс
+         */
+        const spanContext = api.trace.setSpan(api.context.active(), span);
+
+        return api.context.with(spanContext, async () => {
           try {
-            logger.trace(`Wrapped function invoked: ${original.name}`);
+            /**
+             * При запуске функции обернутой в опентелеметрию мы выводим и трейсИд и спанИд
+             * чтобы в ручную по логам отсмотреть порядок запусков, в случаи если нет доступа до борды графаны и на руках есть только файл с логами
+             */
+            logger.trace(
+              `Wrapped function invoked: ${original.name}, traceId: ${
+                span.spanContext().traceId
+              }, spanId: ${span.spanContext().spanId}`,
+            );
 
             const result = original.apply(this, args);
 
             /**
-             * If function returns promise:
-             * - errors won't be caught with try-catch
-             * - enriching span should be don when promise is resolved
-             *
-             * That's why this extra branch exists
+             * Если метод асинхронный - обрабтываем его и фиксируем успешное или не успешное завершение метода и зарываем спан,
+             * чтобы зафиксировать время запроса и видеть его в графане
              */
             if (result instanceof Promise) {
               return result
-                .then((result: unknown) => TraceInjector.enrich(span, result))
-                .catch((error: unknown) =>
-                  TraceInjector.recordAndRethrow(error, span),
-                )
-                .finally(() => span.end());
+                .then(async (result) => {
+                  TraceInjector.enrich(span, result);
+                  span.end();
+                  return result;
+                })
+                .catch(async (error) => {
+                  TraceInjector.recordAndRethrow(error, span);
+                  span.end();
+                  throw error;
+                });
             }
 
+            /**
+             * Если метод обзервабл - обрабтываем его и фиксируем успешное или не успешное завершение метода и зарываем спан,
+             * чтобы зафиксировать время запроса и видеть его в графане
+             */
+            if (result instanceof Observable) {
+              return result.pipe(
+                mergeMap((result) => {
+                  TraceInjector.enrich(span, result);
+                  span.end();
+                  return of(result);
+                }),
+                catchError((error) => {
+                  TraceInjector.recordAndRethrow(error, span);
+                  span.end();
+                  return throwError(() => error);
+                }),
+              );
+            }
+
+            /**
+             * Если метод вернул статичное значение - фиксируем успешное или не успешное завершение метода и зарываем спан,
+             * чтобы зафиксировать время запроса и видеть его в графане
+             */
             TraceInjector.enrich(span, result);
             span.end();
 
             return result;
           } catch (error) {
+            /**
+             * Обрабатываем ошибку и закрываем спан при попытке получения статичного результата или любую иную ошибку
+             */
             TraceInjector.recordAndRethrow(error, span);
             span.end();
           }
@@ -102,8 +348,11 @@ export class TraceInjector {
     }[original.name];
   }
 
-  private static createSpanName(cls: object, methodName: string): string {
-    return `${cls.constructor.name} -> ${methodName}`;
+  private static createSpanName(className: string, methodName: string): string {
+    /**
+     * Всего лишь правила формирования имени спана (не более того), для новой логики нужен был именно такой код
+     */
+    return `${className} -> ${methodName}`;
   }
 
   private static isWrapped(prototype: object): boolean {

package/src/tracing/tracing.interceptor.ts

@@ -0,0 +1,18 @@
+import type {
+  CallHandler,
+  ExecutionContext,
+  NestInterceptor,
+} from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
+import type { Observable } from 'rxjs';
+
+/**
+ * Интернал глобальный интерцептор для работы опентелеметрии
+ * его поведение будет модифицировано в зависимости от включенного или выключенного состояния глобального трэйсинга
+ */
+@Injectable()
+export class TracingInterceptor implements NestInterceptor {
+  intercept(_context: ExecutionContext, next: CallHandler): Observable<any> {
+    return next.handle();
+  }
+}

package/src/tracing/tracing.module.ts

@@ -1,10 +1,9 @@
 import type { DynamicModule, Provider } from '@nestjs/common';
 import { Module } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
 import { context, trace } from '@opentelemetry/api';
 import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
-import { CompositePropagator } from '@opentelemetry/core';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { B3InjectEncoding, B3Propagator } from '@opentelemetry/propagator-b3';
 import { Resource } from '@opentelemetry/resources';
 import { NodeSDK } from '@opentelemetry/sdk-node';
 import type { SpanExporter } from '@opentelemetry/sdk-trace-base';
@@ -17,9 +16,11 @@ import { ILogger, LoggerFactory } from '@rsdk/logging';
 
 import { InjectLogger } from '../logging';
 
-import { InstrumentationService } from './services/instrumentation.service';
-import { ExtendedMetadataScanner } from './services/metadata.scanner';
+import { ActiveSpanModule } from './active-span.module';
+import { RequestMetadataModule } from './request-metadata.module';
+import { InstrumentationService } from './services';
 import { TracingModuleConfig } from './tracing.config';
+import { TracingInterceptor } from './tracing.interceptor';
 
 export interface TracingModuleOptions {
   appName: string;
@@ -39,10 +40,14 @@ export class TracingModule {
   static forRoot(options: TracingModuleOptions): DynamicModule {
     return {
       module: TracingModule,
+      imports: [RequestMetadataModule, ActiveSpanModule],
       providers: [
-        ExtendedMetadataScanner,
         InstrumentationService,
         this.createSDKProvider(options),
+        /**
+         * Глобальный интерцептор для проброса входящих traceId, spanId и requestId из заголовков и метадаты в активный AsyncLocalStorage запроса
+         */
+        { provide: APP_INTERCEPTOR, useClass: TracingInterceptor },
       ],
     };
   }
@@ -71,14 +76,6 @@ export class TracingModule {
             [SemanticResourceAttributes.SERVICE_NAME]: options.appName,
           }),
           spanProcessor: processor,
-          textMapPropagator: new CompositePropagator({
-            propagators: [
-              new B3Propagator(),
-              new B3Propagator({
-                injectEncoding: B3InjectEncoding.MULTI_HEADER,
-              }),
-            ],
-          }),
         });
       },
     };
@@ -86,6 +83,9 @@ export class TracingModule {
 
   // Можно добавить включение и выключение при изменении конфига.
   async onModuleInit(): Promise<void> {
+    this.logger.debug('Injecting request-metadata storage...');
+    this.instrumentations.injectWrapRequestMetadataInjector();
+
     if (!this.config.enabled) {
       this.logger.info('Tracing is disabled');
 
@@ -98,7 +98,7 @@ export class TracingModule {
     await this.sdk.start();
 
     this.logger.debug('Instrumenting nest.js entities...');
-    this.instrumentations.inject();
+    this.instrumentations.injectWrapTraceInjector();
 
     this.logger.debug('Attaching log messages to spans...');
     LoggerFactory.onMessage((level, msg) => {