@unhandled/fastify
v0.2.7
Published
Unhandled for Fastify: route names, users, body capture and error reporting on top of @unhandled/node
Readme
@unhandled/fastify
Unhandled for Fastify 5. It builds on @unhandled/node, which traces the HTTP server, outgoing requests and databases. This package's plugin names each server span after the matched route, adds the user, records request and response bodies when capture is on, reports server errors, and marks the resource with unhandled.framework.name=fastify.
Start
UNHANDLED_DSN=https://[email protected]/0b4f6c2e-8a1d-4c3e-9f7a-1234567890ab \
node --import @unhandled/fastify/register server.js@unhandled/fastify/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/fastify')
init({ serviceName: 'shop', http: { captureBodies: { enabled: true } } })
})In CommonJS or a bundled app, call init(options) from @unhandled/fastify before fastify 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.
Plugin
import Fastify from 'fastify'
import { unhandled } from '@unhandled/fastify'
const app = Fastify()
await app.register(unhandled, {
user: (request) =>
request.user ? { id: request.user.id, email: request.user.email } : undefined,
})
app.get('/users/:id', showUser)The plugin is wrapped with fastify-plugin, so its hooks apply to the whole app and not only to its own encapsulation context. Register it before your routes.
onRequestsetshttp.routefromrequest.routeOptions.urland renames the span, for exampleGET /users/:id. Requests that match no route keep the bare method name.onSendresolvesuser(request, reply)and writesuser.id,user.emailanduser.nameon the server span. It runs after your auth hooks and handler. It also records the parsed request body and the serialized response payload whenhttp.captureBodiesis on. Parsed objects are recorded as JSON. Buffers and streams are not recorded.onErrorreports the error with mechanismfastify.error_handlerand the resolved user.
Which errors are reported
Fastify answers a thrown error with its status or statusCode when that is a 4xx or 5xx code, and with 500 otherwise. The plugin reports only errors answered with a 5xx. Validation errors, @fastify/sensible 4xx errors and anything else with a 4xx code are client errors and are skipped. Requests that hit the not-found handler never reach onError. The client's ignoreExceptions, ignoreStatuses and ignoreCodes rules still apply.
Instrumentation
@unhandled/node keeps @opentelemetry/instrumentation-fastify off, as the OpenTelemetry auto-instrumentations do, because it is deprecated. The plugin creates no spans of its own, so the server span is the HTTP instrumentation's. @fastify/otel, maintained by the Fastify team, is the replacement if you want a span per hook and handler.
