@unhandled/nestjs
v0.2.7
Published
Unhandled for NestJS: route names, users, body capture and exception reporting on top of @unhandled/node
Readme
@unhandled/nestjs
Unhandled for NestJS 11 on the Express platform. It builds on @unhandled/node, which traces the HTTP server, Express, Nest's controllers, outgoing requests and databases. This package's module adds the user to each request, records request and response bodies when capture is on, reports server errors from Nest's exception layer, and marks the resource with unhandled.framework.name=nestjs.
The Fastify platform is not supported yet.
Start
UNHANDLED_DSN=https://[email protected]/0b4f6c2e-8a1d-4c3e-9f7a-1234567890ab \
node --import @unhandled/nestjs/register dist/main.js@unhandled/nestjs/register hooks ES module loading and starts the SDK from UNHANDLED_DSN, UNHANDLED_ENV and OTEL_SERVICE_NAME. Use it rather than @unhandled/node/register, which leaves the framework off the resource. It works for CommonJS builds too, which is what the Nest CLI emits by default.
To pass options, either write your own register file for --import:
// instrument.ts
import { startWithEsmHook } from '@unhandled/node/hook'
await startWithEsmHook(async () => {
const { init } = await import('@unhandled/nestjs')
init({ serviceName: 'shop', http: { captureBodies: { enabled: true } } })
})or, in a CommonJS build, call init(options) from @unhandled/nestjs on the first line of main.ts, before @nestjs/core is imported. It takes every @unhandled/node option.
Like @unhandled/node, it redacts secret query values and secret path segments (not ids) from URL attributes by default (http.sanitizeUrls: false turns that off), and reads source lines only from .js/.ts source files under the app root, never from paths named in an error message or from dotfiles such as .env. The @unhandled/node README has the rules.
Module
import { Module } from '@nestjs/common'
import { UnhandledModule } from '@unhandled/nestjs'
@Module({
imports: [
UnhandledModule.forRoot({
user: (host) => {
const { user } = host.switchToHttp().getRequest()
return user ? { id: user.id, email: user.email } : undefined
},
}),
],
controllers: [UsersController],
})
export class AppModule {}UnhandledModule.forRoot(options?) registers two global providers.
UnhandledInterceptor(APP_INTERCEPTOR) runs after your guards. It setshttp.routefrom the Express route that matched, global prefix included, and renames the span, for exampleGET /users/:id. It resolvesuser(host)and writesuser.id,user.emailanduser.nameon the server span. Withhttp.captureBodieson, it records the parsed request body and the value your handler returned. Returned objects are recorded as JSON. Strings, buffers and streams are not recorded, because Nest picks their content type only while it writes them.UnhandledExceptionFilter(APP_FILTER) extendsBaseExceptionFilter. It reports the error with mechanismnestjs.exception_filterand the resolved user, then lets the base filter send Nest's usual response.
Which errors are reported
Any error that is not an HttpException is reported, and so is an HttpException with a status of 500 or higher. NotFoundException, BadRequestException, validation pipe errors and every other 4xx HttpException are responses you chose to send, so they are skipped. The client's ignoreExceptions, ignoreStatuses and ignoreCodes rules still apply.
Nest hands an error to the first global filter that catches it. If your app registers its own catch-all filter, that filter wins and nothing is reported. Extend UnhandledExceptionFilter instead of BaseExceptionFilter in that filter and call super.catch(exception, host), or call reportException from @unhandled/node/framework yourself.
The filter covers HTTP requests. Microservice and WebSocket handlers are not reported.
Instrumentation
The Express and NestJS instrumentations in @unhandled/node stay on and add middleware and controller spans. The module creates no spans of its own. If you turn the Express instrumentation off to drop the middleware spans, the interceptor still names the route.
