[Package] NestJS Telemetry

[TorinAsakura]

Название пакета

@atls/nestjs-telemetry

Для чего нужен пакет?

Нужен новый NestJS-пакет для распределённой трассировки и корреляции логов между HTTP, gRPC, RabbitMQ/amqplib, Kafka и Nest microservices.

Пакет не должен расширять старый @atls/nestjs-logger как основной продуктовый слой. Старый @atls/logger из atls/common остаётся базой для LogRecord/exporter, а новый пакет отвечает за telemetry context и propagation.

Функции пакета:

• Nest module для настройки OpenTelemetry tracing/log correlation.
• Автоматическое добавление traceId/spanId в логи @atls/logger.
• Поддержка W3C traceparent как основного межсервисного идентификатора.
• HTTP middleware/interceptor для входящего и исходящего context.
• gRPC metadata extractor/injector.
• RabbitMQ/amqplib headers extractor/injector.
• Kafka headers extractor/injector для интеграции с @atls/nestjs-kafka.
• Локальное хранение context через AsyncLocalStorage/CLS только как runtime-хранилище внутри процесса, без собственного distributed tracing protocol.

Пример использования

import { Module } from '@nestjs/common'
import { TelemetryModule } from '@atls/nestjs-telemetry'

@Module({
  imports: [
    TelemetryModule.register({
      serviceName: 'billing-service',
      propagation: {
        http: true,
        grpc: true,
        amqp: true,
        kafka: true,
      },
      logs: {
        enrich: true,
      },
    }),
  ],
})
export class AppModule {}

Ожидаемое поведение:

• входящий HTTP/gRPC/message request получает или создаёт trace context;
• исходящие HTTP/gRPC/RabbitMQ/Kafka вызовы прокидывают traceparent дальше;
• @atls/logger пишет структурные логи с traceId/spanId;
• flow между сервисами восстанавливается через traceId, а не через самодельную строку flow.

Материалы

https://github.com/orgs/atls/discussions/167
https://github.com/atls/common/tree/master/packages/logger
https://docs.nestjs.com/recipes/async-local-storage
https://opentelemetry.io/docs/concepts/context-propagation/
https://www.w3.org/TR/trace-context/