Skip to content

ref(nestjs): extract shared span helpers#22175

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
isaacs merged 1 commit into from
Jul 13, 2026
Merged

ref(nestjs): extract shared span helpers #22175

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 2 additions & 16 deletions packages/nestjs/src/decorators.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@ import { captureException, SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENT
import * as Sentry from '@sentry/node';
import { startSpan } from '@sentry/node';
import { isExpectedError } from './helpers';
import { copyReflectMetadata } from './integrations/helpers';

/**
* A decorator wrapping the native nest Cron decorator, sending check-ins to Sentry.
Expand DownExpand Up@@ -100,20 +101,5 @@ function copyFunctionNameAndMetadata({
writable: true,
});

// copy metadata
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
if (typeof Reflect !== 'undefined' && typeof Reflect.getMetadataKeys === 'function') {
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
const originalMetaData = Reflect.getMetadataKeys(originalMethod);
for (const key of originalMetaData) {
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
const value = Reflect.getMetadata(key, originalMethod);
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
Reflect.defineMetadata(key, value, descriptor.value);
}
}
copyReflectMetadata(originalMethod, descriptor.value as object);
}
101 changes: 82 additions & 19 deletions packages/nestjs/src/integrations/helpers.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -7,40 +7,103 @@ import {
} from '@sentry/core';
import type { CatchTarget, InjectableTarget, NextFunction, Observable, Subscription } from './types';

const sentryPatched = 'sentryPatched';
/** A function of unknown signature, matching the methods/handlers we wrap. */
export type AnyFn = (this: unknown, ...args: unknown[]) => unknown;

/**
* Helper checking if a concrete target class is already patched.
*
* We already guard duplicate patching with isWrapped. However, isWrapped checks whether a file has been patched, whereas we use this check for concrete target classes.
* This check might not be necessary, but better to play it safe.
* Marks a function as already wrapped so repeated subscriptions/decoration
* don't double-wrap it.
*/
export function isPatched(target: InjectableTarget | CatchTarget): boolean {
if (target.sentryPatched) {
return true;
const SENTRY_WRAPPED = Symbol.for('sentry.nestjs.wrapped');

/** Whether `fn` has already been wrapped by this integration. */
export function isWrapped(fn: AnyFn): boolean {
return !!(fn as AnyFn & Record<symbol, unknown>)[SENTRY_WRAPPED];
}

/** Mark `fn` as wrapped (see {@link isWrapped}). */
export function markWrapped(fn: AnyFn): void {
(fn as AnyFn & Record<symbol, unknown>)[SENTRY_WRAPPED] = true;
}

/**
* The subset of `reflect-metadata`'s `Reflect` augmentation that NestJS
* relies on. Methods are optional because `reflect-metadata` may not be
* loaded; guard each before use.
*/
export interface ReflectWithMetadata {
getMetadataKeys?: (target: object) => unknown[];
getMetadata?: (key: unknown, target: object) => unknown;
defineMetadata?: (key: unknown, value: unknown, target: object) => void;
}

/**
* Copy NestJS reflect-metadata from one object onto another so decorators
* (param decorators, guards, `@EventPattern`, ...) that read it keep working
* No-op when `reflect-metadata` isn't loaded.
*/
export function copyReflectMetadata(from: object, to: object): void {
const R = Reflect as ReflectWithMetadata;
if (
typeof R.getMetadataKeys !== 'function' ||
typeof R.getMetadata !== 'function' ||
typeof R.defineMetadata !== 'function'
) {
return;
}
for (const key of R.getMetadataKeys(from)) {
R.defineMetadata(key, R.getMetadata(key, from), to);
}
}
Comment thread
isaacs marked this conversation as resolved.

addNonEnumerableProperty(target, sentryPatched, true);
/**
* Mark a target class as patched (for the given pass) so it's instrumented
* only once, and to stay idempotent across repeated subscriptions/decoration.
*/
export function isTargetPatched(target: object, flag: 'sentryPatchedInjectable' | 'sentryPatchedCatch'): boolean {
if ((target as Record<string, unknown>)[flag]) {
return true;
}
addNonEnumerableProperty(target, flag, true);
return false;
}

/** Origin for middleware/guard/pipe/interceptor/exception_filter spans. */
function middlewareOrigin(componentType?: string): string {
return componentType ? `auto.middleware.nestjs.${componentType}` : 'auto.middleware.nestjs';
}

/**
* Origin for the app-creation / request-context / request-handler HTTP spans.
*/
export function httpOrigin(): string {
Comment thread
isaacs marked this conversation as resolved.
return 'auto.http.otel.nestjs';
}

/** Origin for `@OnEvent` spans. */
function eventOrigin(): string {
return 'auto.event.nestjs';
}

/** Origin for BullMQ `@Processor` `process` spans. */
function bullmqOrigin(): string {
return 'auto.queue.nestjs.bullmq';
}

/**
* Returns span options for nest middleware spans.
* name = provided name or class name.
*/
// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
export function getMiddlewareSpanOptions(
target: InjectableTarget | CatchTarget,
target: InjectableTarget | CatchTarget | { name?: string },
name: string | undefined = undefined,
componentType: string | undefined = undefined,
) {
const span_name = name ?? target.name; // fallback to class name if no name is provided
const origin = componentType ? `auto.middleware.nestjs.${componentType}` : 'auto.middleware.nestjs';

): { name: string; attributes: Record<string, string> } {
return {
name: span_name,
name: name ?? target.name ?? 'unknown',
attributes: {
[SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'middleware.nestjs',
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: origin,
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: middlewareOrigin(componentType),
},
};
}
Expand All@@ -57,7 +120,7 @@ export function getEventSpanOptions(event: string): {
name: `event ${event}`,
attributes: {
[SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'event.nestjs',
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.event.nestjs',
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: eventOrigin(),
},
forceTransaction: true,
};
Expand All@@ -75,7 +138,7 @@ export function getBullMQProcessSpanOptions(queueName: string): {
name: `${queueName} process`,
attributes: {
[SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'queue.process',
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.queue.nestjs.bullmq',
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: bullmqOrigin(),
'messaging.system': 'bullmq',
'messaging.destination.name': queueName,
},
Expand Down
50 changes: 6 additions & 44 deletions packages/nestjs/src/integrations/sentry-nest-bullmq-instrumentation.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -5,19 +5,18 @@ import {
InstrumentationNodeModuleFile,
isWrapped,
} from '@opentelemetry/instrumentation';
import { captureException, SDK_VERSION, startSpan, withIsolationScope } from '@sentry/core';
import { getBullMQProcessSpanOptions } from './helpers';
import { SDK_VERSION } from '@sentry/core';
import type { ProcessorDecoratorTarget } from './types';
import { extractQueueName, patchProcessorTarget } from './wrap-handlers';

const supportedVersions = ['>=10.0.0'];
const COMPONENT = '@nestjs/bullmq';

/**
* Custom instrumentation for nestjs bullmq module.
*
* This hooks into the `@Processor` class decorator, which is applied on queue processor classes.
* It wraps the `process` method on the decorated class to fork the isolation scope for each job
* invocation, create a span, and capture errors.
* This hooks into the `@Processor` class decorator, which is applied on queue
* processor classes.
*/
export class SentryNestBullMQInstrumentation extends InstrumentationBase {
public constructor(config: InstrumentationConfig = {}) {
Expand DownExpand Up@@ -62,50 +61,13 @@ export class SentryNestBullMQInstrumentation extends InstrumentationBase {
return function wrapProcessor(original: any) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return function wrappedProcessor(...decoratorArgs: any[]) {
// Extract queue name from decorator args
// @Processor('queueName') or @Processor({ name: 'queueName' })
const queueName =
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
typeof decoratorArgs[0] === 'string' ? decoratorArgs[0] : decoratorArgs[0]?.name || 'unknown';
const queueName = extractQueueName(decoratorArgs[0]);

// Get the original class decorator
// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
const classDecorator = original(...decoratorArgs);

// Return a new class decorator that wraps the process method
return function (target: ProcessorDecoratorTarget) {
const originalProcess = target.prototype.process;

if (
originalProcess &&
typeof originalProcess === 'function' &&
!target.__SENTRY_INTERNAL__ &&
!originalProcess.__SENTRY_INSTRUMENTED__
) {
target.prototype.process = new Proxy(originalProcess, {
apply: (originalProcessFn, thisArg, args) => {
return withIsolationScope(() => {
return startSpan(getBullMQProcessSpanOptions(queueName), async () => {
try {
return await originalProcessFn.apply(thisArg, args);
} catch (error) {
captureException(error, {
mechanism: {
handled: false,
type: 'auto.queue.nestjs.bullmq',
},
});
throw error;
}
});
});
},
});

target.prototype.process.__SENTRY_INSTRUMENTED__ = true;
}

// Apply the original class decorator
patchProcessorTarget(target, queueName);
// eslint-disable-next-line @typescript-eslint/no-unsafe-return
return classDecorator(target);
};
Expand Down
87 changes: 4 additions & 83 deletions packages/nestjs/src/integrations/sentry-nest-event-instrumentation.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -5,9 +5,10 @@ import {
InstrumentationNodeModuleFile,
isWrapped,
} from '@opentelemetry/instrumentation';
import { isObjectLike, captureException, SDK_VERSION, startSpan, withIsolationScope } from '@sentry/core';
import { getEventSpanOptions } from './helpers';
import { SDK_VERSION } from '@sentry/core';
import type { AnyFn } from './helpers';
import type { OnEventTarget } from './types';
import { patchMethodDescriptor, wrapEventHandler } from './wrap-handlers';

const supportedVersions = ['>=2.0.0'];
const COMPONENT = '@nestjs/event-emitter';
Expand All@@ -16,9 +17,6 @@ const COMPONENT = '@nestjs/event-emitter';
* Custom instrumentation for nestjs event-emitter
*
* This hooks into the `OnEvent` decorator, which is applied on event handlers.
* Wrapped handlers run inside a forked isolation scope to ensure event-scoped data
* (breadcrumbs, tags, etc.) does not leak between concurrent event invocations
* or into subsequent HTTP requests.
*/
export class SentryNestEventInstrumentation extends InstrumentationBase {
public constructor(config: InstrumentationConfig = {}) {
Expand DownExpand Up@@ -62,87 +60,10 @@ export class SentryNestEventInstrumentation extends InstrumentationBase {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
return function wrapOnEvent(original: any) {
return function wrappedOnEvent(event: unknown, options?: unknown) {
// Get the original decorator result
const decoratorResult = original(event, options);

// Return a new decorator function that wraps the handler
return (target: OnEventTarget, propertyKey: string | symbol, descriptor: PropertyDescriptor) => {
if (
!descriptor.value ||
typeof descriptor.value !== 'function' ||
target.__SENTRY_INTERNAL__ ||
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
descriptor.value.__SENTRY_INSTRUMENTED__
) {
return decoratorResult(target, propertyKey, descriptor);
}

function eventNameFromEvent(event: unknown): string {
if (typeof event === 'string') {
return event;
} else if (Array.isArray(event)) {
return event.map(eventNameFromEvent).join(',');
} else return String(event);
}

const originalHandler = descriptor.value;
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
const handlerName = originalHandler.name || propertyKey;
let eventName = eventNameFromEvent(event);

// Instrument the actual handler
descriptor.value = async function (...args: unknown[]) {
// When multiple @OnEvent decorators are used on a single method, we need to get all event names
// from the reflector metadata as there is no information during execution which event triggered it
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
if (Reflect.getMetadataKeys(descriptor.value).includes('EVENT_LISTENER_METADATA')) {
// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-ignore - reflect-metadata of nestjs adds these methods to Reflect
const eventData = Reflect.getMetadata('EVENT_LISTENER_METADATA', descriptor.value);
if (Array.isArray(eventData)) {
eventName = eventData
.map((data: unknown) => {
if (isObjectLike(data) && 'event' in data && data.event) {
return eventNameFromEvent(data.event);
}
return '';
})
.reverse() // decorators are evaluated bottom to top
.join('|');
}
}

return withIsolationScope(() => {
return startSpan(getEventSpanOptions(eventName), async () => {
try {
// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
const result = await originalHandler.apply(this, args);
return result;
} catch (error) {
// exceptions from event handlers are not caught by global error filter
captureException(error, {
mechanism: {
handled: false,
type: 'auto.event.nestjs',
},
});
throw error;
}
});
});
};

// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
descriptor.value.__SENTRY_INSTRUMENTED__ = true;

// Preserve the original function name
Object.defineProperty(descriptor.value, 'name', {
value: handlerName,
configurable: true,
});

// Apply the original decorator
patchMethodDescriptor(target, propertyKey, descriptor, (handler: AnyFn) => wrapEventHandler(handler, event));
return decoratorResult(target, propertyKey, descriptor);
};
};
Expand Down
Loading
Loading