@lad-tech/nsc-toolkit 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
-# [1.27.0](https://github.com/lad-tech/nsc-toolkit/compare/v1.26.2...v1.27.0) (2025-02-06)
+# [1.28.0](https://github.com/lad-tech/nsc-toolkit/compare/v1.27.0...v1.28.0) (2025-05-12)
 
 
 ### Features
 
-* New option for consumer ackPolicy ([#144](https://github.com/lad-tech/nsc-toolkit/issues/144)) ([0426f4e](https://github.com/lad-tech/nsc-toolkit/commit/0426f4e1da4ff092354f0e175d9ad9a295dfb074))
+* Async event traces and tags ([#145](https://github.com/lad-tech/nsc-toolkit/issues/145)) ([02c3560](https://github.com/lad-tech/nsc-toolkit/commit/02c356051d295d528c4cc7758b2a310d37074424))

package/dist/Client.js

@@ -10,6 +10,7 @@ const node_stream_1 = require("node:stream");
 const promises_1 = require("node:timers/promises");
 const Root_1 = require("./Root");
 const StreamManager_1 = require("./StreamManager");
+const Meter_1 = require("./Meter");
 class Client extends Root_1.Root {
     constructor({ broker, events, loggerOutputFormatter, serviceName, baggage, cache, Ref }) {
         super(broker, loggerOutputFormatter);
@@ -35,6 +36,11 @@ class Client extends Root_1.Root {
                 data = (0, nats_1.StringCodec)().decode(event.data);
             }
             const message = { data };
+            let baggage;
+            if (event.headers) {
+                baggage = this.getBaggageFromNATSHeader(event.headers);
+            }
+            message.meter = new Meter_1.Meter(eventName, baggage);
             if (this.isJsMessage(event)) {
                 message.ack = event.ack.bind(event);
                 message.nak = event.nak.bind(event);
@@ -264,31 +270,23 @@ class Client extends Root_1.Root {
             request.end();
         });
     }
-    convertBaggaggeToExternalHeader(baggage) {
-        if (!baggage) {
-            return {};
-        }
-        const headers = {};
-        if (baggage.expired) {
-            headers['nsc-expired'] = baggage.expired;
-        }
-        if (baggage.requestId) {
-            headers['x-request-id'] = baggage.requestId;
-        }
-        if (baggage.traceId) {
-            headers['nsc-trace-id'] = baggage.traceId;
-        }
-        if (baggage.spanId) {
-            headers['nsc-span-id'] = baggage.spanId;
-        }
-        if (baggage.traceFlags) {
-            headers['nsc-trace-flags'] = baggage.traceFlags;
-        }
-        return headers;
-    }
     isJsMessage(message) {
         return !!message.ack && !!message.nak;
     }
+    getBaggageFromNATSHeader(headers) {
+        const traceId = headers.get('nsc-trace-id');
+        const spanId = headers.get('nsc-span-id');
+        const traceFlags = headers.has('nsc-trace-flags') ? +headers.get('nsc-trace-flags') : undefined;
+        const requestId = headers.has('x-request-id') ? String(headers.get('x-request-id')) : undefined;
+        if (traceId && spanId && traceFlags) {
+            return {
+                traceId,
+                spanId,
+                traceFlags,
+                requestId,
+            };
+        }
+    }
 }
 exports.Client = Client;
 //# sourceMappingURL=Client.js.map

package/dist/Meter.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Meter = void 0;
+const interfaces_1 = require("./interfaces");
+const opentelemetry = require("@opentelemetry/api");
+const Root_1 = require("./Root");
+class Meter extends Root_1.Root {
+    constructor(name, baggage) {
+        super();
+        this.name = name;
+        this.baggage = baggage;
+    }
+    start() {
+        const tracer = opentelemetry.trace.getTracer('');
+        this.span = tracer.startSpan(this.name, { kind: opentelemetry.SpanKind.CONSUMER }, this.getContext(this.baggage));
+    }
+    end(error) {
+        if (!this.span) {
+            return;
+        }
+        if (error) {
+            this.span.setAttribute('error', true);
+            this.span.setAttribute('error.kind', error.message);
+        }
+        this.span.end();
+    }
+    measure(func, arg, context, tag) {
+        const tracer = opentelemetry.trace.getTracer('');
+        let spanContext;
+        if (this.span) {
+            spanContext = opentelemetry.trace.setSpan(opentelemetry.context.active(), this.span);
+        }
+        const options = { kind: opentelemetry.SpanKind.INTERNAL };
+        if ((tag === null || tag === void 0 ? void 0 : tag[interfaces_1.TagKey.LOCATION]) === 'external') {
+            options.kind = opentelemetry.SpanKind.CLIENT;
+        }
+        const span = tracer.startSpan(func.name, options, spanContext);
+        this.applyTag(span, tag);
+        const result = func.apply(context, arg);
+        if (result.then) {
+            return result.then((result) => {
+                span.end();
+                return result;
+            }, (error) => {
+                span.setAttribute('error', true);
+                span.setAttribute('error.kind', error.message);
+                span.end();
+                throw error;
+            });
+        }
+        else {
+            span.end();
+        }
+        return result;
+    }
+}
+exports.Meter = Meter;
+//# sourceMappingURL=Meter.js.map

package/dist/Root.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Root = void 0;
 const toolbelt_1 = require("@lad-tech/toolbelt");
 const opentelemetry = require("@opentelemetry/api");
+const interfaces_1 = require("./interfaces");
 const Union_1 = require("./Union");
 class Root {
     constructor(broker, outputFormatter) {
@@ -52,7 +53,7 @@ class Root {
             return expired;
         }
         catch (error) {
-            console.error(error);
+            this.logger.error(error);
             process.exit(1);
         }
     }
@@ -75,6 +76,45 @@ class Root {
             },
         };
     }
+    convertBaggaggeToExternalHeader(baggage) {
+        if (!baggage) {
+            return {};
+        }
+        const headers = {};
+        if (baggage.expired) {
+            headers['nsc-expired'] = baggage.expired;
+        }
+        if (baggage.requestId) {
+            headers['x-request-id'] = baggage.requestId;
+        }
+        if (baggage.traceId) {
+            headers['nsc-trace-id'] = baggage.traceId;
+        }
+        if (baggage.spanId) {
+            headers['nsc-span-id'] = baggage.spanId;
+        }
+        if (baggage.traceFlags) {
+            headers['nsc-trace-flags'] = baggage.traceFlags;
+        }
+        return headers;
+    }
+    applyTag(span, tag) {
+        if (!tag) {
+            return;
+        }
+        if ((tag === null || tag === void 0 ? void 0 : tag[interfaces_1.TagKey.TYPE]) === 'dbms') {
+            span.setAttribute('db.system', tag === null || tag === void 0 ? void 0 : tag[interfaces_1.TagKey.NAME]);
+            if (tag === null || tag === void 0 ? void 0 : tag[interfaces_1.TagKey.TARGET]) {
+                span.setAttribute('db.name', tag[interfaces_1.TagKey.TARGET]);
+            }
+        }
+        if ((tag === null || tag === void 0 ? void 0 : tag[interfaces_1.TagKey.TYPE]) === 'api') {
+            span.setAttribute('net.peer.name', tag === null || tag === void 0 ? void 0 : tag[interfaces_1.TagKey.NAME]);
+            if (tag === null || tag === void 0 ? void 0 : tag[interfaces_1.TagKey.TARGET]) {
+                span.setAttribute('http.target', tag[interfaces_1.TagKey.TARGET]);
+            }
+        }
+    }
 }
 exports.Root = Root;
 //# sourceMappingURL=Root.js.map

package/dist/Service.js

@@ -44,11 +44,12 @@ class Service extends Root_1.Root {
         if (options.events) {
             const events = Object.keys(options.events.list);
             this.emitter = events.reduce((result, eventName) => {
-                result[eventName] = ((params, uniqId, rollupId) => {
+                result[eventName] = ((params, uniqId, rollupId, external) => {
                     var _a, _b, _c;
                     const subject = [options.name];
                     const eventOptions = (_a = options.events) === null || _a === void 0 ? void 0 : _a.list[eventName];
-                    if ((_b = eventOptions === null || eventOptions === void 0 ? void 0 : eventOptions.options) === null || _b === void 0 ? void 0 : _b.stream) {
+                    const isStream = (_b = eventOptions === null || eventOptions === void 0 ? void 0 : eventOptions.options) === null || _b === void 0 ? void 0 : _b.stream;
+                    if (isStream) {
                         const prefix = (_c = options.events) === null || _c === void 0 ? void 0 : _c.streamOptions.prefix;
                         if (!prefix) {
                             throw new Error(`Stream prefix not set for event ${String(eventName)} marked as stream`);
@@ -61,14 +62,32 @@ class Service extends Root_1.Root {
                         settings = { headers: (0, nats_1.headers)() };
                         settings.headers.append(this.UNIQ_ID_HEADER, uniqId);
                     }
-                    if (rollupId) {
+                    if (rollupId && isStream) {
                         settings = settings !== null && settings !== void 0 ? settings : { headers: (0, nats_1.headers)() };
                         settings.headers.append(this.ROLLUP_HEADER, this.ROLLUP_STRATEGY);
                         subject.push(rollupId);
                     }
-                    else {
+                    else if (rollupId && !isStream) {
+                        this.logger.warn(`${String(eventName)}. Rollup is available only for streams`);
+                    }
+                    else if (isStream) {
                         subject.push(this.BASE_EVENT_SUFFIX);
                     }
+                    if (external) {
+                        const baggage = this.getBaggageFromExternalHeader(external);
+                        const tracer = api_1.trace.getTracer('');
+                        const context = this.getContext(this.isBaggageContainTrace(baggage) ? baggage : undefined);
+                        const span = tracer.startSpan(String(eventName), { kind: api_1.SpanKind.PRODUCER }, context);
+                        const eventSpanContext = span.spanContext();
+                        const eventHeader = this.convertBaggaggeToExternalHeader(eventSpanContext);
+                        if (!settings) {
+                            settings = { headers: (0, nats_1.headers)() };
+                        }
+                        for (const [key, value] of Object.entries(eventHeader)) {
+                            settings.headers.append(key, `${value}`);
+                        }
+                        span.end();
+                    }
                     this.broker.publish(subject.join('.'), this.buildMessage(params), settings);
                 });
                 return result;
@@ -97,41 +116,42 @@ class Service extends Root_1.Root {
         provider.addSpanProcessor(new sdk_trace_base_1.SimpleSpanProcessor(exporter));
         provider.register();
     }
-    finishSpan(span, error) {
+    finishSpan(span, error, tag) {
         if (error) {
             span.setAttribute('error', true);
             span.setAttribute('error.kind', error.message);
         }
+        this.applyTag(span, tag);
         span.end();
     }
     /**
      * Wrapper for async methods. Create span
      */
-    perform(func, funcContext, arg, tracer, context) {
+    perform(func, funcContext, arg, tracer, context, tag) {
         const span = tracer.startSpan(func.name, undefined, context);
         try {
             const result = func.apply(funcContext, arg);
             if (result.then) {
                 return result.then((result) => {
-                    this.finishSpan(span);
+                    this.finishSpan(span, undefined, tag);
                     return result;
                 }, (error) => {
-                    this.finishSpan(span, error);
+                    this.finishSpan(span, error, tag);
                     throw error;
                 });
             }
-            this.finishSpan(span);
+            this.finishSpan(span, undefined, tag);
             return result;
         }
         catch (error) {
-            this.finishSpan(span, error);
+            this.finishSpan(span, error, tag);
             throw error;
         }
     }
     /**
      * Build trap for object with async methods
      */
-    getTrap(instance, tracer, baggage) {
+    getTrap(instance, tracer, baggage, tag) {
         const perform = this.perform.bind(this);
         const context = this.getContext(baggage);
         return {
@@ -139,7 +159,7 @@ class Service extends Root_1.Root {
                 const method = Reflect.get(target, propKey, receiver);
                 if (typeof method === 'function') {
                     return function (...args) {
-                        return perform(method, instance, args, tracer, context);
+                        return perform(method, instance, args, tracer, context, tag);
                     };
                 }
                 else {
@@ -154,11 +174,13 @@ class Service extends Root_1.Root {
     createObjectWithDependencies(method, tracer, baggage) {
         const services = _1.ServiceContainer.get(method.settings.action) || new Map();
         const instances = _1.InstanceContainer.get(method.settings.action) || new Map();
+        const tags = new Map();
         const dependences = { [_1.ConstructorDependencyKey]: [] };
         const dependencyStorage = Reflect.getMetadata(_1.dependencyStorageMetaKey, method);
         if (dependencyStorage && dependencyStorage.size) {
             // for constructor
             dependencyStorage.forEach((dependencyKey, propertyName) => {
+                var _a;
                 if (Array.isArray(dependencyKey)) {
                     if (propertyName === _1.ConstructorDependencyKey) {
                         dependencyKey.forEach((item, index) => {
@@ -184,6 +206,9 @@ class Service extends Root_1.Root {
                 }
                 if (dependency.type === _1.DependencyType.ADAPTER) {
                     instances.set(propertyName, _1.container.getInstance(dependencyKey));
+                    if ((_a = dependency.options) === null || _a === void 0 ? void 0 : _a.tag) {
+                        tags.set(propertyName, dependency.options.tag);
+                    }
                 }
                 if (dependency.type === _1.DependencyType.CONSTANT) {
                     dependences[propertyName] = dependency.value;
@@ -197,7 +222,7 @@ class Service extends Root_1.Root {
         }
         if (instances.size) {
             instances.forEach((instance, key) => {
-                const trap = this.getTrap(instance, tracer, baggage);
+                const trap = this.getTrap(instance, tracer, baggage, tags.get(key));
                 dependences[key] = new Proxy(instance, trap);
             });
         }
@@ -231,7 +256,7 @@ class Service extends Root_1.Root {
      * If there is no baggage. For example, in HTTP Gateway
      */
     getRootBaggage(subject, headers, ownTimeout) {
-        const baggage = headers ? this.getBaggageFromHTTPHeader(headers) : undefined;
+        const baggage = headers ? this.getBaggageFromExternalHeader(headers) : undefined;
         const tracer = api_1.trace.getTracer('');
         const context = this.getContext(this.isBaggageContainTrace(baggage) ? baggage : undefined);
         const span = tracer.startSpan(subject, undefined, context);
@@ -328,7 +353,7 @@ class Service extends Root_1.Root {
                 if (other.length || wrongServiceName || !Method) {
                     throw new Error('Wrong url or service name or action');
                 }
-                const baggage = this.getBaggageFromHTTPHeader(request.headers);
+                const baggage = this.getBaggageFromExternalHeader(request.headers);
                 if ((_b = (_a = Method.settings.options) === null || _a === void 0 ? void 0 : _a.useStream) === null || _b === void 0 ? void 0 : _b.request) {
                     const result = await this.handled(request, Method, baggage);
                     if (Method.settings.options.useStream.response && result.payload instanceof node_stream_1.Readable) {
@@ -373,11 +398,12 @@ class Service extends Root_1.Root {
             metadata: baggage,
             outputFormatter: this.options.loggerOutputFormatter,
         });
+        const nextBaggage = this.getNextBaggage(span, baggage);
         try {
-            const requestedDependencies = this.createObjectWithDependencies(Method, tracer, this.getNextBaggage(span, baggage));
+            const requestedDependencies = this.createObjectWithDependencies(Method, tracer, nextBaggage);
             const context = this.createMethodContext(Method, requestedDependencies);
             context['logger'] = logger;
-            context['emitter'] = this.emitter;
+            context['emitter'] = this.getWrappedEmitter(nextBaggage);
             const response = await context.handler.call(context, payload);
             const result = {
                 payload: response,
@@ -393,6 +419,28 @@ class Service extends Root_1.Root {
             return this.buildErrorMessage(error);
         }
     }
+    /**
+     * Wrap emitter for luggage baggagge
+     */
+    getWrappedEmitter(baggage) {
+        if (!baggage) {
+            return this.emitter;
+        }
+        const externalBaggage = this.convertBaggaggeToExternalHeader(baggage);
+        return new Proxy(this.emitter, {
+            get(target, propKey, receiver) {
+                const event = Reflect.get(target, propKey, receiver);
+                if (typeof event === 'function') {
+                    return (params, uniqId, rollupId, userExternalBaggage) => {
+                        return event(params, uniqId, rollupId, userExternalBaggage !== null && userExternalBaggage !== void 0 ? userExternalBaggage : externalBaggage);
+                    };
+                }
+                else {
+                    return event;
+                }
+            },
+        });
+    }
     /**
      * Make error object if error instance of Error object for logger
      */
@@ -607,7 +655,7 @@ class Service extends Root_1.Root {
             port: this.httpPort,
         };
     }
-    getBaggageFromHTTPHeader(headers) {
+    getBaggageFromExternalHeader(headers) {
         const expired = headers['nsc-expired'] ? +headers['nsc-expired'] : undefined;
         const traceId = headers['nsc-trace-id'];
         const spanId = headers['nsc-span-id'];

package/dist/interfaces.js

@@ -1,10 +1,16 @@
 "use strict";
 // COMMON
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DependencyType = void 0;
+exports.TagKey = exports.DependencyType = void 0;
 exports.DependencyType = {
     SERVICE: 'service',
     ADAPTER: 'adapter',
     CONSTANT: 'constant', // Just an object
 };
+exports.TagKey = {
+    LOCATION: 'location',
+    TYPE: 'type',
+    NAME: 'name',
+    TARGET: 'target',
+};
 //# sourceMappingURL=interfaces.js.map

package/dist/types/Client.d.ts

@@ -26,7 +26,7 @@ export declare class Client<E extends Emitter = Emitter> extends Root {
     private isStream;
     private makeBrokerRequest;
     private makeHttpRequest;
-    private convertBaggaggeToExternalHeader;
     private isJsMessage;
+    private getBaggageFromNATSHeader;
 }
 export {};

package/dist/types/Container.d.ts

@@ -1,12 +1,14 @@
-import { ClientService, DependencyType, InitializableService } from '.';
+import { ClientService, DependencyType, InitializableService, Tag } from '.';
 type Constant = Record<string, any>;
 type Service<R extends Constant = Constant> = ClientService<R>;
 export type Adapter<R extends Constant = Constant> = new (...args: any[]) => R;
 export type Singlton = {
     singlton: true;
+    tag?: Tag;
 };
 export type NeedInit = {
     init: true;
+    tag?: Tag;
 };
 export type AdapterOptions = Singlton | NeedInit;
 type Dependency = Service | Adapter | Constant;

package/dist/types/Meter.d.ts

@@ -0,0 +1,11 @@
+import { Baggage, EventMeter, Tag } from './interfaces';
+import { Root } from './Root';
+export declare class Meter extends Root implements EventMeter {
+    private name;
+    private baggage?;
+    private span?;
+    constructor(name: string, baggage?: Baggage | undefined);
+    start(): void;
+    end(error?: Error): void;
+    measure<T extends (...args: any[]) => any>(func: T, arg: Parameters<T>, context: unknown, tag?: Tag): ReturnType<T>;
+}

package/dist/types/Root.d.ts

@@ -1,7 +1,7 @@
 import { Logs } from '@lad-tech/toolbelt';
 import * as opentelemetry from '@opentelemetry/api';
 import type { NatsConnection } from 'nats';
-import type { Baggage } from './interfaces';
+import { type Baggage, type ExternalBaggage, type Tag } from './interfaces';
 import { Broker } from './Union';
 export declare class Root {
     protected readonly SERVICE_SUBJECT_FOR_GET_HTTP_SETTINGS = "get_http_settings";
@@ -24,4 +24,6 @@ export declare class Root {
             code: number | undefined;
         };
     };
+    protected convertBaggaggeToExternalHeader(baggage?: Partial<Baggage>): ExternalBaggage;
+    protected applyTag(span: opentelemetry.Span, tag?: Tag): void;
 }

package/dist/types/Service.d.ts

@@ -88,6 +88,10 @@ export declare class Service<E extends Emitter = Emitter> extends Root {
      * Run business logic for request
      */
     private handled;
+    /**
+     * Wrap emitter for luggage baggagge
+     */
+    private getWrappedEmitter;
     /**
      * Make error object if error instance of Error object for logger
      */
@@ -132,5 +136,5 @@ export declare class Service<E extends Emitter = Emitter> extends Root {
     private upHTTPServer;
     private getMyIpV4;
     private getHttpSettings;
-    private getBaggageFromHTTPHeader;
+    private getBaggageFromExternalHeader;
 }

package/dist/types/StreamOptions/BufferToJsonTransform.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 /// <reference types="node" />
+/// <reference types="node" />
 import { Logs } from '@lad-tech/toolbelt';
 import { Transform, TransformCallback, TransformOptions } from 'stream';
 export declare class BufferToJsonTransform<T = any> extends Transform {

package/dist/types/Union/Subscription.d.ts

@@ -2,7 +2,7 @@
 import { Closed, ConsumerInfoable, Destroyable, Msg, NatsError, Subscription } from 'nats';
 import { PassThrough } from 'node:stream';
 export declare class UnionSubscription extends PassThrough implements Subscription, Destroyable, Closed, ConsumerInfoable {
-    closed: Promise<void>;
+    closed: any;
     unsubscribe(max?: number): void;
     drain(): Promise<void>;
     isDraining(): boolean;

package/dist/types/interfaces.d.ts

@@ -85,10 +85,12 @@ export interface StreamManagerParam {
 }
 export interface EmitterEvent<D extends Record<string, any>> {
     data: D;
+    meter: EventMeter;
 }
 export interface EmitterStreamEvent<D extends Record<string, any>> extends EmitterEvent<D> {
     ack: () => void;
     nak: (millis: number) => void;
+    meter: EventMeter;
 }
 export interface StreamAction {
     action: string;
@@ -157,3 +159,23 @@ export declare const DependencyType: {
     readonly ADAPTER: "adapter";
     readonly CONSTANT: "constant";
 };
+export type TagKey = typeof TagKey[keyof typeof TagKey];
+export declare const TagKey: {
+    readonly LOCATION: "location";
+    readonly TYPE: "type";
+    readonly NAME: "name";
+    readonly TARGET: "target";
+};
+export type LocationTagValue = 'internal' | 'external';
+export type TypeTagValue = 'dbms' | 'api';
+export type Tag = {
+    [TagKey.LOCATION]: LocationTagValue;
+    [TagKey.TYPE]: TypeTagValue;
+    [TagKey.NAME]: string;
+    [TagKey.TARGET]?: string;
+};
+export interface EventMeter {
+    start(): void;
+    end(): void;
+    measure<T extends (...args: any[]) => any>(func: T, arg: Parameters<T>, context: any, tag?: Tag): ReturnType<T>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lad-tech/nsc-toolkit",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Toolkit for create microservices around NATS",
   "main": "dist/index.js",
   "types": "./dist/types/index.d.ts",
@@ -17,7 +17,7 @@
     "@semantic-release/changelog": "^6.0.2",
     "@semantic-release/npm": "^9.0.1",
     "@types/jest": "^27.5.2",
-    "@types/node": "^17.0.42",
+    "@types/node": "^22.13.13",
     "eslint": "^7.32.0",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-prettier": "^8.5.0",
@@ -41,7 +41,7 @@
     "@opentelemetry/sdk-trace-base": "^1.3.1",
     "@opentelemetry/semantic-conventions": "^1.3.1",
     "ajv": "^8.11.0",
-    "nats": "^2.28.2",
+    "nats": "^2.29.3",
     "reflect-metadata": "^0.1.13"
   },
   "peerDependencies": {