diff --git a/apps/docs/content/2.learn/2.wide-events.md b/apps/docs/content/2.learn/2.wide-events.md index 1ce8821b..bc8a2813 100644 --- a/apps/docs/content/2.learn/2.wide-events.md +++ b/apps/docs/content/2.learn/2.wide-events.md @@ -14,8 +14,13 @@ links: to: /reference/best-practices color: neutral variant: subtle +seo: + title: "What are wide events? One log event per request" + description: "A wide event is one structured log event per request, job or script, carrying every field the work touched. How wide events work, with TypeScript examples." --- +A wide event is one structured log event per unit of work, such as an HTTP request, a script run or a queue job. It carries every field that work touched: who called, what they sent, what happened and how it ended. The same pattern is known as [canonical log lines](https://stripe.com/blog/canonical-log-lines) at Stripe. + Wide events are the core concept behind evlog. Instead of scattering logs throughout your codebase, you accumulate context over any unit of work, whether a request, script, job, or workflow, and emit a single, comprehensive log event. ::callout{icon="i-lucide-globe" color="neutral"} @@ -582,6 +587,26 @@ evlog automatically switches between formats based on environment: pretty in dev ``` :: +## FAQ + +::accordion{type="single"} + ::accordion-item{label="How is a wide event different from a structured log?"} + Structured logging is the format: key-value fields, usually JSON, instead of free text. A wide event is a structured log with a scope. One unit of work produces one event, so the fields that would be spread over several lines sit on the same record and can be queried together. + :: + ::accordion-item{label="Are wide events the same as traces?"} + No. A wide event is a log record, while a span is a timed operation inside a trace. evlog does not create spans or metrics. It can attach the incoming `traceparent` to the event and export it over OTLP, so the event lands next to the spans your stack already emits ([evlog and OpenTelemetry](/compare/opentelemetry)). + :: + ::accordion-item{label="Do wide events cost more to store?"} + Usually less. Line-per-step logging repeats the level, timestamp and request context on every line. On the checkout request measured in [Log cost](/reference/cost), one event is 56% fewer bytes and 75% fewer events than four lines. To cut volume further, [sampling](/learn/sampling) drops routine events and can keep every error and slow request. + :: + ::accordion-item{label="How does evlog emit a wide event?"} + With a framework integration, the middleware creates a logger per request and emits it when the response ends, including when the handler throws. Next.js navigation signals such as `redirect()` and `notFound()` are rethrown without an event. `useLogger(event)` retrieves that logger. In scripts and jobs, `createLogger()` gives you the same logger and you call `log.emit()` yourself. After emit the logger is sealed, and `log.fork()` covers background work that needs its own event. + :: + ::accordion-item{label="What should I put in a wide event?"} + IDs and business context grouped by entity (`user`, `cart`, `payment`), plus the outcome. Log IDs rather than whole objects, and leave secrets out. Redaction is on by default in production once `initLogger()` has run, so a script that only calls `createLogger()` has none ([Redaction](/learn/redaction)). [Best Practices](/reference/best-practices) covers naming and what to skip. + :: +:: + ## Next Steps - [Simple Logging](/learn/simple-logging) - Fire-and-forget logs when you don't need context accumulation