Introduction
After you complete the ASP.NET Core installation, unhandled exceptions are reported automatically. InjectLerixClient to
report handled exceptions yourself with extra context.
Automatic capture
AddLerix and UseLerix register two things:
- A middleware. Every exception that escapes the middleware after it
(routing, authentication, your endpoints) passes through it. By default it
reports every exception except those that carry a status below 500, such
as a
BadHttpRequestExceptionwith status 400. The middleware then rethrows, soUseExceptionHandleror the developer exception page builds exactly the response it would have built without Lerix. Requests the client aborted are not reported. - Process-level handlers.
AppDomain.UnhandledExceptionandTaskScheduler.UnobservedTaskExceptionare reported asCrashwithCriticalseverity. SetCaptureUnhandled = falseto skip them.
X-Request-Id header (or ASP.NET’s TraceIdentifier)
under metadata.request.
Change what is reported
ShouldCapture receives the exception, the HttpContext and the status
that will be sent when it is known:
Program.cs
IgnorePaths is a shortcut for skipping whole route prefixes without a
delegate.
Middleware order
UseLerix must sit after UseExceptionHandler (which would otherwise catch
the exception first) and before the middleware you want covered. A typical
pipeline:
Program.cs
Filtering errors
RequiresLerix / Lerix.AspNetCore 0.4.0 or later.
Three LerixOptions properties decide what leaves the process. They apply
to every report, whatever its origin: the ASP.NET Core middleware, the
process-level handlers, and CaptureException / CaptureMessage. Use them
for message-based filtering; use ShouldCapture (above) to decide by
exception, request or status.
Program.cs
IgnoreErrors can also be bound from appsettings.json:
appsettings.json
IgnoreErrors(IList<string>) andIgnoreErrorPatterns(IList<Regex>) run first, thenBeforeSend(Func<LerixErrorEvent, LerixErrorEvent?>) sees only what’s left.- The message matched and passed to
BeforeSendis the issue title shown in the dashboard, for exampleInvalidOperationException: boom. LerixErrorEventhasMessage,Stack(at ...lines),Type(BugType),Severity(BugSeverity) andMetadata(what you passed to the capture call, or the request context from the middleware). Device, app and runtime details are added after the hook, which runs on the thread that captured the error.- If
BeforeSendthrows, the original event is sent and the exception is only logged. It is never reported or rethrown. - A dropped report does not pin its request’s trace.
Report an error manually
LerixClient is a singleton in the container:
OrdersService.cs
CaptureException never throws and completes once the report has been
accepted or given up on. You can also discard the task with _ = to keep
going without waiting. Use CaptureMessage for something that was not
thrown:
Parameters
BugType values
BugSeverity values
What is attached to a report
Stack traces include inner exceptions, each introduced by a
--- caused by ... --- line.
File and line numbers
.NET only puts file and line numbers in stack traces when your app’s.pdb
files are available at runtime. Add a Directory.Build.props file at the
root of your repository:
Directory.Build.props
/_/ root, so this frame:
src/Api/Orders.cs:line 42. A ContinuousIntegrationBuild
build produces the same /_/ root.
If stack traces arrive with no file or line at all, the SDK logs one warning
per process that points to this page.
Other LerixClient members
Disable in tests
SetEnabled = false to turn every call into a no-op without changing your
code: