@unhandled/hono
v0.2.7
Published
Unhandled for Hono on Node.js: route names, users, body capture and error reporting on top of @unhandled/node
Readme
@unhandled/hono
Unhandled for Hono 4.8 or later on Node.js with @hono/node-server. It builds on @unhandled/node, whose HTTP instrumentation creates the server span for every request @hono/node-server receives. This package's middleware names that 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=hono.
Hono on other runtimes (Workers, Deno, Bun) is not covered: the package needs the Node HTTP server span.
Start
UNHANDLED_DSN=https://[email protected]/0b4f6c2e-8a1d-4c3e-9f7a-1234567890ab \
node --import @unhandled/hono/register server.js@unhandled/hono/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/hono')
init({ serviceName: 'shop', http: { captureBodies: { enabled: true } } })
})In CommonJS or a bundled app, call init(options) from @unhandled/hono before anything else is loaded. 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 { serve } from '@hono/node-server'
import { Hono } from 'hono'
import { unhandled } from '@unhandled/hono'
const app = new Hono<{ Variables: { user?: { id: string } } }>()
app.use(unhandled({ user: (c) => c.get('user') }))
app.get('/users/:id', (c) => c.json(loadUser(c.req.param('id'))))
serve({ fetch: app.fetch, port: 3000 })Register unhandled(options?) first, so every other middleware and handler runs inside it. After the rest of the chain has run, it:
- sets
http.routeto the path of the route that answered (fromhono/route) and renames the span, for exampleGET /users/:id. A 404 answered by ause()orall()entry means no route matched, and the span keeps the bare method name. - resolves
user(c)and writesuser.id,user.emailanduser.nameon the server span. It runs after your auth middleware, soc.get(...)values are there. - reports
c.errorwith mechanismhono.on_errorand the resolved user. Hono setsc.errorbefore it calls yourapp.onErrorhandler, so a custom handler changes the response but not the report. - records the request and response bodies when
http.captureBodiesis on and the content type is JSON or a URL-encoded form. It never reads a request body itself. It records the body your handler already read withc.req.json()orc.req.text(). For the response it copies a body that is already in memory, and skips a streamed response instead of waiting for it.
Which errors are reported
Every error that is not an HTTPException is reported. An HTTPException is reported only when its status is 500 or higher, because a 4xx HTTPException is a response you chose to send. The client's ignoreExceptions, ignoreStatuses and ignoreCodes rules still apply.
