@unhandled/express
v0.2.7
Published
Unhandled for Express: route names, users, body capture and error reporting on top of @unhandled/node
Readme
@unhandled/express
Unhandled for Express 5. It builds on @unhandled/node, which traces the HTTP server, Express middleware, outgoing requests and databases. This package adds the user to each request, records request and response bodies when capture is on, reports server errors from Express's error pipeline, and marks the resource with unhandled.framework.name=express.
Start
UNHANDLED_DSN=https://[email protected]/0b4f6c2e-8a1d-4c3e-9f7a-1234567890ab \
node --import @unhandled/express/register server.js@unhandled/express/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.
To pass options in an ES module app, write your own register file and load it with --import:
// instrument.ts
import { startWithEsmHook } from '@unhandled/node/hook'
await startWithEsmHook(async () => {
const { init } = await import('@unhandled/express')
init({ serviceName: 'shop', http: { captureBodies: { enabled: true } } })
})In CommonJS or a bundled app, call init(options) from @unhandled/express before express is first required. 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.
Middleware
import express from 'express'
import { unhandledErrorHandler, unhandledMiddleware } from '@unhandled/express'
const app = express()
app.use(express.json())
app.use(
unhandledMiddleware({
user: (req) => (req.user ? { id: req.user.id, email: req.user.email } : undefined),
})
)
app.get('/users/:id', showUser)
app.use(unhandledErrorHandler())
app.use(yourErrorHandler)unhandledMiddleware(options?) goes before your routes. user(req, res) runs when the response finishes, so it sees whatever your auth middleware put on the request. The result lands on the request's server span as user.id, user.email and user.name.
unhandledErrorHandler() goes after your routes and before your own error handlers. It reports the error with mechanism express.error_handler, then passes it on with next(err), so your handlers and Express's default response still run. It reports only errors Express answers with a 5xx: an error whose status or statusCode is between 400 and 499 is a client error and is skipped. The report carries the user from unhandledMiddleware, and the client's ignoreExceptions, ignoreStatuses and ignoreCodes rules still apply.
Routes
The Express instrumentation in @unhandled/node names each server span after the matched route (GET /users/:id, mount paths included) and records it as http.route. If you turn that instrumentation off with instrumentations: { '@opentelemetry/instrumentation-express': { enabled: false } }, the middleware fills the route in from req.baseUrl and req.route.path instead. In that mode an error thrown inside a mounted router loses the mount path, because Express resets req.baseUrl once the error leaves the router.
Bodies
With http.captureBodies on, the middleware records the body your body parser produced and the body passed to res.send or res.json. Parsed objects are recorded as JSON. Buffers from express.raw() and streamed responses are not recorded.
