@rsdk/core 4.0.0-next.9 → 4.0.0

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) => {

package/src/tracing/utils/create-span.ts

@@ -0,0 +1,20 @@
+import { getRandomBytes } from '@rsdk/common';
+
+/**
+ * Функция для генерации корректного рандомного traceId и spanId
+ * алгоритм взят из: https://github.com/openzipkin/zipkin-js/blob/ec89188cf6a07e184ab886c1dfb6c9dc276ddfa4/packages/zipkin/src/tracer/randomTraceId.js
+ * спецификация по traceId: https://www.w3.org/TR/trace-context/#considerations-for-trace-id-field-generation
+ * @returns {traceId, spanId}
+ */
+export function createSpan(): {
+  traceId: string;
+  spanId: string;
+} {
+  const rootSpanId = getRandomBytes(16);
+  const traceId = getRandomBytes(16) + rootSpanId;
+
+  return {
+    traceId,
+    spanId: rootSpanId,
+  };
+}

package/src/tracing/utils/save-async-hooks-context.ts

@@ -0,0 +1,61 @@
+import { SpanStatusCode } from '@opentelemetry/api';
+import { api } from '@opentelemetry/sdk-node';
+import type { ErrorLike } from '@rsdk/common';
+
+import { TraceInjector } from '../services';
+import { ActiveSpanStorage } from '../services/active-span.storage';
+
+/**
+ * Проблема: при передаче управления в rxjs теряется контекст асинк локал стораджа
+ *
+ * Решение: Утилита для проброса инфы из асинк локал стораджа в тело пайпа rxjs
+ * поиском "observableToAsyncIterable" можно найти тесты в которых есть пример использования
+ *
+ * Тут есть часть логик трейсер декоратора, суть простая:
+ * мы - находясь в контексте с актуальным асинк Metadata запускаем создание боди для пайпа rx и тем самым мы передаем контекст работы туда
+ * ```
+ * return this.booksStream.pipe(
+ *       concatMap(
+ *         saveAsyncHooksContext(async (book) => {
+ *           return { book: { ...book, pages: request.limit } };
+ *         }),
+ *       ),
+ *     );
+ * ```
+ */
+export function saveAsyncHooksContext<T>(
+  fn: (...args: any[]) => Promise<T>,
+): (...args: any[]) => Promise<T> {
+  const span = ActiveSpanStorage.getInstance()?.getActiveSpan();
+
+  return async function (...args): Promise<T> {
+    const activeSpan = ActiveSpanStorage.getInstance()?.getActiveSpan();
+    if (activeSpan) {
+      Object.assign(activeSpan.spanContext(), span?.spanContext());
+      return fn(...args);
+    }
+    if (!span) {
+      return fn(...args);
+    }
+    const spanContext = api.trace.setSpan(api.context.active(), span);
+
+    return api.context.with(spanContext, async () =>
+      fn(...args)
+        .then(async (result) => {
+          span.setAttribute('response', TraceInjector.toAttribute(result));
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.end();
+          return result;
+        })
+        .catch(async (error) => {
+          span.recordException(error as ErrorLike);
+          span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: (error as ErrorLike).message,
+          });
+          span.end();
+          throw error;
+        }),
+    );
+  };
+}

package/src/transport/get-transport-id.ts

@@ -0,0 +1,20 @@
+import type { ExecutionContext } from '@nestjs/common';
+import { createParamDecorator } from '@nestjs/common';
+import type { ExecutionContextHost } from '@nestjs/core/helpers/execution-context-host';
+import type { Transport } from '@nestjs/microservices';
+import { TRANSPORT_METADATA } from '@nestjs/microservices/constants';
+
+export const TransportId = createParamDecorator(
+  (_data: unknown, ctx: ExecutionContext | ExecutionContextHost) => {
+    return getTransportId(ctx);
+  },
+);
+
+export function getTransportId(
+  context: ExecutionContext | ExecutionContextHost,
+): Transport {
+  return (
+    Reflect.getMetadata(TRANSPORT_METADATA, context.getHandler()) ??
+    Reflect.getMetadata(TRANSPORT_METADATA, context.getClass())
+  );
+}

package/src/transport/protocol.detector.ts

@@ -0,0 +1,38 @@
+import type { ArgumentsHost } from '@nestjs/common';
+
+import { InternalException } from '../exceptions';
+import type { ITransport } from '../types';
+
+export class ProtocolDetector {
+  constructor(private transports: ITransport[]) {}
+
+  getProtocol(context: ArgumentsHost): string | undefined {
+    if (this.transports.length === 0) {
+      return;
+    }
+    const matchers = this.transports.map((tr) => ({
+      matched: tr.matchByContext(context),
+      tr,
+    }));
+    const matched = matchers.filter((matched) => matched.matched);
+    if (matched.length > 1) {
+      throw new InternalException('So many matchers for transports', {
+        cause: {
+          matchers,
+          matched,
+          context,
+        },
+      });
+    }
+    if (matched.length === 0) {
+      throw new InternalException('No matchers found', {
+        cause: {
+          matchers,
+          matched,
+          context,
+        },
+      });
+    }
+    return matched[0].tr.getProtocol();
+  }
+}

package/src/transport/transport.module.ts

@@ -9,6 +9,8 @@ import { MetricsModule } from '../metrics';
 import type { PlatformExtendedOptions } from '../types';
 import { isPrimaryTransport } from '../types';
 
+import { ProtocolDetector } from './protocol.detector';
+
 export class PlatformTransportModule {
   static forOptions(options: PlatformExtendedOptions): DynamicModule {
     return {
@@ -19,6 +21,14 @@ export class PlatformTransportModule {
         ...PlatformTransportModule.getTransportModules(options),
       ],
       module: PlatformTransportModule,
+      providers: [
+        {
+          provide: ProtocolDetector,
+          useFactory: () => new ProtocolDetector(options.transports ?? []),
+        },
+      ],
+      global: true,
+      exports: [ProtocolDetector],
     };
   }
 

package/src/types/index.ts

@@ -1,3 +1,5 @@
+export { getTransportId, TransportId } from '../transport/get-transport-id';
+
 export * from './metadata';
 export * from './options';
 export * from './transports';

package/src/types/transports.ts

@@ -1,3 +1,4 @@
+import type { ArgumentsHost } from '@nestjs/common';
 import type { Controller, INestApplication } from '@nestjs/common/interfaces';
 import type { AbstractHttpAdapter } from '@nestjs/core';
 import type { MicroserviceOptions } from '@nestjs/microservices';
@@ -21,6 +22,18 @@ export interface ITransport {
    */
   getProtocol(): string;
 
+  /**
+   * Detect is it context of this transport
+   * !!! Do NOT check on getType() === 'rpc', this type corresponds to all microservices
+   *
+   * @param {ArgumentsHost} ctx
+   * @returns {boolean}
+   * @example
+   * return ctx.getType() === 'http'
+   * return ctx.getArgByIndex(1) instanceof MyTransportContext
+   */
+  matchByContext(ctx: ArgumentsHost): boolean;
+
   /**
    * @returns error formatting algorithm
    */
@@ -50,6 +63,7 @@ export interface ITransport {
  */
 export interface IPrimaryTransport extends ITransport {
   getHealthController(): Constructor<Controller>;
+
   getMetricsController(): Constructor<Controller>;
 }
 
@@ -105,6 +119,7 @@ export interface IHttpTransport extends IPrimaryTransport {
     app: INestApplication,
     configContext: ConfigContext,
   ): Promise<void> | void;
+
   createHttpOptions(configContext: ConfigContext): HttpOptions;
 }
 

package/tsconfig.json

@@ -4,6 +4,16 @@
     "declaration": true,
     "outDir": "dist"
   },
-  "include": ["src/**/*"],
- "exclude": ["node_modules", "dist", "test", "**/*.spec.ts", "**/*.test.ts", "**/*.spec.e2e.ts", "**/*.test.e2e.ts"]
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test",
+    "**/*.spec.ts",
+    "**/*.test.ts",
+    "**/*.spec.e2e.ts",
+    "**/*.test.e2e.ts"
+  ]
 }