Introduction
After you complete the NestJS installation, unhandled exceptions are reported automatically. InjectLerixService to
report handled exceptions yourself with extra context.
Automatic capture
LerixModule registers two things:
- A global exception filter. Every exception thrown from a controller,
guard, pipe or interceptor passes through it. By default it reports
exceptions that are not an
HttpException, andHttpExceptions with a status of 500 or above. Expected client errors such asNotFoundExceptionor a failedValidationPipeare not reported. The filter then hands the exception to Nest’s default filter, so the HTTP response is exactly what it would have been without Lerix. - Process-level handlers.
uncaughtExceptionandunhandledRejectionare reported, the report is given up toflushTimeoutMsto leave, and the process exits with code 1 as Node would. SetexitOnUnhandled: falseto keep the process alive, orcaptureUnhandled: falseto skip the handlers.
x-request-id (or x-correlation-id) header when present, under
metadata.request.
Change what is reported
shouldCapture receives the exception and a context object with the
request details:
app.module.ts
Use your own filter
If your app already registers a catch-allAPP_FILTER, set
captureHttpExceptions: false and report from that filter:
all-exceptions.filter.ts
LerixExceptionFilter and override catch to customise
the response while keeping the reporting.
Filtering errors
Requires@lerix-dev/lerix-nestjs 1.4.0 or later.
Two options decide what leaves the process. They apply to every report,
whatever its origin: the global filter, uncaught exceptions and unhandled
rejections, and captureException / captureMessage. Use them for
message-based filtering; use shouldCapture (above) to decide by
exception or request.
app.module.ts
ignoreErrorsruns first, thenbeforeSendsees only what’s left.- The message matched and passed to
beforeSendis the issue title shown in the dashboard, for exampleTypeError: Cannot read properties of undefined. - The event has
message,stack(at ...lines),type(BugType),severity(BugSeverity) andmetadata(what you passed to the capture call, or the request context from the filter). Device, app and runtime details are added after the hook. - If
beforeSendthrows, the original event is sent and the error is only logged. It is never reported or rethrown. - A dropped report does not pin its request’s trace.
HttpExceptions below 500 are already skipped by the default
shouldCapture.
Lerix also groups repeated errors into one issue and filters common noise on
the server, for every SDK version. See
How errors are grouped into issues.
Report an error manually
orders.service.ts
captureException never throws and resolves once the report has been
accepted or given up on. Use captureMessage for something that was not
thrown:
Parameters
BugType values
BugSeverity values
What is attached to a report
TypeScript file and line numbers
Stack traces are mapped back to your TypeScript source automatically. When it reports an error, the SDK reads the.js.map files that nest build writes
next to the compiled code, so a frame like dist/src/orders/orders.service.js:58
is reported as src/orders/orders.service.ts:42.
There is nothing to upload, no Node.js flag and nothing to configure. Nest
enables "sourceMap": true in tsconfig.json by default. Inline source maps
and nest build --webpack bundles work too.
Paths are made relative to the app’s working directory (normally the
repository root), so they read like repository paths. Frames from
dependencies show as node_modules/....
Other LerixService methods
Disable in tests
Passenabled: false to turn every call into a no-op without changing your
code: