@lensmcp/nest-instrumentation 1.0.0

package/lib/provider-tracker.js

@@ -0,0 +1,315 @@
+import { __decorate, __metadata } from "tslib";
+import { Injectable } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { fingerprint, ulid } from '@lensmcp/core';
+import { trackContainer } from '@lensmcp/memory-tracker';
+import { activeOptions, currentGeneration } from './state.js';
+import { readTraceProvider } from './trace-provider.js';
+import { traceWrap, isTraced, isIgnored } from './instrument.js';
+// Nest lifecycle hooks + base Object methods we never auto-wrap.
+const SKIP_METHODS = new Set([
+    'constructor',
+    'onModuleInit',
+    'onApplicationBootstrap',
+    'onModuleDestroy',
+    'beforeApplicationShutdown',
+    'onApplicationShutdown',
+]);
+// Provider "class" names that are really built-ins (value/factory providers).
+const BUILTIN_CLASS = /^(_|Object|String|Number|Array|Promise|Function|RegExp|Map|Set)$/;
+// Marks a shared prototype already auto-instrumented, so request-scoped /
+// transient providers (instantiated per request) are wrapped exactly once.
+const LENSMCP_PROTO_WRAPPED = Symbol.for('@lensmcp/nest-instrumentation/proto-wrapped');
+/**
+ * On application bootstrap, walks the Nest container and emits one
+ * `singleton-instance` event per provider so the `apps/nest` reducer
+ * can materialise `nest://providers`. On module destroy (HMR / shutdown)
+ * marks each instance as `disposed`.
+ *
+ * `generation` is the LensMCP module-instance counter (incremented each
+ * time `LensmcpModule.forRoot` is constructed), which mirrors a hot
+ * reload. Lets the agent ask "is the new gen serving requests, or did
+ * an old one stick around?".
+ */
+let LensmcpProviderTracker = class LensmcpProviderTracker {
+    constructor(moduleRef) {
+        this.moduleRef = moduleRef;
+        this.active = new Map(); // logicalId → instanceId
+    }
+    onApplicationBootstrap() {
+        const opts = activeOptions();
+        const gen = currentGeneration();
+        // Nest's ModuleRef doesn't expose the full provider list publicly.
+        // Phase 3 uses a small reflection trick: ModuleRef has an internal
+        // `container` accessor used by interceptors. We treat it as opaque
+        // and use the public `get` for known classes — the deeper enumeration
+        // lands in Phase 3.5 once we ship a `@TraceProvider` decorator.
+        const internalContainer = this.moduleRef.container;
+        if (!internalContainer?.getModules)
+            return;
+        for (const [, module] of internalContainer.getModules()) {
+            // Controllers live in their OWN map (module.controllers), not in
+            // providers — without this loop the trace jumps from server-request
+            // straight to the service, hiding the controller hop the request
+            // actually goes through.
+            const controllers = module?.controllers;
+            if (controllers && typeof controllers.forEach === 'function') {
+                controllers.forEach((wrapper) => {
+                    const instance = wrapper?.instance;
+                    if (!instance || typeof instance !== 'object')
+                        return;
+                    const ctor = instance.constructor;
+                    const cls = ctor?.name;
+                    if (!cls || BUILTIN_CLASS.test(cls))
+                        return;
+                    const logicalId = `nest:controller:${cls}`;
+                    const instanceId = `${cls}#gen${gen}#${shortHash(`${cls}:${gen}`)}`;
+                    this.active.set(logicalId, instanceId);
+                    opts.emit(makeProviderEvent({
+                        logicalId,
+                        instanceId,
+                        generation: gen,
+                        module: module?.metatype?.name,
+                        scope: scopeLabel(wrapper?.scope),
+                        lifecycle: 'active',
+                    }));
+                    if (opts.trace.autoInstrumentMethods && ctor) {
+                        autoInstrumentProviderMethods(instance, ctor, cls);
+                    }
+                });
+            }
+            const providers = module?.providers;
+            if (!providers || typeof providers.forEach !== 'function')
+                continue;
+            providers.forEach((wrapper) => {
+                const instance = wrapper?.instance;
+                // Request-scoped / transient providers get a fresh instance per
+                // request/injection. Nest does create a *static-context* instance at
+                // bootstrap, but wrapping that one instance wouldn't cover the
+                // per-request ones — so for any non-singleton scope we wrap the
+                // shared prototype (traceWrap keeps `this`, so every per-request
+                // instance is traced). Gate on scope, not instance presence.
+                if (scopeLabel(wrapper?.scope) !== 'SINGLETON') {
+                    this.trackScopedProvider(wrapper, module, gen, opts);
+                    return;
+                }
+                if (!instance || typeof instance !== 'object')
+                    return;
+                const ctor = instance.constructor;
+                const cls = ctor?.name;
+                if (!cls || BUILTIN_CLASS.test(cls))
+                    return;
+                const logicalId = `nest:provider:${cls}`;
+                const instanceId = `${cls}#gen${gen}#${shortHash(`${cls}:${gen}`)}`;
+                this.active.set(logicalId, instanceId);
+                opts.emit(makeProviderEvent({
+                    logicalId,
+                    instanceId,
+                    generation: gen,
+                    module: module?.metatype?.name,
+                    scope: scopeLabel(wrapper?.scope),
+                    lifecycle: 'active',
+                }));
+                // Phase 7: memory container tracking. Wrap Map/Set/Array fields
+                // on tagged providers (or all providers when scope === 'all').
+                if (opts.memory.mode !== 'off') {
+                    const tag = readTraceProvider(ctor);
+                    const shouldTrack = opts.memory.scope === 'all' || (tag?.memory ?? false);
+                    if (shouldTrack) {
+                        trackProviderContainers(instance, instanceId);
+                    }
+                }
+                // Phase 8: zero-config — auto-wrap this provider's methods with
+                // span + db-call tracing (no @TraceMethod needed). Skips methods
+                // already wrapped (@TraceMethod) or marked @LensmcpIgnore.
+                if (opts.trace.autoInstrumentMethods && ctor) {
+                    autoInstrumentProviderMethods(instance, ctor, cls);
+                }
+            });
+        }
+    }
+    onModuleDestroy() {
+        const opts = activeOptions();
+        const gen = currentGeneration();
+        for (const [logicalId, instanceId] of this.active) {
+            opts.emit(makeProviderEvent({
+                logicalId,
+                instanceId,
+                generation: gen,
+                lifecycle: 'disposed',
+            }));
+        }
+    }
+    /**
+     * Handle a provider with no bootstrap instance. Request-scoped and
+     * transient providers fall here; value/factory providers (no class
+     * `metatype`) are ignored. Wraps the class's shared prototype once and
+     * emits a provider event with the real scope.
+     */
+    trackScopedProvider(wrapper, module, gen, opts) {
+        // Prefer the class metatype; fall back to the static-context instance's
+        // constructor when the wrapper doesn't expose a metatype.
+        let ctorUnknown;
+        if (typeof wrapper?.metatype === 'function') {
+            ctorUnknown = wrapper.metatype;
+        }
+        else if (wrapper?.instance && typeof wrapper.instance === 'object') {
+            ctorUnknown = wrapper.instance.constructor;
+        }
+        if (typeof ctorUnknown !== 'function')
+            return; // value/factory provider
+        const ctor = ctorUnknown;
+        if (!ctor.prototype)
+            return;
+        const cls = ctor.name;
+        if (!cls || BUILTIN_CLASS.test(cls))
+            return;
+        const scope = scopeLabel(wrapper?.scope);
+        const logicalId = `nest:provider:${cls}`;
+        const instanceId = `${cls}#gen${gen}#${scope.toLowerCase()}`;
+        if (!this.active.has(logicalId))
+            this.active.set(logicalId, instanceId);
+        opts.emit(makeProviderEvent({
+            logicalId,
+            instanceId,
+            generation: gen,
+            module: module?.metatype?.name,
+            scope,
+            lifecycle: 'active',
+        }));
+        if (opts.trace.autoInstrumentMethods) {
+            autoInstrumentPrototypeMethods(ctor, cls);
+        }
+    }
+};
+LensmcpProviderTracker = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [ModuleRef])
+], LensmcpProviderTracker);
+export { LensmcpProviderTracker };
+/** Normalise Nest's scope (enum number or string) to a stable label. */
+function scopeLabel(scope) {
+    if (scope === 1 || scope === 'TRANSIENT')
+        return 'TRANSIENT';
+    if (scope === 2 || scope === 'REQUEST')
+        return 'REQUEST';
+    return 'SINGLETON';
+}
+function makeProviderEvent(p) {
+    const opts = activeOptions();
+    return {
+        id: ulid(),
+        sessionId: opts.sessionId,
+        timestamp: Date.now(),
+        source: 'nestjs',
+        category: 'backend',
+        severity: 'info',
+        context: { sessionId: opts.sessionId },
+        fingerprint: fingerprint({ kind: 'nest-provider', identity: p.logicalId }),
+        title: `Nest provider ${p.logicalId} ${p.lifecycle}`,
+        raw: {
+            kind: 'singleton-instance',
+            provider: { ...p, createdAt: Date.now() },
+        },
+    };
+}
+function shortHash(input) {
+    let h = 5381;
+    for (let i = 0; i < input.length; i++)
+        h = ((h << 5) + h + input.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(16).slice(0, 6);
+}
+/**
+ * Scan an instance's own enumerable fields for Map/Set/Array containers
+ * and wrap them so mutations emit memory-mutation events.
+ */
+function trackProviderContainers(instance, ownerInstanceId) {
+    for (const fieldName of Object.keys(instance)) {
+        const value = instance[fieldName];
+        if (value instanceof Map || value instanceof Set || Array.isArray(value)) {
+            trackContainer({ ownerInstanceId, fieldName, container: value });
+        }
+    }
+}
+/**
+ * Replace each of a provider's own prototype methods with a traced
+ * wrapper, in place on the instance. Wraps on the instance (not the
+ * shared prototype) so two providers of the same class don't collide and
+ * `this` stays bound. Skips lifecycle hooks, getters/setters,
+ * non-functions, already-traced (@TraceMethod), and @LensmcpIgnore.
+ */
+function autoInstrumentProviderMethods(instance, ctor, cls) {
+    if (isIgnored(ctor))
+        return;
+    const proto = Object.getPrototypeOf(instance);
+    if (!proto || proto === Object.prototype)
+        return;
+    for (const name of Object.getOwnPropertyNames(proto)) {
+        if (SKIP_METHODS.has(name))
+            continue;
+        const desc = Object.getOwnPropertyDescriptor(proto, name);
+        if (!desc || typeof desc.value !== 'function' || desc.get || desc.set)
+            continue;
+        const original = desc.value;
+        if (isTraced(original) || isIgnored(original))
+            continue;
+        const wrapped = traceWrap(original, `${cls}.${name}`);
+        try {
+            // Define on the instance so we don't mutate the shared prototype.
+            Object.defineProperty(instance, name, {
+                value: wrapped,
+                writable: true,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        catch {
+            /* read-only / exotic — skip */
+        }
+    }
+}
+/**
+ * Auto-wrap the methods on a class's shared prototype, in place. Used for
+ * request-scoped / transient providers, which have no instance at bootstrap
+ * — every per-request instance resolves these methods from the prototype,
+ * and `traceWrap` preserves `this`, so each call is traced correctly.
+ * Marked once on the prototype so HMR generations don't re-wrap.
+ */
+function autoInstrumentPrototypeMethods(metatype, cls) {
+    if (isIgnored(metatype))
+        return;
+    const proto = metatype.prototype;
+    if (!proto || proto === Object.prototype)
+        return;
+    const marker = proto;
+    if (marker[LENSMCP_PROTO_WRAPPED])
+        return;
+    const wrappedNames = [];
+    for (const name of Object.getOwnPropertyNames(proto)) {
+        if (SKIP_METHODS.has(name))
+            continue;
+        const desc = Object.getOwnPropertyDescriptor(proto, name);
+        if (!desc || typeof desc.value !== 'function' || desc.get || desc.set)
+            continue;
+        const original = desc.value;
+        if (isTraced(original) || isIgnored(original))
+            continue;
+        const wrapped = traceWrap(original, `${cls}.${name}`);
+        try {
+            Object.defineProperty(proto, name, {
+                value: wrapped,
+                writable: true,
+                enumerable: false,
+                configurable: true,
+            });
+            wrappedNames.push(name);
+        }
+        catch {
+            /* read-only / exotic — skip */
+        }
+    }
+    marker[LENSMCP_PROTO_WRAPPED] = true;
+    if (process.env['LENSMCP_DEBUG']) {
+        console.error(`[lensmcp] proto-wrapped ${cls}: [${wrappedNames.join(', ')}]`);
+    }
+}

package/lib/state.d.ts

@@ -0,0 +1,5 @@
+import type { LensmcpModuleOptions, ResolvedOptions } from './types.js';
+export declare function setActiveOptions(opts: LensmcpModuleOptions): ResolvedOptions;
+export declare function activeOptions(): ResolvedOptions;
+export declare function currentGeneration(): number;
+//# sourceMappingURL=state.d.ts.map

package/lib/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/lib/state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAUxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,eAAe,CAuB5E;AAED,wBAAgB,aAAa,IAAI,eAAe,CAQ/C;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/lib/state.js

@@ -0,0 +1,43 @@
+import { ulid } from '@lensmcp/core';
+import { defaultEventSink } from './event-sink.js';
+/**
+ * Per-process singleton holding the resolved instrumentation options.
+ * Tied to `LensmcpModule.forRoot()` — Nest constructs the module once
+ * per app boot, so `setActiveOptions` runs exactly once per generation.
+ */
+let active;
+let generation = 0;
+export function setActiveOptions(opts) {
+    const resolved = {
+        projectName: opts.projectName,
+        sessionId: opts.sessionId ?? process.env['LENSMCP_SESSION_ID'] ?? ulid(),
+        emit: opts.emit ?? defaultEventSink(),
+        trace: {
+            requests: opts.trace?.requests ?? true,
+            guards: opts.trace?.guards ?? true,
+            controllers: opts.trace?.controllers ?? true,
+            services: opts.trace?.services ?? true,
+            db: opts.trace?.db ?? false,
+            redis: opts.trace?.redis ?? false,
+            queues: opts.trace?.queues ?? false,
+            autoInstrumentMethods: opts.trace?.autoInstrumentMethods ?? false,
+        },
+        memory: {
+            mode: opts.memory?.mode ?? 'off',
+            scope: opts.memory?.scope ?? 'tagged',
+        },
+    };
+    active = resolved;
+    generation += 1;
+    return resolved;
+}
+export function activeOptions() {
+    if (!active) {
+        throw new Error('@lensmcp/nest-instrumentation: LensmcpModule.forRoot(...) has not been registered. ' +
+            'Did you forget to add it to your AppModule?');
+    }
+    return active;
+}
+export function currentGeneration() {
+    return generation;
+}

package/lib/trace-interceptor.d.ts

@@ -0,0 +1,16 @@
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+/**
+ * Wraps every Nest HTTP request:
+ *   1. Reads `x-request-id`, `x-lensmcp-flow-id`, `x-lensmcp-origin-node-id`,
+ *      `traceparent` headers from the incoming request.
+ *   2. Runs the rest of the request inside a new
+ *      `LensmcpRequestContext` so any `@TraceMethod`-decorated service
+ *      call, DB query, or queue job downstream inherits the same flow.
+ *   3. Emits a `server-request` event on completion with method, route,
+ *      status, and duration.
+ */
+export declare class TraceInterceptor implements NestInterceptor {
+    intercept(execCtx: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//# sourceMappingURL=trace-interceptor.d.ts.map

package/lib/trace-interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-interceptor.d.ts","sourceRoot":"","sources":["../../src/lib/trace-interceptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC3G,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAQlC;;;;;;;;;GASG;AACH,qBACa,gBAAiB,YAAW,eAAe;IACtD,SAAS,CAAC,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CAAC,OAAO,CAAC;CA6E7E"}

package/lib/trace-interceptor.js

@@ -0,0 +1,194 @@
+import { __decorate } from "tslib";
+import { Injectable } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { catchError, tap } from 'rxjs/operators';
+import { fingerprint, ulid } from '@lensmcp/core';
+import { activeMemoryOptions, onFlowStart, onFlowSettled } from '@lensmcp/memory-tracker';
+import { LENSMCP_CONTEXT_STORAGE } from './context.js';
+import { activeOptions } from './state.js';
+/**
+ * Wraps every Nest HTTP request:
+ *   1. Reads `x-request-id`, `x-lensmcp-flow-id`, `x-lensmcp-origin-node-id`,
+ *      `traceparent` headers from the incoming request.
+ *   2. Runs the rest of the request inside a new
+ *      `LensmcpRequestContext` so any `@TraceMethod`-decorated service
+ *      call, DB query, or queue job downstream inherits the same flow.
+ *   3. Emits a `server-request` event on completion with method, route,
+ *      status, and duration.
+ */
+let TraceInterceptor = class TraceInterceptor {
+    intercept(execCtx, next) {
+        const opts = activeOptions();
+        if (!opts.trace.requests)
+            return next.handle();
+        const http = execCtx.switchToHttp();
+        const req = http.getRequest();
+        const res = http.getResponse();
+        const requestId = stringHeader(req.headers?.['x-request-id']) ?? ulid();
+        const ctx = {
+            sessionId: opts.sessionId,
+            requestId,
+            flowId: stringHeader(req.headers?.['x-lensmcp-flow-id']),
+            originNodeId: stringHeader(req.headers?.['x-lensmcp-origin-node-id']),
+            traceparent: stringHeader(req.headers?.['traceparent']),
+            dbCallCount: 0,
+        };
+        const method = (req.method ?? 'GET').toUpperCase();
+        const route = req.route?.path ?? req.url ?? '<unknown>';
+        // The controller hop, by name. Wrapping controller instances at bootstrap
+        // is too late — Nest's router captured the raw method reference when the
+        // routes were mapped — so the interceptor (which brackets the handler)
+        // is the seam that can see and time the controller call.
+        const controllerCls = execCtx.getClass?.()?.name;
+        const handlerName = execCtx.getHandler?.()?.name;
+        const startedAt = Date.now();
+        // Phase 7.5: bracket the request as a memory "flow" so the
+        // suspect-leak detector can compare tracked-container sizes at
+        // request start vs after it settles. Keyed by requestId.
+        const memoryOn = opts.memory.mode !== 'off';
+        if (memoryOn)
+            onFlowStart(requestId);
+        const settleAndCheck = () => {
+            if (!memoryOn)
+                return;
+            const settleMs = activeMemoryOptions()?.settleMs ?? 1000;
+            const t = setTimeout(() => onFlowSettled(requestId), settleMs);
+            t.unref?.();
+        };
+        return new Observable((subscriber) => {
+            LENSMCP_CONTEXT_STORAGE.run(ctx, () => {
+                next
+                    .handle()
+                    .pipe(tap({
+                    next: (v) => subscriber.next(v),
+                    complete: () => {
+                        emitRequest(opts.projectName, ctx, method, route, res.statusCode ?? 200, startedAt);
+                        emitControllerSpan(ctx, controllerCls, handlerName, startedAt, 'ok');
+                        settleAndCheck();
+                        subscriber.complete();
+                    },
+                }), catchError((err) => {
+                    // The exception filter hasn't written the response yet — Nest's
+                    // default (201 for POST) is still on res.statusCode. The thrown
+                    // error knows the real status: HttpException via getStatus(),
+                    // domain errors via the `status`/`statusCode` field convention.
+                    const e = err;
+                    const errStatus = typeof e?.getStatus === 'function' ? e.getStatus()
+                        : typeof e?.status === 'number' && e.status >= 100 ? e.status
+                            : typeof e?.statusCode === 'number' && e.statusCode >= 100 ? e.statusCode
+                                : res.statusCode && res.statusCode >= 400 ? res.statusCode
+                                    : 500;
+                    emitRequest(opts.projectName, ctx, method, route, errStatus, startedAt, err);
+                    emitControllerSpan(ctx, controllerCls, handlerName, startedAt, 'error');
+                    settleAndCheck();
+                    subscriber.error(err);
+                    return new Observable();
+                }))
+                    .subscribe();
+            });
+        });
+    }
+};
+TraceInterceptor = __decorate([
+    Injectable()
+], TraceInterceptor);
+export { TraceInterceptor };
+function stringHeader(v) {
+    if (typeof v === 'string')
+        return v;
+    if (Array.isArray(v) && typeof v[0] === 'string')
+        return v[0];
+    return undefined;
+}
+/** The controller hop as a span — `CompanyController.create (12ms)`. */
+function emitControllerSpan(ctx, controllerCls, handlerName, startedAt, status) {
+    if (!controllerCls || !handlerName)
+        return;
+    const opts = activeOptions();
+    const durationMs = Date.now() - startedAt;
+    const name = `${controllerCls}.${handlerName}`;
+    opts.emit({
+        id: ulid(),
+        sessionId: ctx.sessionId,
+        timestamp: Date.now(),
+        source: 'nestjs',
+        category: 'backend',
+        severity: status === 'error' ? 'error' : 'info',
+        context: { sessionId: ctx.sessionId, flowId: ctx.flowId, requestId: ctx.requestId },
+        fingerprint: fingerprint({ kind: 'method-call', identity: name }),
+        title: `${name} (${durationMs}ms)${status === 'error' ? ' ✗' : ''}`,
+        raw: {
+            kind: 'span',
+            span: {
+                name,
+                role: 'controller',
+                flowId: ctx.flowId,
+                requestId: ctx.requestId,
+                startTime: startedAt,
+                endTime: Date.now(),
+                durationMs,
+                status,
+            },
+        },
+    });
+}
+function emitRequest(projectName, ctx, method, route, status, startedAt, err) {
+    const opts = activeOptions();
+    const durationMs = Date.now() - startedAt;
+    const isError = status >= 500 || err !== undefined;
+    const event = {
+        id: ulid(),
+        sessionId: ctx.sessionId,
+        timestamp: Date.now(),
+        source: 'nestjs',
+        category: 'backend',
+        severity: isError ? 'error' : 'info',
+        context: {
+            sessionId: ctx.sessionId,
+            flowId: ctx.flowId,
+            requestId: ctx.requestId,
+            originNodeId: ctx.originNodeId,
+            traceparent: ctx.traceparent,
+        },
+        fingerprint: fingerprint({
+            kind: 'server-request',
+            identity: `${method}:${route}:${Math.floor(status / 100)}xx`,
+        }),
+        title: `${method} ${route} → ${status} (${durationMs}ms)`,
+        message: err instanceof Error ? err.message : undefined,
+        raw: {
+            kind: 'server-request',
+            request: {
+                method,
+                route,
+                status,
+                durationMs,
+                startedAt,
+                endedAt: Date.now(),
+                flowId: ctx.flowId,
+                requestId: ctx.requestId,
+            },
+        },
+    };
+    // Also emit a span-shaped event so trace:// picks it up.
+    const spanEvent = {
+        ...event,
+        id: ulid(),
+        raw: {
+            kind: 'span',
+            span: {
+                name: `nest.request ${method} ${route}`,
+                traceId: ctx.traceparent,
+                flowId: ctx.flowId,
+                requestId: ctx.requestId,
+                startTime: startedAt,
+                endTime: Date.now(),
+                durationMs,
+                status: isError ? 'error' : 'ok',
+            },
+        },
+    };
+    void projectName; // reserved for per-project namespacing
+    opts.emit(event);
+    opts.emit(spanEvent);
+}

package/lib/trace-method.d.ts

@@ -0,0 +1,28 @@
+export interface TraceMethodOptions {
+    /** Override the span name (default `Class.method`). */
+    name?: string;
+    /**
+     * Mark this method as a DB query. Each call emits a `db-query` event
+     * (feeding N+1 detection) and bumps the request's `dbCallCount` so an
+     * enclosing method is flagged db-in-loop.
+     */
+    db?: boolean;
+}
+/**
+ * `@TraceMethod()` — decorate a service/controller method so every
+ * invocation emits a `span` event with method name + duration. Inherits
+ * the request's `flowId`/`requestId` from the `AsyncLocalStorage`
+ * context set by `TraceInterceptor`.
+ *
+ *   @Injectable()
+ *   class AuthService {
+ *     @TraceMethod()                 login(dto) { … }
+ *     @TraceMethod({ db: true })     findUser(id) { … }
+ *   }
+ *
+ * Wraps sync + async methods; sync throws / async rejections become
+ * `status=error` spans. Uses the same `traceWrap` the bootstrap
+ * auto-instrumenter uses, so a method is never double-wrapped.
+ */
+export declare function TraceMethod(nameOverrideOrOptions?: string | TraceMethodOptions): MethodDecorator;
+//# sourceMappingURL=trace-method.d.ts.map

package/lib/trace-method.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-method.d.ts","sourceRoot":"","sources":["../../src/lib/trace-method.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,CAAC,EAAE,OAAO,CAAC;CACd;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,qBAAqB,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAClD,eAAe,CAwBjB"}

package/lib/trace-method.js

@@ -0,0 +1,31 @@
+import { traceWrap } from './instrument.js';
+/**
+ * `@TraceMethod()` — decorate a service/controller method so every
+ * invocation emits a `span` event with method name + duration. Inherits
+ * the request's `flowId`/`requestId` from the `AsyncLocalStorage`
+ * context set by `TraceInterceptor`.
+ *
+ *   @Injectable()
+ *   class AuthService {
+ *     @TraceMethod()                 login(dto) { … }
+ *     @TraceMethod({ db: true })     findUser(id) { … }
+ *   }
+ *
+ * Wraps sync + async methods; sync throws / async rejections become
+ * `status=error` spans. Uses the same `traceWrap` the bootstrap
+ * auto-instrumenter uses, so a method is never double-wrapped.
+ */
+export function TraceMethod(nameOverrideOrOptions) {
+    const options = typeof nameOverrideOrOptions === 'string'
+        ? { name: nameOverrideOrOptions }
+        : nameOverrideOrOptions ?? {};
+    return function (target, propertyKey, descriptor) {
+        const fn = descriptor.value;
+        if (typeof fn !== 'function')
+            return descriptor;
+        const className = target.constructor?.name ?? 'Anonymous';
+        const spanName = options.name ?? `${className}.${String(propertyKey)}`;
+        descriptor.value = traceWrap(fn, spanName, { db: options.db });
+        return descriptor;
+    };
+}

package/lib/trace-provider.d.ts

@@ -0,0 +1,7 @@
+export interface TraceProviderOptions {
+    /** Track this provider's container fields for memory growth. */
+    memory?: boolean;
+}
+export declare function TraceProvider(options?: TraceProviderOptions): ClassDecorator;
+export declare function readTraceProvider(ctor: unknown): TraceProviderOptions | undefined;
+//# sourceMappingURL=trace-provider.d.ts.map

package/lib/trace-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-provider.d.ts","sourceRoot":"","sources":["../../src/lib/trace-provider.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,cAAc,CAMhF;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,GACZ,oBAAoB,GAAG,SAAS,CAOlC"}