Libraries

A library that throws new Error('Upstream request failed') hands its host a string. The host's dashboards cannot count it, its support channel cannot search it, and the developer debugging it at 2am learns nothing from it. Your package runs inside their process, but its failures are invisible.

evlog inside the package changes what the host receives. Progress logs become named events the host can filter. Failures become structured errors with a code, a cause, and a fix, routed through the drain pipeline the host already configured. Every host that runs evlog gets your package's telemetry for free, in the same shape as its own.

The contract

Your package emits. The host configures. Everything about where events go, which ones survive sampling, and what gets redacted is decided by the application's initLogger() call. Library code never calls it: initLogger() writes process-wide state shared by every evlog copy of the same major, and the last call wins. A library that calls it at import time replaces the host's drain for the whole process, and takes the host's logging down with a single require.

That single rule settles most of the decisions on Emitting Events: which API you use, where the package name goes, and why a library accepts a request logger as a parameter instead of building one.

What this section answers

What it costs

The payoff is legibility in every host; the prices are real and small. evlog becomes a peer dependency of your package, so a host that never installed it gets a plain dependency instead. Version discipline matters: the process shares one configuration per evlog major, so pin your peer range to a single major and read what happens when two majors meet. And the emit-only contract is a real constraint: your package cannot route its own events anywhere, which is the point.

For the API underneath this section, Wide Events and Simple Logging cover the primitives as an application would use them.