Wide Events Support

[hanneswidrig]

I didn't see any mention of "wide events" in the LogTape docs. I'm curious what the community proposes for using this style of logging with logtape?

evlog is another logging library I came across that had wide events front and center, but I really like what I've seen from LogTape, especially its answers for challenging environments like monorepos.

[dahlia]

Thanks for raising this. Wide events as a deliberate pattern aren't mentioned anywhere in the LogTape docs, and there's no dedicated API for them today. I think it's fair to say LogTape can express wide events, but doesn't support them natively in the way evlog does.

Today the closest fit is a combination of pieces.

Logger.with({...}) returns a child logger with bound properties. It's immutable, so accumulating fields means reassigning:

let log = getLogger(["api", "checkout"]).with({ requestId });
log = log.with({ user: { id: 1, plan: "pro" } });
log = log.with({ cart: { items: 3, total: 9999 } });
log.info("Checkout completed");

withContext() does the same thing across async boundaries via AsyncLocalStorage, so deeply nested handlers don't have to pass a logger around:

await withContext({ requestId }, async () => {
  await handler(); // any logger.x() call inside picks up requestId
});

Both of these merge into every log record inside their scope, which isn't quite the wide-events shape (one record per request). The trick for that is to keep a plain object as the accumulator and let handlers mutate it, then emit once at the end:

const event: Record<string, unknown> = {};
await withContext({ event }, async () => {
  await handler(); // can read the ambient event and set event.user, etc.
});
logger.info("HTTP request", event);

The logger stays immutable. Only the payload object is mutable, and it lives just for the request.

The HTTP framework integrations (Express, Hono, Koa, Fastify) already emit one record per request, but they only carry the metadata available at the middleware layer (method, status, duration, etc.). They don't yet expose a hook for handlers to enrich that record with business data, which is the part that wide events really want.

My current answer is: it works, but having to create the accumulator by hand, and having no clean way to feed business data into the framework integrations' per-request record, is friction I don't want to leave there.

I plan to add a built-in way to do this in a future LogTape version. I don't want to commit to the exact shape yet, I have a few sketches and want to sit with the tradeoffs. Treat this as a yes on the direction. If you had an API shape in mind, please sketch it here.

[hanneswidrig]

Thanks for the insightful and detailed response!

Here are some of my initial thoughts. For the API shape, I was thinking maybe something like logger.set({ ... }), drawing a bit from evlog?

I’m not entirely sure about their approach to immutability, though. They have rules for deep merging objects, concatenating arrays, and replacing primitives. It feels like a lot for a developer to have to memorize, so I’d love to avoid that kind of friction if we can.

I’ve been leaning toward the patterns you see in libraries like Immer or the React useState hook in regards to immutability. What if the API optionally took a callback for updating purposes? That would give the user more explicit control over update logic. You could decide for yourself whether to concatenate an array, push a new value, or replace a primitive, using standard JavaScript instead of library-specific merging rules.

It might also be pretty valuable to be able to explicitly type the event object, though I totally get that this probably adds a fair amount of complexity to the implementation.

[dahlia]

@hanneswidrig Thanks for digging into this further.

The callback updater point is the one I'll take into the design. Implicit merge rules, where the library quietly decides what concat means and what replace means, are the kind of thing LogTape has tried to stay away from in other places, and you're right that it accrues a memorization tax fast. A callback-style updater (set(prev => ({ ...prev, items: [...prev.items, item] }))) keeps the merge logic where the user already understands it, in their own JavaScript, and lines up with the immutable-logger model rather than fighting it. Treat that as a constraint on whatever API I sketch.

Typing the event object also needs some thought. LogTape's LogRecord["properties"] is Record<string, unknown> today, so a typed accumulator raises a follow-on question: how far should that type travel through formatters, sinks, and filters. I don't have a settled view yet, but I'd rather have the question on the record than not.

I opened #153 just before reading your reply as the tracking issue for this, intentionally without an API proposal. If you'd be up for re-posting these two points there, they'll sit on the requirements list rather than getting buried in this thread.