Logging & Observability

Capture request duration, status, and failures from loaders and API routes with one wrap-around middleware — no per-handler instrumentation.

Recommended Shape

Pracht middleware wraps the rest of the request via next(), so a single middleware can try / catch / finally around every loader and API handler. This is the right place for Honeycomb-style request logging, OpenTelemetry spans, or anything that needs to observe the final status and any thrown error.

Manifest apps (those with routes.ts): use a tracing/logging middleware registered with defineApp. One middleware covers loaders, API routes, and inner middleware in one wrapper.
Pages router apps: there is no manifest, so wrap individual API handlers with a small higher-order function instead.
Adapter-level wrappers are only needed when you want to observe the outer HTTP cycle including framework-internal failures, since pracht converts loader/handler errors into responses before they leave its runtime.

Create a Request Logger in Context

Adapters can import a context factory with createContextFrom. This is a good place to create a request id and logger instance shared by loaders, middleware, and API handlers.

vite.config.ts

import { nodeAdapter } from "@pracht/adapter-node";
import { pracht } from "@pracht/vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    pracht({
      adapter: nodeAdapter({ createContextFrom: "/src/server/context.ts" }),
    }),
  ],
});

src/server/context.ts

import { createRequestLogger } from "./logger";

export function createContext({ request }: { request: Request }) {
  const url = new URL(request.url);
  const requestId = request.headers.get("x-request-id") ?? crypto.randomUUID();

  return {
    logger: createRequestLogger({
      method: request.method,
      path: url.pathname,
      requestId,
    }),
    requestId,
  };
}

src/env.d.ts

import type { RequestLogger } from "./server/logger";

declare module "@pracht/core" {
  interface Register {
    context: {
      logger: RequestLogger;
      requestId: string;
    };
  }
}

Wrap-Around Logging Middleware

Register the middleware once in the manifest. Apply it globally for API routes via api.middleware, and on a group/route for page routes:

src/routes.ts

import { defineApp, group, route } from "@pracht/core";

export const app = defineApp({
  middleware: {
    requestLog: "./middleware/request-log.ts",
  },
  api: {
    middleware: ["requestLog"],
  },
  routes: [
    group({ middleware: ["requestLog"] }, [
      route("/dashboard", "./routes/dashboard.tsx", { render: "ssr" }),
      route("/projects/:id", "./routes/project.tsx", { render: "ssr" }),
    ]),
  ],
});

src/middleware/request-log.ts

import type { MiddlewareFn } from "@pracht/core";

export const middleware: MiddlewareFn = async ({ context, request, route, url }, next) => {
  const startedAt = performance.now();
  let response: Response | undefined;
  let thrown: unknown;

  try {
    response = await next();
    return response;
  } catch (error) {
    thrown = error;
    throw error;
  } finally {
    const durationMs = Math.round(performance.now() - startedAt);
    const status = response?.status ?? 500;

    context.logger.event({
      durationMs,
      error: serializeError(thrown),
      method: request.method,
      path: url.pathname,
      requestId: context.requestId,
      route: route.path,
      status,
    });

    // Hand the flush off to the runtime so the response can return
    // immediately. On Cloudflare this keeps the worker alive long enough
    // for the events to ship; on Node the helper just awaits the promise.
    deferFlush(context, context.logger.flush());
  }
};

function serializeError(error: unknown) {
  if (!error) return undefined;
  if (error instanceof Error) {
    return { message: error.message, name: error.name, stack: error.stack };
  }
  return { message: String(error), name: "Error" };
}

// Cloudflare's executionContext.waitUntil keeps the worker alive past the
// response. On Node there's no equivalent — `await` would delay the
// response, and bare fire-and-forget would lose unhandled rejections, so
// just attach a catch handler.
function deferFlush(context: { executionContext?: { waitUntil(p: Promise<unknown>): void } }, flushPromise: Promise<unknown>) {
  if (context.executionContext?.waitUntil) {
    context.executionContext.waitUntil(
      flushPromise.catch((err) => console.error("[pracht] log flush failed", err)),
    );
    return;
  }
  flushPromise.catch((err) => console.error("[pracht] log flush failed", err));
}

This is the same try / catch / finally shape Hono and Koa users are accustomed to. The middleware sees the final response status and any thrown error, and finally runs as part of the request — exactly what Honeycomb / Beeline-style libraries need.

**Cloudflare:** the `fetch` handler returns once the middleware does, and the worker can be torn down at any point afterward. `await flush()` inside `finally` works but blocks the response on the flush; bare fire-and-forget risks the worker terminating mid-flight. The recommended pattern is `context.executionContext.waitUntil(flushPromise)` — the response goes out immediately and the runtime keeps the worker alive until the flush resolves. The `deferFlush` helper above handles both runtimes.

Pages Router: Higher-Order Wrapper

The pages router does not use the manifest, so register logging by wrapping individual handlers:

src/lib/with-request-logging.ts

import type { ApiRouteHandler } from "@pracht/core";

export function withRequestLogging(handler: ApiRouteHandler): ApiRouteHandler {
  return async (args) => {
    const startedAt = performance.now();
    let response: Response | undefined;
    let thrown: unknown;

    try {
      response = await handler(args);
      return response;
    } catch (error) {
      thrown = error;
      throw error;
    } finally {
      args.context.logger.event({
        durationMs: Math.round(performance.now() - startedAt),
        error: thrown ? String(thrown) : undefined,
        method: args.request.method,
        path: args.url.pathname,
        requestId: args.context.requestId,
        route: args.route.path,
        status: response?.status ?? 500,
      });
      // On Cloudflare, prefer
      // `args.context.executionContext.waitUntil(args.context.logger.flush())`
      // so the response is not blocked on the flush. On Node, `await` is fine.
      await args.context.logger.flush();
    }
  };
}

src/api/projects.ts

import { withRequestLogging } from "../lib/with-request-logging";

export const POST = withRequestLogging(async ({ request, context }) => {
  const body = await request.json();
  context.logger.event({ action: "project.create" });
  const project = await createProject(body);
  return Response.json({ project }, { status: 201 });
});

Multiple wrappers compose: withRequestLogging(withAuth(handler)).

← Testing

Full-Stack Cloudflare →