Logging and error hooks

Dotpress logs through one logger, given to the app, and gives each request a logger of its own, bound to its request ID.

The logger

By default, the app logs to the console, from the info level. Pass your logger to createApp():

import pino from 'pino'

const app = await createApp({ adapter, logger: pino() })

The Logger interface is the one of Pino: a Pino instance works as is. Any logger with debug, info, warn, error and child() methods, accepting (message) or (data, message), works too.

The default logger can be configured:

import { createConsoleLogger } from '@dotpress/core'

const logger = createConsoleLogger({ level: 'debug', bindings: { service: 'billing-api' } })

The request logger

ctx.logger is a child logger: every line it writes carries the requestId of the request.

defineRoute<"/payments/:id/refund", EmptyObject, false, unknown[]>(route: RouteConfig<"/payments/:id/refund", EmptyObject, EmptyObject, false, unknown[], unknown>): voidDeclares a route on the global router.defineRoute({
  RouteConfig<P extends string, S extends RouteSchema, TParentParams = EmptyObject, TRawBody extends boolean = false, TProvided extends readonly unknown[] = unknown[], TGroupContext = unknown>.method?: HttpMethod | undefinedDefaults to get.method: 'post',
  RouteConfig<"/payments/:id/refund", EmptyObject, EmptyObject, false, unknown[], unknown>.path: "/payments/:id/refund"path: '/payments/:id/refund',
  RouteConfig<"/payments/:id/refund", EmptyObject, EmptyObject, false, unknown[], unknown>.handler: RouteHandler<EmptyObject, {
    id: string;
}, false, unknown>
handler: async ({ req: RouteRequest<EmptyObject, {
    id: string;
}, false>
req, logger: LoggerLogger bound to the request (requestId field).logger }) => {
    const const refund: {
    amount: number;
}
refund = await const payments: {
    refund(id: string): Promise<{
        amount: number;
    }>;
}
payments.function refund(id: string): Promise<{
    amount: number;
}>
refund(req: RouteRequest<EmptyObject, {
    id: string;
}, false>
req.DotpressRequest<{ id: string; }, QueryValues, unknown, UploadedFiles>.params: {
    id: string;
}
params.id: stringid)
    logger: LoggerLogger bound to the request (requestId field).logger.Logger.info: LogFn
(data: object, message?: string, ...args: unknown[]) => void (+1 overload)
info({ paymentId: stringpaymentId: req: RouteRequest<EmptyObject, {
    id: string;
}, false>
req.DotpressRequest<{ id: string; }, QueryValues, unknown, UploadedFiles>.params: {
    id: string;
}
params.id: stringid, amount: numberamount: const refund: {
    amount: number;
}
refund.amount: numberamount }, 'Payment refunded')
    return const refund: {
    amount: number;
}
refund
  },
})

Pass ctx.logger to the services a request calls: their log lines are tied to the request. ctx.events and ctx.mailer use the request logger for you.

Request IDs

Each request gets an ID, crypto.randomUUID() by default. It is:

ctx.requestId in handlers and middlewares;
bound to every line of ctx.logger;
sent back in the X-Request-ID header of every response, errors included.

To reuse the ID set by a gateway or a load balancer, use generateRequestId. Accept it only from a proxy you trust, and check its format:

const const app: App<unknown>app = await createApp<HttpAdapter<unknown>>(options: AppOptions<HttpAdapter<unknown>>): Promise<App<unknown>>Creates a Dotpress application and mounts its routes on the adapter.createApp({
  AppOptions<HttpAdapter<unknown>>.adapter: HttpAdapter<unknown>HTTP adapter (Express, Hono, Fastify…).adapter,
  AppOptions<HttpAdapter<unknown>>.generateRequestId?: ((request: NormalizedRequest) => string) | undefinedDefaults to crypto.randomUUID().generateRequestId: (request: NormalizedRequestrequest) => {
    const const id: string | string[] | undefinedid = request: NormalizedRequestrequest.NormalizedRequest.headers: IncomingHeadersRequest headers, with lowercase names.headers['x-request-id']
    return typeof const id: string | string[] | undefinedid === 'string' && /^[\w-]{8,64}$/.RegExp.test(string: string): booleanReturns a Boolean value that indicates whether or not a pattern exists in a searched string.
@paramstring  String on which to perform the search.test(const id: stringid) ? const id: stringid : var crypto: CryptoMDN Referencecrypto.Crypto.randomUUID(): `${string}-${string}-${string}-${string}-${string}`The randomUUID() method of the Crypto interface is used to generate a v4 UUID using a cryptographically secure random number generator.
Available only in secure contexts.
MDN ReferencerandomUUID()
  },
})

Logging every request

A small plugin logs every response with the onResponse hook, including the 404 and 405 of the router:

export const const httpLogger: {
    readonly name: "http-logger";
    readonly setup: (api: PluginAPI) => void;
}
httpLogger = definePlugin<{
    readonly name: "http-logger";
    readonly setup: (api: PluginAPI) => void;
}>(plugin: {
    readonly name: "http-logger";
    readonly setup: (api: PluginAPI) => void;
}): {
    readonly name: "http-logger";
    readonly setup: (api: PluginAPI) => void;
}
Declares a plugin. Extra properties are allowed, and exposed to other
plugins through api.getPlugin().
@exampleexport  const healthPlugin = (path = '/health') =>
definePlugin({
name: 'health',
setup(api) {
api.addRoute({ path, handler: () => ({ status: 'ok' }) })
},
})definePlugin({
  name: "http-logger"name: 'http-logger',
  function setup(api: PluginAPI): voidsetup(api: PluginAPIapi) {
    api: PluginAPIapi.PluginAPI.hooks: PluginHookshooks.PluginHooks.onResponse(hook: ResponseHook): voidonResponse(({ request: NormalizedRequestrequest, response: NormalizedResponseresponse, requestId: stringrequestId, duration: numberTime spent producing the response, in milliseconds. Streamed bodies are
not included.duration }) => {
      api: PluginAPIapi.PluginAPI.logger: LoggerLogger bound to the plugin (plugin field).logger.Logger.info: LogFn
(data: object, message?: string, ...args: unknown[]) => void (+1 overload)
info(
        { requestId: stringrequestId, status: numberstatus: response: NormalizedResponseresponse.NormalizedResponse.status: numberstatus, duration: numberduration: var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.Math.Math.round(x: number): numberReturns a supplied numeric expression rounded to the nearest integer.
@paramx  The value to be rounded to the nearest integer.round(duration: numberTime spent producing the response, in milliseconds. Streamed bodies are
not included.duration) },
        `${request: NormalizedRequestrequest.NormalizedRequest.method: stringHTTP method, case-insensitive.method} ${request: NormalizedRequestrequest.NormalizedRequest.path: stringRequest path, without the query string.path}`
      )
    })
  },
})

const app = await createApp({ adapter, plugins: [httpLogger] })

The hook receives the request, the final response, the request ID, the duration in milliseconds, and the route when one matched (route.path is the declared path, such as /users/:id: a good label for metrics).

Reporting errors

Unexpected errors are logged with the request logger, then passed to the onError hooks: the one of createApp(), and those of the plugins (api.onError()). See Errors.

const app = await createApp({
  adapter,
  onError: (error, ctx) => errorTracker.capture(error, { requestId: ctx?.requestId }),
})

Tracing and request-scoped storage

The wrapRequest hook of a plugin runs the whole pipeline of a request inside a function: a tracing span, or an AsyncLocalStorage context that services read without receiving ctx.

export const const requestStore: AsyncLocalStorage<{
    requestId: string;
}>
requestStore = new new AsyncLocalStorage<{
    requestId: string;
}>(): AsyncLocalStorage<{
    requestId: string;
}>
This class creates stores that stay coherent through asynchronous operations.
While you can create your own implementation on top of the node:async_hooks module, AsyncLocalStorage should be preferred as it is a performant and memory
safe implementation that involves significant optimizations that are non-obvious
to implement.
The following example uses AsyncLocalStorage to build a simple logger
that assigns IDs to incoming HTTP requests and includes them in messages
logged within each request.
import http from 'node:http';
import { AsyncLocalStorage } from 'node:async_hooks';

const asyncLocalStorage = new AsyncLocalStorage();

function logWithId(msg) {
  const id = asyncLocalStorage.getStore();
  console.log(`${id !== undefined ? id : '-'}:`, msg);
}

let idSeq = 0;
http.createServer((req, res) => {
  asyncLocalStorage.run(idSeq++, () => {
    logWithId('start');
    // Imagine any chain of async operations here
    setImmediate(() => {
      logWithId('finish');
      res.end();
    });
  });
}).listen(8080);

http.get('http://localhost:8080');
http.get('http://localhost:8080');
// Prints:
//   0: start
//   0: finish
//   1: start
//   1: finish

Each instance of AsyncLocalStorage maintains an independent storage context.
Multiple instances can safely exist simultaneously without risk of interfering
with each other's data.
@sincev13 .10.0, v12.17.0AsyncLocalStorage<{ requestId: stringrequestId: string }>()

export const const requestStorePlugin: {
    readonly name: "request-store";
    readonly setup: (api: PluginAPI) => void;
}
requestStorePlugin = definePlugin<{
    readonly name: "request-store";
    readonly setup: (api: PluginAPI) => void;
}>(plugin: {
    readonly name: "request-store";
    readonly setup: (api: PluginAPI) => void;
}): {
    readonly name: "request-store";
    readonly setup: (api: PluginAPI) => void;
}
Declares a plugin. Extra properties are allowed, and exposed to other
plugins through api.getPlugin().
@exampleexport  const healthPlugin = (path = '/health') =>
definePlugin({
name: 'health',
setup(api) {
api.addRoute({ path, handler: () => ({ status: 'ok' }) })
},
})definePlugin({
  name: "request-store"name: 'request-store',
  function setup(api: PluginAPI): voidsetup(api: PluginAPIapi) {
    api: PluginAPIapi.PluginAPI.hooks: PluginHookshooks.PluginHooks.wrapRequest(hook: RequestWrapper): voidRuns every request matching a route inside the hook (see
RequestWrapper). The hooks of the first plugins run outermost.wrapRequest((ctx: RequestContextctx, next: () => Promise<T>next) => const requestStore: AsyncLocalStorage<{
    requestId: string;
}>
requestStore.AsyncLocalStorage<{ requestId: string; }>.run<Promise<T>>(store: {
    requestId: string;
}, callback: () => Promise<T>): Promise<T> (+1 overload)
Runs a function synchronously within a context and returns its
return value. The store is not accessible outside of the callback function.
The store is accessible to any asynchronous operations created within the
callback.
The optional args are passed to the callback function.
If the callback function throws an error, the error is thrown by run() too.
The stacktrace is not impacted by this call and the context is exited.
Example:
const store = { id: 2 };
try {
  asyncLocalStorage.run(store, () => {
    asyncLocalStorage.getStore(); // Returns the store object
    setTimeout(() => {
      asyncLocalStorage.getStore(); // Returns the store object
    }, 200);
    throw new Error();
  });
} catch (e) {
  asyncLocalStorage.getStore(); // Returns undefined
  // The error will be caught here
}
@sincev13 .10.0, v12.17.0run({ requestId: stringrequestId: ctx: RequestContextctx.RequestContext.requestId: stringUnique identifier of the request, also sent as X-Request-ID.requestId }, next: () => Promise<T>next))
  },
})

The hook must call next() once, and return its result.

Coming from v1

Pino is no longer loaded automatically: pass it to createApp({ logger }). enableHttpLogging and onRequestComplete are replaced by the onResponse hook of a plugin, and onException by onError.

#Logging and error hooks

#The logger

#The request logger

#Request IDs

#Logging every request

#Reporting errors

#Tracing and request-scoped storage