@yolo-croket-dev/core 1.10.0 → 1.10.1

package/CHANGELOG.md

@@ -11,3 +11,13 @@
 - 현재 소비 버전 1.10.0-jun.2의 gRPC metadata 및 예외 처리 동작을 유지합니다.
 - 비회원 인증 요청 로그의 민감 값을 마스킹하고 검증 오류에서 입력값을 제외합니다.
 - 인증 실패의 남은 입력 횟수와 재시도 대기시간 필드를 추가합니다.
+
+## 1.9.13-beta.1
+
+- AMQP 요청의 `param.timeout`을 최대 29분 범위에서 적용해 timeout 시 클라이언트 Observable 구독을 해제합니다.
+
+## 1.9.12-beta.1
+
+- `GracefulServerRMQ`가 RabbitMQ 연결에 queue, environment, owner, hostname, process ID 기반 `connection_name`을 자동으로 추가합니다.
+- 호출자가 지정한 `connectionOptions`, `clientProperties`, 유효한 문자열 `connection_name`은 그대로 보존합니다.
+- 문자열이 아닌 `connection_name`은 런타임 오류 없이 자동 생성값으로 대체합니다.

package/functions/amqp-call-manager.function.js

@@ -25,6 +25,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AmqpManagement = void 0;
 const msa_logger_1 = __importStar(require("@yolo-croket-dev/msa-logger"));
+const rmq_diagnostics_function_1 = require("./rmq-diagnostics.function");
 const _1 = require(".");
 const msaLogger = new msa_logger_1.default(msa_logger_1.ServerTypeEnum.SERVICE);
 class AmqpManagement {
@@ -44,7 +45,9 @@ class AmqpManagement {
         }
         return param;
     }
-    async call(funcName, messagePattern, payload, argParam, options, file) {
+    async call(funcName, messagePattern, payload, argParam, options, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    file) {
         const param = this.paramProcessor(argParam || {
             traceId: (0, _1.generateTraceId)(),
             isInternal: true,
@@ -58,7 +61,9 @@ class AmqpManagement {
             return result.data;
         }
         catch (err) {
-            msaLogger.warn(`ThrowWrapppingCall[${funcName}] error: traceId=${param.traceId}`, { traceId: param.traceId }, { param });
+            if (!(0, rmq_diagnostics_function_1.getRmqDiagnosticSnapshot)(this.client) && !(0, rmq_diagnostics_function_1.isRmqDiagnosticsEnabled)()) {
+                msaLogger.warn(`ThrowWrapppingCall[${funcName}] error: traceId=${param.traceId}`, { traceId: param.traceId }, { param });
+            }
             if (options && options.isErrorThrowing) {
                 throw err;
             }

package/functions/amqp-handler.function.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AmqpHandler = exports.HttpExceptionCustom = void 0;
+/* eslint-disable max-len */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const microservices_1 = require("@nestjs/microservices");
 const common_1 = require("@nestjs/common");
 const rxjs_1 = require("rxjs");
 const operators_1 = require("rxjs/operators");
 const msa_logger_1 = require("@yolo-croket-dev/msa-logger");
+const rmq_diagnostics_function_1 = require("./rmq-diagnostics.function");
 const _1 = require(".");
 const DEFAULT_TIMEOUT = 1000 * 60 * 29; // 29분 타임아웃
 const DEFAULT_TIMEOUT_MESSAGE = '요청이 타임아웃되었습니다.';
@@ -23,10 +27,23 @@ function resolveAmqpTimeout(timeoutMs) {
     }
     return Math.min(timeoutMs, DEFAULT_TIMEOUT);
 }
+function getLegacyRmqQueue(client) {
+    if (!(client instanceof microservices_1.ClientRMQ))
+        return undefined;
+    try {
+        const queue = Reflect.get(Reflect.get(client, 'options'), 'queue');
+        return typeof queue === 'string' ? (0, msa_logger_1.sanitizeDiagnosticText)(queue).slice(0, 240) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 async function AmqpHandler(client, messagePattern, payload) {
     var _a, _b, _c, _d, _e;
     let data;
     const timeoutMs = resolveAmqpTimeout((_a = payload === null || payload === void 0 ? void 0 : payload.param) === null || _a === void 0 ? void 0 : _a.timeout);
+    const startedAt = Date.now();
+    const startConnection = (0, rmq_diagnostics_function_1.getRmqDiagnosticSnapshot)(client);
     try {
         data = await (0, rxjs_1.lastValueFrom)(client.send(messagePattern, payload).pipe((0, operators_1.timeout)(timeoutMs)));
         if (data.isError) {
@@ -55,36 +72,67 @@ async function AmqpHandler(client, messagePattern, payload) {
         }
     }
     catch (err) {
+        const normalized = (startConnection || (0, rmq_diagnostics_function_1.isRmqDiagnosticsEnabled)())
+            ? (0, msa_logger_1.normalizeDiagnosticError)(err, err instanceof HttpExceptionCustom ? 'service_error' : undefined) : undefined;
+        const diagnosticInfo = normalized ? {
+            ...normalized.diagnosticInfo,
+            ...(0, rmq_diagnostics_function_1.getRmqDiagnosticSnapshot)(client),
+            ...(startConnection ? {} : {
+                direction: 'client',
+                connectionState: 'unobserved',
+                targetService: getLegacyRmqQueue(client),
+            }),
+            event: 'call_failed',
+            messagePattern: (0, msa_logger_1.sanitizeDiagnosticText)(messagePattern).slice(0, 240),
+            elapsedMs: Date.now() - startedAt,
+            timeoutMs,
+            startGeneration: startConnection === null || startConnection === void 0 ? void 0 : startConnection.generation,
+            startConnectionState: startConnection === null || startConnection === void 0 ? void 0 : startConnection.connectionState,
+        } : undefined;
+        const details = normalized ? normalized.details : { err };
+        if (normalized)
+            (0, rmq_diagnostics_function_1.recordRmqDiagnosticError)(err, normalized);
         if (typeof err === 'string' && err.includes('There is no matching message handler defined in the remote service.')) {
             msaLogger.error('NOT_EXISTS_MESSAGE_PATTERN', {
                 traceId: ((_c = payload === null || payload === void 0 ? void 0 : payload.param) === null || _c === void 0 ? void 0 : _c.traceId) || '-',
+                diagnosticInfo,
                 errInfo: {
                     errType: 'NOT_EXISTS_MESSAGE_PATTERN',
                     message: `${messagePattern} 해당 메시지 패턴은 존재하지 않습니다.`,
                     status: 404,
                 },
-            }, { err });
-            throw new HttpExceptionCustom('해당 메시지 패턴은 존재하지 않습니다.', 404, 'There is no matching message handler defined in the remote service.', {
+            }, details);
+            const exception = new HttpExceptionCustom('해당 메시지 패턴은 존재하지 않습니다.', 404, 'There is no matching message handler defined in the remote service.', {
                 type: 'NOT_EXISTS_MESSAGE_PATTERN',
                 message: `${messagePattern} 해당 메시지 패턴은 존재하지 않습니다.`,
             });
+            if (normalized)
+                (0, rmq_diagnostics_function_1.recordRmqDiagnosticError)(exception, normalized);
+            throw exception;
         }
-        else if (err instanceof rxjs_1.TimeoutError || err.message === DEFAULT_TIMEOUT_MESSAGE) {
+        else if (err instanceof rxjs_1.TimeoutError || (err === null || err === void 0 ? void 0 : err.message) === DEFAULT_TIMEOUT_MESSAGE) {
             msaLogger.error('TIMEOUT_ERROR', {
                 traceId: ((_d = payload === null || payload === void 0 ? void 0 : payload.param) === null || _d === void 0 ? void 0 : _d.traceId) || '-',
+                diagnosticInfo,
                 errInfo: {
                     errType: 'TIMEOUT_ERROR',
                     message: DEFAULT_TIMEOUT_MESSAGE,
                     status: 500,
                 },
-            }, { err });
-            throw new HttpExceptionCustom(DEFAULT_TIMEOUT_MESSAGE, 500, DEFAULT_TIMEOUT_MESSAGE, {
+            }, details);
+            const exception = new HttpExceptionCustom(DEFAULT_TIMEOUT_MESSAGE, 500, DEFAULT_TIMEOUT_MESSAGE, {
                 type: 'TIMEOUT_ERROR',
                 message: DEFAULT_TIMEOUT_MESSAGE,
             });
+            if (normalized)
+                (0, rmq_diagnostics_function_1.recordRmqDiagnosticError)(exception, normalized);
+            throw exception;
         }
         else {
-            msaLogger.warn('AMQP_HANDLER_ERROR', { traceId: ((_e = payload === null || payload === void 0 ? void 0 : payload.param) === null || _e === void 0 ? void 0 : _e.traceId) || '-' }, { err });
+            msaLogger.warn('AMQP_HANDLER_ERROR', {
+                traceId: ((_e = payload === null || payload === void 0 ? void 0 : payload.param) === null || _e === void 0 ? void 0 : _e.traceId) || '-',
+                diagnosticInfo,
+            }, details);
             throw err;
         }
     }

package/functions/index.d.ts

@@ -8,3 +8,4 @@ export * from './extract-redis-url.function';
 export * from './abort';
 export * from './uncaught-exception-handler';
 export * from './unhandled-rejection-handler';
+export * from './rmq-diagnostics.function';

package/functions/index.js

@@ -24,3 +24,4 @@ __exportStar(require("./extract-redis-url.function"), exports);
 __exportStar(require("./abort"), exports);
 __exportStar(require("./uncaught-exception-handler"), exports);
 __exportStar(require("./unhandled-rejection-handler"), exports);
+__exportStar(require("./rmq-diagnostics.function"), exports);

package/functions/rmq-diagnostics.function.d.ts

@@ -0,0 +1,89 @@
+/// <reference types="node" />
+import { EventEmitter } from 'node:events';
+import { ClientRMQ, RmqOptions } from '@nestjs/microservices';
+import { DiagnosticInfo, NormalizedDiagnosticError } from '@yolo-croket-dev/msa-logger';
+type RmqConnectionOptions = NonNullable<RmqOptions['options']>;
+type Snapshot = Pick<DiagnosticInfo, 'connectionId' | 'connectionName' | 'direction' | 'targetService' | 'generation' | 'connectionState' | 'stateChangedAt'>;
+type DiagnosticWriter = (info: DiagnosticInfo, details?: NormalizedDiagnosticError['details']) => void;
+/**
+ * @author jun
+ * @description 프로세스의 RMQ 연결 진단 활성 여부를 확인한다.
+ * @process 명시적인 true 값만 활성으로 해석한다.
+ */
+export declare function isRmqDiagnosticsEnabled(): boolean;
+/**
+ * @author jun
+ * @description 전송 동작을 바꾸지 않고 연결 상태와 반복 실패를 기록한다.
+ * @process 연결 이벤트 구독 → 상태 갱신/60초 실패 요약 → 종료 시 listener/timer 정리.
+ */
+export declare class RmqConnectionObserver {
+    private readonly direction;
+    private readonly write;
+    readonly connectionId: `${string}-${string}-${string}-${string}-${string}`;
+    readonly connectionName: string;
+    readonly targetService: string;
+    private generation;
+    private state;
+    private changedAt;
+    private emitter?;
+    private listeners;
+    private timer?;
+    private failed;
+    private repeatCount;
+    private firstOccurredAt?;
+    private lastOccurredAt?;
+    private latestFailure?;
+    constructor(queue: string | undefined, direction: 'client' | 'consumer', configuredName?: string, write?: DiagnosticWriter);
+    snapshot(): Snapshot;
+    private transition;
+    private emit;
+    private flush;
+    private onFailure;
+    observe(emitter: EventEmitter): void;
+    private detach;
+    close(): void;
+}
+/**
+ * @author jun
+ * @description 기존 연결 옵션으로 관찰자를 만든다.
+ * @process 명시적인 broker 연결 이름을 읽고 인스턴스 식별자를 생성한다.
+ */
+export declare function createRmqObserver(options: RmqConnectionOptions, direction: 'client' | 'consumer'): RmqConnectionObserver;
+/**
+ * @author jun
+ * @description 기존 RMQ 옵션에 연결 이름만 추가한다.
+ * @process 원본 옵션과 명시적인 연결 이름을 보존한 복사본을 반환한다.
+ */
+export declare function withRmqConnectionName<T extends RmqConnectionOptions>(options: T, observer: RmqConnectionObserver): T;
+/**
+ * @author jun
+ * @description 클라이언트 또는 consumer 채널을 관찰자와 연결한다.
+ * @process WeakMap에 등록하여 전송 객체 수명 이후 참조를 유지하지 않는다.
+ */
+export declare function registerRmqObservation(owner: object, observer: RmqConnectionObserver): void;
+/**
+ * @author jun
+ * @description 현재 연결 상태의 독립적인 스냅샷을 반환한다.
+ * @process 관찰 대상이 아니면 undefined를 반환한다.
+ */
+export declare function getRmqDiagnosticSnapshot(owner: object): Snapshot | undefined;
+/**
+ * @author jun
+ * @description 이미 기록한 오류 상세를 표시한다.
+ * @process 요청별 호출 정보 없이 오류 메타데이터만 WeakMap에 저장한다.
+ */
+export declare function recordRmqDiagnosticError(error: unknown, diagnostic: NormalizedDiagnosticError): void;
+/**
+ * @author jun
+ * @description 동일 오류의 중복 상세 기록 여부를 확인한다.
+ * @process 객체 오류에 연결된 정규화 결과를 반환한다.
+ */
+export declare function getRecordedRmqDiagnosticError(error: unknown): NormalizedDiagnosticError | undefined;
+/** Same factory/options and lazy connection behavior; observation is opt-in per process. */
+/**
+ * @author jun
+ * @description lazy 연결을 유지하는 RMQ 클라이언트를 생성한다.
+ * @process 진단이 활성화되면 기존 ClientRMQ를 확장하고 그 외에는 기본 factory를 사용한다.
+ */
+export declare function createDiagnosticRmqClient(options: RmqOptions): ClientRMQ;
+export {};

package/functions/rmq-diagnostics.function.js

@@ -0,0 +1,300 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDiagnosticRmqClient = exports.getRecordedRmqDiagnosticError = exports.recordRmqDiagnosticError = exports.getRmqDiagnosticSnapshot = exports.registerRmqObservation = exports.withRmqConnectionName = exports.createRmqObserver = exports.RmqConnectionObserver = exports.isRmqDiagnosticsEnabled = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = __importDefault(require("node:os"));
+const microservices_1 = require("@nestjs/microservices");
+const msa_logger_1 = __importStar(require("@yolo-croket-dev/msa-logger"));
+const observations = new WeakMap();
+const recordedErrors = new WeakMap();
+let logger;
+/**
+ * @author jun
+ * @description 프로세스의 RMQ 연결 진단 활성 여부를 확인한다.
+ * @process 명시적인 true 값만 활성으로 해석한다.
+ */
+function isRmqDiagnosticsEnabled() {
+    return process.env.RMQ_DIAGNOSTICS_ENABLED === 'true';
+}
+exports.isRmqDiagnosticsEnabled = isRmqDiagnosticsEnabled;
+function writeConnectionEvent(info, details) {
+    logger !== null && logger !== void 0 ? logger : (logger = new msa_logger_1.default(msa_logger_1.ServerTypeEnum.SERVICE));
+    const method = info.event === 'connected' || info.event === 'unblocked' ? 'info' : 'warn';
+    logger[method]('RMQ_CONNECTION', {
+        traceId: '-',
+        diagnosticInfo: info,
+    }, details);
+}
+/**
+ * @author jun
+ * @description 전송 동작을 바꾸지 않고 연결 상태와 반복 실패를 기록한다.
+ * @process 연결 이벤트 구독 → 상태 갱신/60초 실패 요약 → 종료 시 listener/timer 정리.
+ */
+class RmqConnectionObserver {
+    constructor(queue, direction, configuredName, write = writeConnectionEvent) {
+        this.direction = direction;
+        this.write = write;
+        this.connectionId = (0, node_crypto_1.randomUUID)();
+        this.generation = 0;
+        this.state = 'not_connected';
+        this.changedAt = new Date().toISOString();
+        this.listeners = [];
+        this.failed = false;
+        this.repeatCount = 0;
+        this.targetService = (0, msa_logger_1.sanitizeDiagnosticText)(queue || 'unknown').slice(0, 240);
+        this.connectionName = (configuredName === null || configuredName === void 0 ? void 0 : configuredName.trim()) ? configuredName
+            : `${process.env.SERVER_NAME || 'unknown'}/${direction}/${queue || 'unknown'}/${node_os_1.default.hostname()}/${this.connectionId}`;
+    }
+    snapshot() {
+        return {
+            connectionId: this.connectionId,
+            connectionName: (0, msa_logger_1.sanitizeDiagnosticText)(this.connectionName).slice(0, 240),
+            direction: this.direction,
+            targetService: this.targetService,
+            generation: this.generation,
+            connectionState: this.state,
+            stateChangedAt: this.changedAt,
+        };
+    }
+    transition(state) {
+        if (this.state !== state) {
+            this.state = state;
+            this.changedAt = new Date().toISOString();
+        }
+    }
+    emit(event, error, extra = {}) {
+        // Diagnostics must not throw into the connection manager's synchronous event dispatch.
+        try {
+            this.write({
+                ...error === null || error === void 0 ? void 0 : error.diagnosticInfo,
+                ...this.snapshot(),
+                event,
+                ...extra,
+            }, error === null || error === void 0 ? void 0 : error.details);
+        }
+        catch { /* The transport remains authoritative if the log sink fails. */ }
+    }
+    flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        if (this.repeatCount) {
+            this.emit('connect_failed_summary', this.latestFailure, {
+                repeatCount: this.repeatCount,
+                firstOccurredAt: this.firstOccurredAt,
+                lastOccurredAt: this.lastOccurredAt,
+            });
+        }
+        this.repeatCount = 0;
+        this.latestFailure = undefined;
+        this.firstOccurredAt = undefined;
+        this.lastOccurredAt = undefined;
+    }
+    onFailure(value) {
+        var _a;
+        this.transition('connection_failed');
+        const error = (0, msa_logger_1.normalizeDiagnosticError)(value, 'connection_failed');
+        if (!this.failed) {
+            this.failed = true;
+            this.emit('connect_failed', error);
+            return;
+        }
+        this.repeatCount += 1;
+        this.latestFailure = error;
+        this.lastOccurredAt = new Date().toISOString();
+        (_a = this.firstOccurredAt) !== null && _a !== void 0 ? _a : (this.firstOccurredAt = this.lastOccurredAt);
+        if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), 60000);
+            this.timer.unref();
+        }
+    }
+    observe(emitter) {
+        if (this.emitter === emitter)
+            return;
+        this.detach();
+        this.emitter = emitter;
+        this.listeners = [
+            [
+                'connect',
+                () => {
+                    this.flush();
+                    this.failed = false;
+                    this.generation += 1;
+                    this.transition('connected');
+                    this.emit('connected');
+                },
+            ],
+            [
+                'connectFailed',
+                value => this.onFailure(value),
+            ],
+            [
+                'disconnect',
+                value => {
+                    this.transition('disconnected');
+                    this.emit('disconnected', (0, msa_logger_1.normalizeDiagnosticError)(value, 'connection_lost'));
+                },
+            ],
+            [
+                'blocked',
+                () => {
+                    this.transition('blocked');
+                    this.emit('blocked');
+                },
+            ],
+            [
+                'unblocked',
+                () => {
+                    this.transition('connected');
+                    this.emit('unblocked');
+                },
+            ],
+        ];
+        this.listeners.forEach(([event, listener,]) => emitter.on(event, listener));
+    }
+    detach() {
+        this.listeners.forEach(([event, listener,]) => { var _a; return (_a = this.emitter) === null || _a === void 0 ? void 0 : _a.removeListener(event, listener); });
+        this.listeners = [];
+        this.emitter = undefined;
+    }
+    close() {
+        this.flush();
+        this.detach();
+        this.failed = false;
+        this.transition('closed');
+    }
+}
+exports.RmqConnectionObserver = RmqConnectionObserver;
+/**
+ * @author jun
+ * @description 기존 연결 옵션으로 관찰자를 만든다.
+ * @process 명시적인 broker 연결 이름을 읽고 인스턴스 식별자를 생성한다.
+ */
+function createRmqObserver(options, direction) {
+    var _a, _b;
+    const properties = (_b = (_a = options.socketOptions) === null || _a === void 0 ? void 0 : _a.connectionOptions) === null || _b === void 0 ? void 0 : _b.clientProperties;
+    const configured = properties && typeof properties === 'object'
+        ? properties.connection_name : undefined;
+    return new RmqConnectionObserver(options.queue, direction, typeof configured === 'string' ? configured : undefined);
+}
+exports.createRmqObserver = createRmqObserver;
+/**
+ * @author jun
+ * @description 기존 RMQ 옵션에 연결 이름만 추가한다.
+ * @process 원본 옵션과 명시적인 연결 이름을 보존한 복사본을 반환한다.
+ */
+function withRmqConnectionName(options, observer) {
+    var _a, _b, _c;
+    return {
+        ...options,
+        socketOptions: {
+            ...options.socketOptions,
+            connectionOptions: {
+                ...(_a = options.socketOptions) === null || _a === void 0 ? void 0 : _a.connectionOptions,
+                clientProperties: {
+                    ...(_c = (_b = options.socketOptions) === null || _b === void 0 ? void 0 : _b.connectionOptions) === null || _c === void 0 ? void 0 : _c.clientProperties,
+                    connection_name: observer.connectionName,
+                },
+            },
+        },
+    };
+}
+exports.withRmqConnectionName = withRmqConnectionName;
+/**
+ * @author jun
+ * @description 클라이언트 또는 consumer 채널을 관찰자와 연결한다.
+ * @process WeakMap에 등록하여 전송 객체 수명 이후 참조를 유지하지 않는다.
+ */
+function registerRmqObservation(owner, observer) {
+    observations.set(owner, observer);
+}
+exports.registerRmqObservation = registerRmqObservation;
+/**
+ * @author jun
+ * @description 현재 연결 상태의 독립적인 스냅샷을 반환한다.
+ * @process 관찰 대상이 아니면 undefined를 반환한다.
+ */
+function getRmqDiagnosticSnapshot(owner) {
+    var _a;
+    return (_a = observations.get(owner)) === null || _a === void 0 ? void 0 : _a.snapshot();
+}
+exports.getRmqDiagnosticSnapshot = getRmqDiagnosticSnapshot;
+// Contains error metadata only, never per-request context: one RMQ error can reject concurrent calls.
+/**
+ * @author jun
+ * @description 이미 기록한 오류 상세를 표시한다.
+ * @process 요청별 호출 정보 없이 오류 메타데이터만 WeakMap에 저장한다.
+ */
+function recordRmqDiagnosticError(error, diagnostic) {
+    if (error !== null && typeof error === 'object')
+        recordedErrors.set(error, diagnostic);
+}
+exports.recordRmqDiagnosticError = recordRmqDiagnosticError;
+/**
+ * @author jun
+ * @description 동일 오류의 중복 상세 기록 여부를 확인한다.
+ * @process 객체 오류에 연결된 정규화 결과를 반환한다.
+ */
+function getRecordedRmqDiagnosticError(error) {
+    return error !== null && typeof error === 'object' ? recordedErrors.get(error) : undefined;
+}
+exports.getRecordedRmqDiagnosticError = getRecordedRmqDiagnosticError;
+class DiagnosticClientRMQ extends microservices_1.ClientRMQ {
+    constructor(options, observation) {
+        super(withRmqConnectionName(options, observation));
+        this.observation = observation;
+        registerRmqObservation(this, observation);
+    }
+    createClient() {
+        const client = super.createClient();
+        this.observation.observe(client);
+        return client;
+    }
+    async close() {
+        try {
+            await super.close();
+        }
+        finally {
+            this.observation.close();
+        }
+    }
+}
+/** Same factory/options and lazy connection behavior; observation is opt-in per process. */
+/**
+ * @author jun
+ * @description lazy 연결을 유지하는 RMQ 클라이언트를 생성한다.
+ * @process 진단이 활성화되면 기존 ClientRMQ를 확장하고 그 외에는 기본 factory를 사용한다.
+ */
+function createDiagnosticRmqClient(options) {
+    if (!isRmqDiagnosticsEnabled())
+        return microservices_1.ClientProxyFactory.create(options);
+    const connectionOptions = options.options || {};
+    return new DiagnosticClientRMQ(connectionOptions, createRmqObserver(connectionOptions, 'client'));
+}
+exports.createDiagnosticRmqClient = createDiagnosticRmqClient;

package/interceptors/logging-service.interceptor.js

@@ -39,11 +39,22 @@ const common_1 = require("@nestjs/common");
 const msa_logger_1 = __importStar(require("@yolo-croket-dev/msa-logger"));
 const operators_1 = require("rxjs/operators");
 const dd_trace_1 = __importDefault(require("dd-trace"));
+const rmq_diagnostics_function_1 = require("../functions/rmq-diagnostics.function");
 const redact_auth_data_function_1 = require("../functions/redact-auth-data.function");
 const grpc_param_metadata_function_1 = require("../functions/grpc-param-metadata.function");
 const { SERVER_NAME } = process.env;
 const msaLogger = new msa_logger_1.default(msa_logger_1.ServerTypeEnum.SERVICE);
 const MAX_CUT_LENGTH = 500;
+function readErrorProperty(error, key) {
+    if (error === null || error === undefined)
+        return undefined;
+    try {
+        return Reflect.get(Object(error), key);
+    }
+    catch {
+        return undefined;
+    }
+}
 dd_trace_1.default.init();
 let LoggingServiceInterceptor = class LoggingServiceInterceptor {
     keyCutter(data) {
@@ -108,6 +119,7 @@ let LoggingServiceInterceptor = class LoggingServiceInterceptor {
             pattern = content.pattern;
             payload = context.switchToHttp().getRequest().payload;
         }
+        const connection = isGrpc ? undefined : (0, rmq_diagnostics_function_1.getRmqDiagnosticSnapshot)(rmqContext.getChannelRef());
         const pastParam = JSON.parse(JSON.stringify(param));
         const pastFrom = pastParam.from || '-';
         const pastFroms = pastParam.froms || [pastFrom];
@@ -171,22 +183,47 @@ let LoggingServiceInterceptor = class LoggingServiceInterceptor {
                 loggingSpan.finish();
             }
         })).pipe((0, operators_1.catchError)((error) => {
+            const diagnostic = connection ? (0, msa_logger_1.normalizeDiagnosticError)(error, 'service_error') : undefined;
+            const frame = diagnostic === null || diagnostic === void 0 ? void 0 : diagnostic.details.errors[0];
+            const subMessageValue = readErrorProperty(error, 'subMessage');
+            let subMessage = typeof subMessageValue === 'string' ? subMessageValue : undefined;
+            if (subMessage && diagnostic)
+                subMessage = (0, msa_logger_1.sanitizeDiagnosticText)(subMessage);
+            const messageValue = readErrorProperty(error, 'message');
+            const errorMessage = (frame === null || frame === void 0 ? void 0 : frame.message) || (typeof messageValue === 'string' ? messageValue : undefined)
+                || (typeof error === 'string' ? error : undefined);
+            const nameValue = readErrorProperty(error, 'name');
+            const errorName = (frame === null || frame === void 0 ? void 0 : frame.name) || (typeof nameValue === 'string' ? nameValue : 'UNKNOWN_ERROR');
+            const stackValue = readErrorProperty(error, 'stack');
+            const errorStack = (frame === null || frame === void 0 ? void 0 : frame.stack) || (typeof stackValue === 'string' ? stackValue : undefined);
+            const statusValue = readErrorProperty(error, 'status');
+            const status = typeof statusValue === 'number' ? statusValue : 500;
+            const errOption = readErrorProperty(error, 'errOption');
             if (loggingSpan) {
                 loggingSpan.setTag('error', true);
-                loggingSpan.setTag('error.message', error.message);
-                loggingSpan.setTag('error.status', error.status);
-                loggingSpan.setTag('error.subMessage', error.subMessage);
-                loggingSpan.setTag('error.stack', error.stack);
-                loggingSpan.setTag('error.type', error.constructor.name);
+                loggingSpan.setTag('error.message', errorMessage);
+                loggingSpan.setTag('error.status', status);
+                loggingSpan.setTag('error.subMessage', subMessage);
+                loggingSpan.setTag('error.stack', errorStack);
+                loggingSpan.setTag('error.type', errorName);
             }
             msaLogger.printExceptionFliterService({
+                diagnosticInfo: diagnostic ? {
+                    ...diagnostic.diagnosticInfo,
+                    ...(0, rmq_diagnostics_function_1.getRmqDiagnosticSnapshot)(rmqContext.getChannelRef()),
+                    event: 'handler_failed',
+                    messagePattern: (0, msa_logger_1.sanitizeDiagnosticText)(pattern).slice(0, 240),
+                    elapsedMs: Date.now() - now,
+                    startGeneration: connection === null || connection === void 0 ? void 0 : connection.generation,
+                    startConnectionState: connection === null || connection === void 0 ? void 0 : connection.connectionState,
+                } : undefined,
                 traceId,
                 errInfo: {
-                    errType: error.subMessage ? error.message : error.name,
-                    message: error.subMessage ? error.subMessage : error.message,
-                    status: error.status,
-                    stack: error.stack,
-                    errOption: error.errOption,
+                    errType: subMessage ? errorMessage || errorName : errorName,
+                    message: subMessage || errorMessage,
+                    status,
+                    stack: errorStack,
+                    errOption,
                 },
                 messageBrokerInfo: {
                     messagePatten: pattern,
@@ -196,12 +233,12 @@ let LoggingServiceInterceptor = class LoggingServiceInterceptor {
                     from: pastFrom,
                     froms: pastFroms,
                 },
-            });
+            }, diagnostic === null || diagnostic === void 0 ? void 0 : diagnostic.details);
             const elapsed = Date.now() - now;
             msaLogger.printOutService({
                 traceId,
                 responseInfo: {
-                    status: error.status,
+                    status,
                     ms: elapsed,
                 },
                 messageBrokerInfo: {

package/interceptors/rpc.interceptor.js

@@ -48,6 +48,7 @@ const functions_1 = require("../functions");
 const exceptions_1 = require("../exceptions");
 const context_promise_patch_1 = require("../functions/abort/context-promise-patch");
 const graceful_shutdown_service_1 = require("../modules/graceful-shutdown/graceful-shutdown.service");
+const rmq_diagnostics_function_1 = require("../functions/rmq-diagnostics.function");
 const msaLogger = new msa_logger_1.default(msa_logger_1.ServerTypeEnum.SERVICE);
 // const MAX_CUT_LENGTH = 500;
 const MAX_LENGTH = 300;
@@ -154,6 +155,7 @@ let RPCInterceptor = class RPCInterceptor {
         const arg = args[0];
         const rmq = args[1];
         const channel = rmq.getChannelRef();
+        const startConnection = (0, rmq_diagnostics_function_1.getRmqDiagnosticSnapshot)(channel);
         const message = rmq.getMessage();
         const now = Date.now();
         const content = JSON.parse(message.content.toString());
@@ -206,7 +208,7 @@ let RPCInterceptor = class RPCInterceptor {
         }
         const noAck = message.fields.routingKey.includes('ASYNC');
         let localErrorProcessor = async (err) => {
-            var _a;
+            var _a, _b;
             const errMsg = err.response ? err.response : err.message;
             const status = err.status ? err.status : 500;
             const errType = err.errType;
@@ -278,10 +280,28 @@ let RPCInterceptor = class RPCInterceptor {
                 }
             }
             const sendMessage = Buffer.from(JSON.stringify(abstractAmqpHandlerData));
-            if (!isAck) {
+            const diagnostic = startConnection
+                ? (0, msa_logger_1.normalizeDiagnosticError)(err, isTimeoutError ? 'response_timeout' : 'service_error') : undefined;
+            const diagnosticInfo = diagnostic ? {
+                ...diagnostic.diagnosticInfo,
+                ...(0, rmq_diagnostics_function_1.getRmqDiagnosticSnapshot)(channel),
+                event: 'handler_failed',
+                messagePattern: (0, msa_logger_1.sanitizeDiagnosticText)(String(method)).slice(0, 240),
+                elapsedMs: duration,
+                startGeneration: startConnection === null || startConnection === void 0 ? void 0 : startConnection.generation,
+                startConnectionState: startConnection === null || startConnection === void 0 ? void 0 : startConnection.connectionState,
+            } : undefined;
+            if (!isAck || diagnostic) {
                 const currentContext = functions_1.AbortContext.getCurrentContext();
-                // 에러 전달
-                msaLogger.warn('에러 응답 전송 처리', { traceId: execInterceptor.traceId }, {
+                msaLogger.warn(isAck ? 'RPCInterceptor 오류 처리' : '에러 응답 전송 처리', {
+                    traceId: execInterceptor.traceId,
+                    diagnosticInfo,
+                }, diagnostic ? {
+                    error: diagnostic.details,
+                    reDeliveryCount,
+                    staticRetryCount,
+                    currentContext: (_a = currentContext === null || currentContext === void 0 ? void 0 : currentContext.requestId) !== null && _a !== void 0 ? _a : null,
+                } : {
                     error: {
                         message: err.message,
                         stack: err.stack,
@@ -293,11 +313,13 @@ let RPCInterceptor = class RPCInterceptor {
                     messagePattern: method,
                     currentContext: currentContext && currentContext.requestId ? currentContext.requestId : null,
                 });
+            }
+            if (!isAck) {
                 channel.sendToQueue(message.properties.replyTo, sendMessage, { correlationId: message.properties.correlationId });
             }
             const messageContent = message.content.toString();
             /** 파일 객체 처리 */
-            (0, functions_1.reWriteFileValue)((_a = messageContent === null || messageContent === void 0 ? void 0 : messageContent.data) === null || _a === void 0 ? void 0 : _a.file);
+            (0, functions_1.reWriteFileValue)((_b = messageContent === null || messageContent === void 0 ? void 0 : messageContent.data) === null || _b === void 0 ? void 0 : _b.file);
             if (!noAck && !isAck) {
                 channel.ack(message);
                 execInterceptor.isMessageAck = true;

package/interfaces/http.d.ts

@@ -1,5 +1,5 @@
-import { Method } from 'axios';
 import { ErrInfo } from './exception';
+type RequestLogMethod = 'GET' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'POST' | 'PUT' | 'PATCH' | 'PURGE' | 'LINK' | 'UNLINK';
 export interface ExternalTokenValue {
     provider: string;
     client_id: string;
@@ -16,7 +16,7 @@ export interface DeviceRequest {
 export interface RequestLog {
     query?: unknown;
     body?: unknown;
-    method: Method;
+    method: RequestLogMethod | Lowercase<RequestLogMethod>;
     endpoint: string;
 }
 /** 최신 에러 정보 */
@@ -98,3 +98,4 @@ export interface ExternalResponseNormalize<T> {
 export interface ResponseAction {
     result: boolean;
 }
+export {};

package/modules/graceful-shutdown/graceful-shutdown.rmq.d.ts

@@ -13,12 +13,14 @@ export type GracefulRmqOptions = RmqOptions['options'] & {
  */
 export declare class GracefulServerRMQ extends ServerRMQ {
     protected readonly options: GracefulRmqOptions;
+    private readonly observation?;
     protected runningMessages: number;
     protected closing: boolean;
     protected consumerTag: string | null;
     protected readonly waitingEndingHandlersTimeoutMs: number;
     protected readonly waitingEndingHandlersIntervalMs: number;
     constructor(options: GracefulRmqOptions);
+    createClient(): any;
     setupChannel(channel: Channel, callback: () => void): Promise<void>;
     protected waitingHandlers(): Promise<void>;
     handleMessage(message: ConsumeMessage, channel: Channel): Promise<void>;

package/modules/graceful-shutdown/graceful-shutdown.rmq.js

@@ -7,6 +7,7 @@ exports.GracefulServerRMQ = void 0;
 const microservices_1 = require("@nestjs/microservices");
 const os_1 = __importDefault(require("os"));
 const node_util_1 = require("node:util");
+const rmq_diagnostics_function_1 = require("../../functions/rmq-diagnostics.function");
 const sleep = (0, node_util_1.promisify)(setTimeout);
 const RMQ_DEFAULT_WAITING_ENDING_HANDLERS_TIMEOUT_MS = 5000;
 const RMQ_DEFAULT_WAITING_ENDING_HANDLERS_INTERVAL_MS = 500;
@@ -56,21 +57,32 @@ function addRmqConnectionName(options) {
  */
 class GracefulServerRMQ extends microservices_1.ServerRMQ {
     constructor(options) {
-        const optionsWithConnectionName = addRmqConnectionName(options);
+        const observation = (0, rmq_diagnostics_function_1.isRmqDiagnosticsEnabled)() ? (0, rmq_diagnostics_function_1.createRmqObserver)(options, 'consumer') : undefined;
+        const optionsWithConnectionName = observation
+            ? (0, rmq_diagnostics_function_1.withRmqConnectionName)(options, observation) : addRmqConnectionName(options);
         super(optionsWithConnectionName);
         this.runningMessages = 0;
         this.closing = false;
         this.consumerTag = null;
         this.options = optionsWithConnectionName;
+        this.observation = observation;
         this.waitingEndingHandlersTimeoutMs = this.getOptionsProp(this.options, 'waitingEndingHandlersTimeoutMs')
             || RMQ_DEFAULT_WAITING_ENDING_HANDLERS_TIMEOUT_MS;
         this.waitingEndingHandlersIntervalMs = this.getOptionsProp(this.options, 'waitingEndingHandlersIntervalMs')
             || RMQ_DEFAULT_WAITING_ENDING_HANDLERS_INTERVAL_MS;
     }
+    createClient() {
+        var _a;
+        const client = super.createClient();
+        (_a = this.observation) === null || _a === void 0 ? void 0 : _a.observe(client);
+        return client;
+    }
     async setupChannel(channel, callback) {
         if (this.closing) {
             return;
         }
+        if (this.observation)
+            (0, rmq_diagnostics_function_1.registerRmqObservation)(channel, this.observation);
         if (!this.queueOptions.noAssert) {
             await channel.assertQueue(this.queue, this.queueOptions);
         }
@@ -91,18 +103,24 @@ class GracefulServerRMQ extends microservices_1.ServerRMQ {
         });
     }
     async close() {
+        var _a;
         this.closing = true;
-        if (this.channel) {
-            await this.channel.removeSetup(undefined, (channel) => channel.cancel(this.consumerTag));
+        try {
+            if (this.channel) {
+                await this.channel.removeSetup(undefined, (channel) => channel.cancel(this.consumerTag));
+            }
+            this.consumerTag = null;
+            await Promise.race([
+                this.waitingHandlers(),
+                this.waitingEndingHandlersTimeoutMs > 0
+                    && sleep(this.waitingEndingHandlersTimeoutMs),
+            ]);
+            this.runningMessages = 0;
+            await super.close();
+        }
+        finally {
+            (_a = this.observation) === null || _a === void 0 ? void 0 : _a.close();
         }
-        this.consumerTag = null;
-        await Promise.race([
-            this.waitingHandlers(),
-            this.waitingEndingHandlersTimeoutMs > 0
-                && sleep(this.waitingEndingHandlersTimeoutMs),
-        ]);
-        this.runningMessages = 0;
-        super.close();
     }
 }
 exports.GracefulServerRMQ = GracefulServerRMQ;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-croket-dev/core",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "author": "Yolo Co., Ltd.",
   "description": "Yolo commonization module",
   "main": "index.js",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@yolo-croket-dev/logger": "^1.0.15",
-    "@yolo-croket-dev/msa-logger": "^3.5.0",
+    "@yolo-croket-dev/msa-logger": "3.5.3",
     "@yolo-croket-dev/redis": "^1.0.25",
     "axios": "^1.1.3",
     "randomstring": "^1.2.2",

package/tests/rmq-consumer-diagnostics.test.cjs

@@ -0,0 +1,150 @@
+const assert = require('node:assert/strict');
+const { EventEmitter } = require('node:events');
+const test = require('node:test');
+const { ServerRMQ, RmqContext } = require('@nestjs/microservices');
+const { lastValueFrom, throwError } = require('rxjs');
+const { MsaLogger } = require('@yolo-croket-dev/msa-logger');
+const { GracefulServerRMQ } = require('../modules/graceful-shutdown/graceful-shutdown.rmq');
+const { LoggingServiceInterceptor } = require('../interceptors/logging-service.interceptor');
+const { RPCInterceptor } = require('../interceptors/rpc.interceptor');
+const { getRmqDiagnosticSnapshot, RmqConnectionObserver, registerRmqObservation } = require('../functions/rmq-diagnostics.function');
+
+test('default/manage consumers preserve QoS/ACK, correlate failures and dispose observers on close', async t => {
+  const flag = process.env.RMQ_DIAGNOSTICS_ENABLED;
+  process.env.RMQ_DIAGNOSTICS_ENABLED = 'true';
+  t.after(() => { if (flag === undefined) delete process.env.RMQ_DIAGNOSTICS_ENABLED; else process.env.RMQ_DIAGNOSTICS_ENABLED = flag; });
+  const managers = [];
+  t.mock.method(ServerRMQ.prototype, 'createClient', () => {
+    const manager = new EventEmitter(); managers.push(manager); return manager;
+  });
+  const close = t.mock.method(ServerRMQ.prototype, 'close', () => {});
+  const errors = [];
+  for (const method of ['info', 'warn', 'printInputInterceptorService', 'printOutService']) t.mock.method(MsaLogger.prototype, method, () => {});
+  t.mock.method(MsaLogger.prototype, 'printExceptionFliterService', (info, details) => errors.push({ info, details }));
+  const identities = new Set();
+  for (const queue of ['USER_SERVICE', 'MANAGE_SERVICE']) {
+    const calls = [];
+    const channel = {
+      assertQueue: async (...args) => calls.push(['assert', ...args]),
+      prefetch: async (...args) => calls.push(['prefetch', ...args]),
+      consume: async (...args) => { calls.push(['consume', ...args]); return { consumerTag: 'tag' }; },
+      cancel: async tag => calls.push(['cancel', tag]),
+    };
+    const server = new GracefulServerRMQ({ queue, noAck: false, prefetchCount: 7, queueOptions: { durable: true, deadLetterExchange: 'existing.dlx' }, waitingEndingHandlersTimeoutMs: 1 });
+    const manager = server.createClient(); manager.emit('connect');
+    await server.setupChannel(channel, () => {});
+    assert.deepEqual(calls[0], ['assert', queue, { durable: true, deadLetterExchange: 'existing.dlx' }]);
+    assert.deepEqual(calls[1], ['prefetch', 7, undefined]);
+    assert.deepEqual(calls[2][3], { noAck: false });
+    const snapshot = getRmqDiagnosticSnapshot(channel);
+    identities.add(snapshot.connectionId);
+    const data = { payload: { ok: true }, param: { traceId: 'consumer-trace' } };
+    const context = new RmqContext([{ content: Buffer.from(JSON.stringify({ pattern: 'test.receive' })) }, channel, 'test.receive']);
+    const execution = { getArgs: () => [data, context], switchToRpc: () => ({ getContext: () => context, getData: () => data }), switchToHttp: () => ({ getRequest: () => data }) };
+    const error = Object.assign(Error('handler failed'), { status: 409, errOption: { logErrorLevel: 'warn' } });
+    await assert.rejects(lastValueFrom(new LoggingServiceInterceptor().intercept(execution, { handle: () => throwError(() => error) })), actual => actual === error);
+    const record = errors.at(-1);
+    assert.equal(record.info.diagnosticInfo.connectionId, snapshot.connectionId);
+    assert.equal(record.info.diagnosticInfo.targetService, queue);
+    assert.equal(record.info.diagnosticInfo.direction, 'consumer');
+    assert.equal(record.info.diagnosticInfo.kind, 'service_error');
+    assert.equal(record.info.errInfo.errOption.logErrorLevel, 'warn');
+    server.channel = { removeSetup: async (_, cancel) => cancel(channel) };
+    await server.close();
+    assert.deepEqual(calls.at(-1), ['cancel', 'tag']);
+    assert.equal(manager.eventNames().length, 0);
+  }
+  assert.equal(identities.size, 2);
+  assert.equal(close.mock.callCount(), 2);
+});
+
+test('primitive and getter failures retain the original rejection and emit diagnostics', async t => {
+  const output = [];
+  for (const method of ['printInputInterceptorService', 'printOutService']) t.mock.method(MsaLogger.prototype, method, () => {});
+  t.mock.method(MsaLogger.prototype, 'printExceptionFliterService', (info, details) => output.push({ info, details }));
+  const channel = {};
+  registerRmqObservation(channel, new RmqConnectionObserver('USER_SERVICE', 'consumer', undefined, () => {}));
+  const data = { payload: {}, param: { traceId: 'primitive-error' } };
+  const context = new RmqContext([{ content: Buffer.from(JSON.stringify({ pattern: 'test.receive' })) }, channel, 'test.receive']);
+  const execution = { getArgs: () => [data, context], switchToRpc: () => ({ getContext: () => context, getData: () => data }), switchToHttp: () => ({ getRequest: () => data }) };
+  const throwingGetter = new Proxy({}, { get() { throw Error('getter failed'); } });
+  for (const original of [null, 'remote failed', throwingGetter]) {
+    const settled = await Promise.allSettled([lastValueFrom(new LoggingServiceInterceptor().intercept(execution, { handle: () => throwError(() => original) }))]);
+    assert.equal(settled[0].status, 'rejected');
+    assert.equal(settled[0].reason, original);
+    assert.equal(output.at(-1).info.traceId, 'primitive-error');
+    assert.equal(output.at(-1).info.diagnosticInfo.event, 'handler_failed');
+  }
+});
+
+test('consumer observer is disposed even when channel setup removal fails', async t => {
+  const flag = process.env.RMQ_DIAGNOSTICS_ENABLED;
+  process.env.RMQ_DIAGNOSTICS_ENABLED = 'true';
+  t.after(() => { if (flag === undefined) delete process.env.RMQ_DIAGNOSTICS_ENABLED; else process.env.RMQ_DIAGNOSTICS_ENABLED = flag; });
+  const manager = new EventEmitter();
+  t.mock.method(ServerRMQ.prototype, 'createClient', () => manager);
+  t.mock.method(ServerRMQ.prototype, 'close', () => {});
+  const server = new GracefulServerRMQ({ queue: 'USER_SERVICE' });
+  server.createClient();
+  server.channel = { removeSetup: async () => { throw Error('channel closed'); } };
+  await assert.rejects(server.close(), /channel closed/);
+  assert.equal(manager.listenerCount('connect'), 0);
+});
+
+test('RPC-only consumer failure keeps the existing reply and adds connection diagnostics to its warning', async t => {
+  const warnings = [];
+  t.mock.method(MsaLogger.prototype, 'warn', (message, info, details) => warnings.push({ message, info, details }));
+  const replies = [];
+  const channel = {
+    sendToQueue: (...args) => replies.push(args),
+    ack: () => {},
+  };
+  const observer = new RmqConnectionObserver('MANAGE_SERVICE', 'consumer', undefined, () => {});
+  registerRmqObservation(channel, observer);
+  const request = { pattern: 'manage.fail', data: { payload: {}, param: { traceId: 'rpc-only' } } };
+  const message = {
+    content: Buffer.from(JSON.stringify(request)),
+    properties: { headers: {}, correlationId: 'correlation', replyTo: 'reply.queue' },
+    fields: { routingKey: 'MANAGE_SERVICE', consumerTag: 'consumer' },
+  };
+  const context = { getArgs: () => [{}, new RmqContext([message, channel, 'manage.fail'])], getHandler: () => function handler() {} };
+  const interceptor = new RPCInterceptor({ get: () => ({ isAdminGuard: true }) }, { isApplicationExit: false });
+  await interceptor.intercept(context, { handle: () => { throw Error('guard should reject first'); } });
+  assert.equal(warnings.length, 1);
+  assert.equal(warnings[0].info.traceId, 'rpc-only');
+  assert.equal(warnings[0].info.diagnosticInfo.connectionId, observer.connectionId);
+  assert.equal(warnings[0].info.diagnosticInfo.targetService, 'MANAGE_SERVICE');
+  assert.equal(warnings[0].info.diagnosticInfo.messagePattern, 'manage.fail');
+  assert.equal(warnings[0].info.diagnosticInfo.event, 'handler_failed');
+  assert.equal(replies.length, 1);
+  assert.equal(JSON.parse(replies[0][1].toString()).isError, true);
+});
+
+test('RPC-only handler failure records its trace and channel on the existing warning', async t => {
+  const warnings = [];
+  t.mock.method(MsaLogger.prototype, 'warn', (message, info) => warnings.push({ message, info }));
+  const acknowledgements = [];
+  const channel = {
+    sendToQueue: () => {},
+    ack: message => acknowledgements.push(message),
+  };
+  const observer = new RmqConnectionObserver('MANAGE_SERVICE', 'consumer', undefined, () => {});
+  registerRmqObservation(channel, observer);
+  const request = { pattern: 'manage.fail', data: { payload: {}, param: { traceId: 'handler-trace' } } };
+  const message = {
+    content: Buffer.from(JSON.stringify(request)),
+    properties: { headers: {}, correlationId: 'correlation', replyTo: 'reply.queue' },
+    fields: { routingKey: 'MANAGE_SERVICE', consumerTag: 'consumer' },
+  };
+  const context = { getArgs: () => [{}, new RmqContext([message, channel, 'manage.fail'])], getHandler: () => function handler() {} };
+  const shutdown = { isApplicationExit: false, pushActiveInterceptors: () => {}, popActiveInterceptors: () => {} };
+  const interceptor = new RPCInterceptor({ get: () => undefined }, shutdown);
+  const failure = Error('handler failed');
+  const stream = await interceptor.intercept(context, { handle: () => throwError(() => failure) });
+  await assert.rejects(lastValueFrom(stream), actual => actual === failure);
+  assert.equal(warnings.length, 1);
+  assert.equal(warnings[0].info.traceId, 'handler-trace');
+  assert.equal(warnings[0].info.diagnosticInfo.connectionId, observer.connectionId);
+  assert.equal(warnings[0].info.diagnosticInfo.event, 'handler_failed');
+  assert.equal(acknowledgements.length, 1);
+});

package/tests/rmq-diagnostics.test.cjs

@@ -0,0 +1,177 @@
+const assert = require('node:assert/strict');
+const { EventEmitter } = require('node:events');
+const test = require('node:test');
+const { Observable, of, throwError } = require('rxjs');
+const { ClientRMQ, Transport } = require('@nestjs/microservices');
+const { MsaLogger } = require('@yolo-croket-dev/msa-logger');
+const {
+  RmqConnectionObserver, createDiagnosticRmqClient, registerRmqObservation, getRmqDiagnosticSnapshot,
+} = require('../functions/rmq-diagnostics.function');
+const { AmqpHandler, HttpExceptionCustom } = require('../functions/amqp-handler.function');
+const { AmqpManagement } = require('../functions/amqp-call-manager.function');
+
+test('connection events have no request context; generation, summary and cleanup follow lifecycle', t => {
+  t.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
+  const records = [];
+  const observer = new RmqConnectionObserver('USER_SERVICE', 'client', undefined, (info, details) => records.push({ info, details }));
+  const manager = new EventEmitter();
+  observer.observe(manager); observer.observe(manager);
+  assert.equal(manager.listenerCount('connectFailed'), 1);
+  assert.equal(observer.snapshot().connectionState, 'not_connected');
+  const error = Object.assign(Error('refused amqp://user:password@host'), { code: 'ECONNREFUSED' });
+  manager.emit('connectFailed', { err: error });
+  for (let i = 0; i < 100; i += 1) manager.emit('connectFailed', { err: error });
+  assert.equal(records.length, 1);
+  t.mock.timers.tick(60_000);
+  assert.equal(records[1].info.repeatCount, 100);
+  manager.emit('connectFailed', { err: error });
+  manager.emit('connect', {});
+  assert.equal(records[2].info.repeatCount, 1);
+  assert.equal(observer.snapshot().generation, 1);
+  manager.emit('blocked', { reason: 'private' });
+  assert.equal(observer.snapshot().connectionState, 'blocked');
+  manager.emit('unblocked');
+  manager.emit('disconnect', { err: Error('closed') });
+  assert.equal(records.at(-1).info.kind, 'connection_lost');
+  manager.emit('connect', {});
+  assert.equal(observer.snapshot().generation, 2);
+  manager.emit('connectFailed', { err: error });
+  manager.emit('connectFailed', { err: error });
+  observer.close();
+  const count = records.length;
+  t.mock.timers.tick(120_000);
+  manager.emit('connect', {});
+  assert.equal(records.length, count);
+  assert.equal(manager.eventNames().length, 0);
+  assert.ok(!JSON.stringify(records).includes('user:password'));
+  assert.ok(!JSON.stringify(records).includes('private'));
+});
+
+test('factory is lazy, preserves transport options and configured names, opt-in defaults off', async t => {
+  const previous = process.env.RMQ_DIAGNOSTICS_ENABLED;
+  t.after(() => { if (previous === undefined) delete process.env.RMQ_DIAGNOSTICS_ENABLED; else process.env.RMQ_DIAGNOSTICS_ENABLED = previous; });
+  const createSpy = t.mock.method(ClientRMQ.prototype, 'createClient', () => { throw Error('must remain lazy'); });
+  const options = {
+    transport: Transport.RMQ,
+    options: { queue: 'USER_SERVICE', noAck: true, queueOptions: { noAssert: true, durable: true },
+      socketOptions: { heartbeatIntervalInSeconds: 60, connectionOptions: { clientProperties: { connection_name: 'explicit' } } } },
+  };
+  const copy = JSON.stringify(options);
+  delete process.env.RMQ_DIAGNOSTICS_ENABLED;
+  const disabled = createDiagnosticRmqClient(options);
+  assert.equal(getRmqDiagnosticSnapshot(disabled), undefined);
+  process.env.RMQ_DIAGNOSTICS_ENABLED = 'true';
+  const client = createDiagnosticRmqClient(options);
+  const other = createDiagnosticRmqClient(options);
+  assert.equal(createSpy.mock.callCount(), 0);
+  assert.equal(getRmqDiagnosticSnapshot(client).connectionState, 'not_connected');
+  assert.equal(getRmqDiagnosticSnapshot(client).connectionName, 'explicit');
+  assert.notEqual(getRmqDiagnosticSnapshot(client).connectionId, getRmqDiagnosticSnapshot(other).connectionId);
+  assert.equal(JSON.stringify(options), copy);
+  assert.deepEqual(client.options, options.options);
+  await disabled.close(); await client.close(); await other.close();
+});
+
+test('same trace and shared error retain each call target and start/failure generation', async t => {
+  const records = [];
+  t.mock.method(MsaLogger.prototype, 'warn', (message, info, details) => records.push({ message, info, details }));
+  const error = { err: Object.assign(Error('reset'), { code: 'ECONNRESET' }) };
+  const subscribers = [];
+  const calls = ['USER_SERVICE', 'PAYMENT_SERVICE'].map(target => {
+    const observer = new RmqConnectionObserver(target, 'client', undefined, () => {});
+    const manager = new EventEmitter(); observer.observe(manager);
+    const client = { send: () => new Observable(subscriber => { subscribers.push(subscriber); }) };
+    registerRmqObservation(client, observer);
+    const promise = AmqpHandler(client, `test.${target}`, { payload: { secret: 'not logged' }, param: { traceId: 'same', timeout: 1000 } });
+    manager.emit('connect'); manager.emit('disconnect', error); manager.emit('connect');
+    return promise;
+  });
+  const results = Promise.allSettled(calls);
+  subscribers.forEach(subscriber => subscriber.error(error));
+  assert.ok((await results).every(result => result.reason === error));
+  assert.equal(records.length, 2);
+  assert.deepEqual(records.map(record => record.info.diagnosticInfo.targetService), ['USER_SERVICE', 'PAYMENT_SERVICE']);
+  for (const record of records) {
+    assert.equal(record.info.traceId, 'same');
+    assert.equal(record.info.diagnosticInfo.startGeneration, 0);
+    assert.equal(record.info.diagnosticInfo.startConnectionState, 'not_connected');
+    assert.equal(record.info.diagnosticInfo.generation, 2);
+    assert.equal(record.info.diagnosticInfo.kind, 'connection_lost');
+    assert.equal(record.info.diagnosticInfo.timeoutMs, 1000);
+  }
+  assert.ok(!JSON.stringify(records).includes('not logged'));
+});
+
+test('success adds no logs; initial connect failure, timeout, service and no-handler stay distinct', async t => {
+  const records = [];
+  for (const method of ['info', 'warn', 'error']) t.mock.method(MsaLogger.prototype, method, (message, info) => records.push(info));
+  const observer = new RmqConnectionObserver('USER_SERVICE', 'client', undefined, () => {});
+  const cases = [
+    [() => throwError(() => ({ err: Object.assign(Error('refused'), { code: 'ECONNREFUSED' }) })), 'connection_failed'],
+    [() => new Observable(() => {}), 'response_timeout'],
+    [() => of({ isError: true, status: 400, errType: 'BUSINESS', errMessage: 'no' }), 'service_error'],
+    [() => throwError(() => 'There is no matching message handler defined in the remote service.'), 'handler_not_found'],
+  ];
+  for (const [send, kind] of cases) {
+    const client = { send }; registerRmqObservation(client, observer);
+    await assert.rejects(AmqpHandler(client, 'test.call', { payload: {}, param: { traceId: kind, timeout: 5 } }));
+    assert.equal(records.at(-1).diagnosticInfo.kind, kind);
+  }
+  const client = { send: () => of({ data: 42 }) }; registerRmqObservation(client, observer);
+  const count = records.length;
+  assert.deepEqual(await AmqpHandler(client, 'ok', { payload: {}, param: { traceId: 'ok' } }), { data: 42 });
+  assert.equal(records.length, count);
+  const business = { send: () => of({ isError: true, status: 409, errType: 'EXISTS', errMessage: 'exists' }) };
+  registerRmqObservation(business, observer);
+  await assert.rejects(AmqpHandler(business, 'test.call', { payload: {}, param: { traceId: 'business' } }), err => {
+    assert.ok(err instanceof HttpExceptionCustom); assert.equal(err.getStatus(), 409); assert.equal(err.errInfo.type, 'EXISTS'); return true;
+  });
+});
+
+test('legacy unobserved clients report failed pattern without inventing connection state', async t => {
+  const previous = process.env.RMQ_DIAGNOSTICS_ENABLED;
+  process.env.RMQ_DIAGNOSTICS_ENABLED = 'true';
+  t.after(() => { if (previous === undefined) delete process.env.RMQ_DIAGNOSTICS_ENABLED; else process.env.RMQ_DIAGNOSTICS_ENABLED = previous; });
+  const records = [];
+  t.mock.method(MsaLogger.prototype, 'warn', (message, info) => records.push({ message, info }));
+  const client = { send: () => throwError(() => Object.assign(Error('connection reset'), { code: 'ECONNRESET' })) };
+
+  await assert.rejects(AmqpHandler(client, 'user.lookup', { payload: {}, param: { traceId: 'legacy-call' } }));
+  assert.equal(records.length, 1);
+  assert.equal(records[0].info.traceId, 'legacy-call');
+  assert.equal(records[0].info.diagnosticInfo.messagePattern, 'user.lookup');
+  assert.equal(records[0].info.diagnosticInfo.connectionState, 'unobserved');
+  assert.equal(records[0].info.diagnosticInfo.connectionId, undefined);
+
+  const legacyClient = new ClientRMQ({ queue: 'USER_SERVICE' });
+  legacyClient.send = client.send;
+  await assert.rejects(AmqpHandler(legacyClient, 'user.lookup', { payload: {}, param: { traceId: 'legacy-rmq' } }));
+  assert.equal(records[1].info.diagnosticInfo.targetService, 'USER_SERVICE');
+
+  const manager = new AmqpManagement(legacyClient);
+  await assert.rejects(manager.call('lookup', 'user.lookup', {}, { traceId: 'legacy-wrapper' }, { isErrorThrowing: true }));
+  assert.equal(records.length, 3);
+  assert.equal(records[2].info.traceId, 'legacy-wrapper');
+});
+
+test('close waits for native async close and retains its rejection after listener cleanup', async t => {
+  const previous = process.env.RMQ_DIAGNOSTICS_ENABLED;
+  process.env.RMQ_DIAGNOSTICS_ENABLED = 'true';
+  t.after(() => { if (previous === undefined) delete process.env.RMQ_DIAGNOSTICS_ENABLED; else process.env.RMQ_DIAGNOSTICS_ENABLED = previous; });
+  const manager = new EventEmitter();
+  t.mock.method(ClientRMQ.prototype, 'createClient', () => manager);
+  let finish;
+  t.mock.method(ClientRMQ.prototype, 'close', () => new Promise((resolve, reject) => { finish = reject; }));
+  const client = createDiagnosticRmqClient({ transport: Transport.RMQ, options: { queue: 'TEST' } });
+  client.createClient();
+  let settled = false;
+  const error = Error('close failed');
+  const closed = client.close().finally(() => { settled = true; });
+  const rejected = assert.rejects(closed, err => err === error);
+  await Promise.resolve();
+  assert.equal(settled, false);
+  assert.equal(manager.listenerCount('connect'), 1);
+  finish(error);
+  await rejected;
+  assert.equal(manager.listenerCount('connect'), 0);
+});