# evlog

> A modern TypeScript logger for everything you ship. Simple structured logs, wide events, and structured errors in one API - for scripts, libraries, jobs, edge, and requests.

## Documentation Sets

- [evlog - full documentation](https://www.evlog.dev/llms-full.txt): Complete evlog documentation as structured markdown for deep retrieval.

## Get started

- [Introduction](https://www.evlog.dev/raw/start/introduction.md): [object Object]
- [Why start with evlog](https://www.evlog.dev/raw/start/why-evlog.md): The cheapest moment to add structured logging is before the first request. Pick evlog on day zero and the rest of the system inherits it.
- [Install evlog](https://www.evlog.dev/raw/start/installation.md): Install evlog in your TypeScript project. Supports Nuxt, Next.js, SvelteKit, Hono, Express, Fastify, Elysia, NestJS, and standalone scripts.
- [Quick Start](https://www.evlog.dev/raw/start/quick-start.md): Get up and running with evlog in minutes. Learn the log API, createLogger for wide events, useLogger for requests, and structured errors.

## Learn

- [Learn evlog](https://www.evlog.dev/raw/learn/overview.md): [object Object]
- [Simple Logging](https://www.evlog.dev/raw/learn/simple-logging.md): evlog's general-purpose logger, a drop-in for console.log, pino, or consola, with the same levels, drains, redaction, and output as wide events.
- [Wide Events](https://www.evlog.dev/raw/learn/wide-events.md): Accumulate context over any unit of work and emit a single comprehensive event. Works for HTTP requests, scripts, background jobs, queue workers, and workflows.
- [Structured Errors](https://www.evlog.dev/raw/learn/structured-errors.md): Create errors that explain why they occurred and how to fix them. Add actionable context with why, fix, and link fields for humans and AI agents.
- [Lifecycle](https://www.evlog.dev/raw/learn/lifecycle.md): An evlog event from creation to drain, across all three modes, through sampling, enrichment, and delivery.
- [Sampling](https://www.evlog.dev/raw/learn/sampling.md): [object Object]
- [Auto-Redaction](https://www.evlog.dev/raw/learn/redaction.md): Automatically scrub PII from wide events before console output and drains. Built-in smart masking for credit cards, emails, IPs, phone numbers, JWTs, and more.
- [Typed Fields](https://www.evlog.dev/raw/learn/typed-fields.md): Add compile-time type safety to your wide events with TypeScript module augmentation. Prevent typos and ensure consistent field names across your codebase.
- [Catalogs](https://www.evlog.dev/raw/learn/catalogs.md): [object Object]

## CLI

- [evlog CLI](https://www.evlog.dev/raw/cli/overview.md): [object Object]
- [evlog init](https://www.evlog.dev/raw/cli/init.md): Wire evlog into an existing app. Interactive setup that installs the package, registers the integration, and wires the destination you pick.
- [evlog map](https://www.evlog.dev/raw/cli/map.md): A deterministic observability test for your app. Scans every entry point, scores wide-event coverage, and names what to fix first.
- [Map rules](https://www.evlog.dev/raw/cli/rules.md): [object Object]
- [Map scoring](https://www.evlog.dev/raw/cli/scoring.md): [object Object]
- [evlog map in CI](https://www.evlog.dev/raw/cli/ci.md): Gate a pull request on your observability score with --min-score. The JSON contract, exit codes, GitHub Actions, and jq recipes.
- [evlog doctor](https://www.evlog.dev/raw/cli/doctor.md): Diagnose an evlog setup — Node version, project resolution, the installed evlog version, the detected framework, and whether local logs are being written.
- [CLI telemetry](https://www.evlog.dev/raw/cli/telemetry.md): What the evlog CLI collects about its own usage, how to see it, and the three ways to turn it off — DO_NOT_TRACK, EVLOG_TELEMETRY=0, or evlog telemetry disable.
- [evlog agents](https://www.evlog.dev/raw/cli/agents.md): [object Object]

## Integrate

- [Integrate evlog](https://www.evlog.dev/raw/integrate/overview.md): Pick a framework integration to capture requests, then pick adapters to ship events. Frameworks decide where the logger lives, adapters where events go.
- [Adapters Overview](https://www.evlog.dev/raw/integrate/adapters/overview.md): Send your logs to external services with evlog adapters. Built-in support for popular observability platforms and custom destinations.
- [Axiom Adapter](https://www.evlog.dev/raw/integrate/adapters/cloud/axiom.md): Send wide events to Axiom for powerful querying, dashboards, and alerting. Zero-config setup with environment variables and automatic batching.
- [PostHog Adapter](https://www.evlog.dev/raw/integrate/adapters/cloud/posthog.md): Send wide events to PostHog Logs via OTLP for structured log querying, debugging, and observability in your PostHog dashboard.
- [Sentry Adapter](https://www.evlog.dev/raw/integrate/adapters/cloud/sentry.md): Send structured logs to Sentry Logs for high-cardinality querying and debugging. Zero-config setup with environment variables.
- [Better Stack Adapter](https://www.evlog.dev/raw/integrate/adapters/cloud/better-stack.md): Send wide events to Better Stack (formerly Logtail) for log management, alerting, and dashboards. Zero-config setup with environment variables.
- [Datadog Adapter](https://www.evlog.dev/raw/integrate/adapters/cloud/datadog.md): Send wide events to Datadog Logs via the native HTTP intake API. Supports all Datadog sites and DD_* environment variables.
- [Grafana Loki Adapter](https://www.evlog.dev/raw/integrate/adapters/hybrid/loki.md): Push wide events to Grafana Loki — self-hosted, multi-tenant, or Grafana Cloud — with low-cardinality labels and full JSON querying.
- [ClickHouse Adapter](https://www.evlog.dev/raw/integrate/adapters/hybrid/clickhouse.md): Insert wide events into ClickHouse over the HTTP interface — typed columns for what you aggregate, full JSON for everything else.
- [OTLP Adapter](https://www.evlog.dev/raw/integrate/adapters/hybrid/otlp.md): Send logs via OpenTelemetry Protocol (OTLP) to Grafana, Datadog, Honeycomb, and any compatible backend. Supports gRPC and HTTP transports.
- [HyperDX Adapter](https://www.evlog.dev/raw/integrate/adapters/hybrid/hyperdx.md): Send wide events to HyperDX over OTLP/HTTP, using its documented endpoint and authorization header. Configured from environment variables.
- [File System Adapter](https://www.evlog.dev/raw/integrate/adapters/self-hosted/fs.md): Write wide events to the local file system as NDJSON for local debugging, AI agent integration, and production backup.
- [NuxtHub Storage](https://www.evlog.dev/raw/integrate/adapters/self-hosted/nuxthub.md): Self-hosted retention using NuxtHub database storage. Store, query, and clean up your wide events with no external dependency.
- [Memory Adapter](https://www.evlog.dev/raw/integrate/adapters/self-hosted/memory.md): Store wide events in an in-memory ring buffer. Works in any runtime — including Cloudflare Workers (workerd) — where the file system is unavailable.
- [Framework Integrations](https://www.evlog.dev/raw/integrate/frameworks/overview.md): evlog supports every major TypeScript framework. Choose your stack and get started in minutes.
- [Nuxt](https://www.evlog.dev/raw/integrate/frameworks/nuxt.md): Automatic wide events, structured errors, drain adapters, enrichers, tail sampling, and client transport in Nuxt applications.
- [Next.js](https://www.evlog.dev/raw/integrate/frameworks/nextjs.md): Wide events, structured errors, drain pipeline, tail sampling, route-based services, error handling, and client-side logging in Next.js applications.
- [SvelteKit](https://www.evlog.dev/raw/integrate/frameworks/sveltekit.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in SvelteKit applications.
- [Nitro](https://www.evlog.dev/raw/integrate/frameworks/nitro.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in Nitro v2 and v3 applications.
- [TanStack Start](https://www.evlog.dev/raw/integrate/frameworks/tanstack-start.md): Automatic wide events, structured errors, and logging in TanStack Start API routes and server functions.
- [NestJS](https://www.evlog.dev/raw/integrate/frameworks/nestjs.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in NestJS applications.
- [Express](https://www.evlog.dev/raw/integrate/frameworks/express.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in Express applications.
- [Hono](https://www.evlog.dev/raw/integrate/frameworks/hono.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in Hono applications.
- [Fastify](https://www.evlog.dev/raw/integrate/frameworks/fastify.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in Fastify applications.
- [Elysia](https://www.evlog.dev/raw/integrate/frameworks/elysia.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in Elysia applications.
- [React Router](https://www.evlog.dev/raw/integrate/frameworks/react-router.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in React Router applications.
- [Cloudflare Workers](https://www.evlog.dev/raw/integrate/frameworks/cloudflare-workers.md): Wide events, structured errors, and logging in Cloudflare Workers and Durable Objects.
- [Standalone TypeScript](https://www.evlog.dev/raw/integrate/frameworks/standalone.md): Use evlog in standalone TypeScript scripts, CLI tools, queues, cron jobs, and any TypeScript process.
- [Astro](https://www.evlog.dev/raw/integrate/frameworks/astro.md): Wide events and structured errors in Astro server middleware.
- [oRPC](https://www.evlog.dev/raw/integrate/frameworks/orpc.md): Automatic wide events, structured errors, drain adapters, enrichers, and tail sampling in oRPC applications.
- [AWS Lambda](https://www.evlog.dev/raw/integrate/frameworks/aws-lambda.md): Wide events and structured logging in AWS Lambda functions, including SQS consumers and event-driven handlers.

## Use cases

- [Use Cases](https://www.evlog.dev/raw/use-cases/overview.md): [object Object]
- [Client Logging](https://www.evlog.dev/raw/use-cases/client-logging.md): Capture browser events with structured logging. Same API as the server, with automatic console styling, user identity context, and optional server transport.
- [AI SDK Integration](https://www.evlog.dev/raw/use-cases/ai-sdk/overview.md): Capture token usage, tool calls, model info, and streaming metrics from the Vercel AI SDK into wide events. Wrap your model, get the rest free.
- [Usage Patterns](https://www.evlog.dev/raw/use-cases/ai-sdk/usage.md): streamText, generateText, multi-step agents, RAG, and multiple models — every common AI SDK pattern wired into evlog.
- [Options](https://www.evlog.dev/raw/use-cases/ai-sdk/options.md): Configure tool input capture (with redaction and truncation), enable cost estimation per model, and handle errors during AI calls.
- [Access Metadata](https://www.evlog.dev/raw/use-cases/ai-sdk/metadata.md): Read AI metadata from your handler — persist it, surface it to end-users, bill against it, or stream incremental progress to the client.
- [Deeper Telemetry](https://www.evlog.dev/raw/use-cases/ai-sdk/telemetry.md): Add tool execution timing and total wall time with createEvlogIntegration. Compose with other middleware like supermemory or guardrails.
- [Better Auth Integration](https://www.evlog.dev/raw/use-cases/better-auth/overview.md): Identify users on every request. Each wide event carries who made it, their profile, and session metadata, with no manual log.set call.
- [identifyUser](https://www.evlog.dev/raw/use-cases/better-auth/identify-user.md): The core building block — extract safe user fields, mask emails, and capture plugin data (organizations, roles, 2FA) from a Better Auth session.
- [createAuthMiddleware](https://www.evlog.dev/raw/use-cases/better-auth/middleware.md): Framework-agnostic factory with route filtering, session timing, and lifecycle hooks. Call it once at startup and reuse across requests.
- [Client Identity Sync](https://www.evlog.dev/raw/use-cases/better-auth/client-sync.md): Mirror the server-side user identity into client-side logs by watching the Better Auth session and calling setIdentity.
- [Performance & Composition](https://www.evlog.dev/raw/use-cases/better-auth/performance.md): Watch session resolution time, enable session caching, wire the standalone Nitro hook, and combine with the AI SDK integration.
- [Audit Logs](https://www.evlog.dev/raw/use-cases/audit/overview.md): Audit logs as a thin layer over wide events. A tamper-evident trail from one enricher, one drain wrapper, and one helper.
- [Audit Schema](https://www.evlog.dev/raw/use-cases/audit/schema.md): The AuditFields type, action naming conventions, actor types, idempotency, and how the schema sits inside a regular wide event.
- [Recording Events](https://www.evlog.dev/raw/use-cases/audit/recording.md): log.audit and log.audit.deny, standalone audit(), withAudit, the defineAuditAction and defineAuditCatalog registries, and auditDiff.
- [Drains & Integrity](https://www.evlog.dev/raw/use-cases/audit/pipeline.md): auditEnricher to auto-fill request context, auditOnly to route audits to a dedicated sink, and signed for tamper-evident HMAC or hash-chain integrity.
- [Compliance](https://www.evlog.dev/raw/use-cases/audit/compliance.md): Integrity, redact presets, GDPR vs append-only, retention windows, and the most common pitfalls when shipping audit logs to production.
- [Recipes & Reference](https://www.evlog.dev/raw/use-cases/audit/recipes.md): File system, Axiom, and Postgres recipes for audit logs, plus mockAudit for tests and the full API reference.
- [telemetry](https://www.evlog.dev/raw/use-cases/telemetry/overview.md): One event per run for CLIs and automation, with privacy-safe flags, consent, an outbox, and disclosure generated from the same config.
- [Telemetry Setup](https://www.evlog.dev/raw/use-cases/telemetry/setup.md): Wire @evlog/telemetry into citty CLIs, standalone scripts, and GitHub Actions — delivery config, automatic flag capture, telemetry.set(), and debug mode.
- [Telemetry Ingest](https://www.evlog.dev/raw/use-cases/telemetry/ingest.md): [object Object]
- [Telemetry Reference](https://www.evlog.dev/raw/use-cases/telemetry/reference.md): RunEvent envelope, extending the schema with collect and custom fields, privacy rules, TELEMETRY.md disclosure, and consent / outbox reliability.
- [Enrichers](https://www.evlog.dev/raw/use-cases/enrichers.md): [object Object]
- [eve](https://www.evlog.dev/raw/use-cases/eve.md): [object Object]

## Extend

- [Extend evlog](https://www.evlog.dev/raw/extend/overview.md): Observe what flows through the pipeline, plug into it, or build your own bricks. The map of every extension point evlog exposes.
- [Stream](https://www.evlog.dev/raw/extend/stream.md): Subscribe to wide events flowing through evlog — in-process with createStreamDrain, or over the network with the local SSE stream server.
- [Custom Framework Integration](https://www.evlog.dev/raw/extend/custom-framework.md): Build evlog support for a framework or runtime that has no integration, with defineFrameworkIntegration or the lower-level helpers.
- [Diagnostics Channel](https://www.evlog.dev/raw/extend/diagnostics-channel.md): Publish every wide event on a node:diagnostics_channel, so a consumer subscribes without importing evlog and Cloudflare can Tail Worker it.
- [FS reader](https://www.evlog.dev/raw/extend/fs-reader.md): Replay and tail the local NDJSON drain with readFsLogs and tailFsLogs — works in-process or from any external Node tool, survives restarts.
- [Recipes](https://www.evlog.dev/raw/extend/consumer-recipes.md): Concrete copy-paste recipes — build your own minimal devtool, pipe to curl + jq, replay history then go live, and aggregate on the consumer side.
- [Plugins](https://www.evlog.dev/raw/extend/plugins.md): [object Object]
- [Custom Enrichers](https://www.evlog.dev/raw/extend/custom-enrichers.md): Write an enricher that adds deployment metadata, tenant ids, feature flags, or anything computed. Error isolation and merging are handled.
- [Tail Sampling](https://www.evlog.dev/raw/extend/tail-sampling.md): Decide after the fact whether to keep an event, knowing its status, duration, and errors. Keep every error, throw away healthy noise.
- [Identity Headers](https://www.evlog.dev/raw/extend/identity-headers.md): Every drain request carries User-Agent and X-Evlog-Source so receivers can triage the traffic. Override or suppress them when you need to.
- [Custom Drains](https://www.evlog.dev/raw/extend/custom-drains.md): Build a drain for any backend without a built-in adapter. Config resolution, retries, timeouts, and identity headers are handled for you.
- [Drain Pipeline](https://www.evlog.dev/raw/extend/drain-pipeline.md): Batch events, retry on failure, fan out to several destinations, and ship browser logs to your server. The pipeline that wraps every drain.

## Reference

- [Configuration](https://www.evlog.dev/raw/reference/configuration.md): [object Object]
- [Performance](https://www.evlog.dev/raw/reference/performance.md): evlog adds ~3µs per request. Faster than pino, consola, and winston in most scenarios while emitting richer, more useful events.
- [Vite Plugin](https://www.evlog.dev/raw/reference/vite-plugin.md): Build-time optimizations for any Vite-based framework. Auto-init, debug stripping, source location injection, and optional auto-imports.
- [Best Practices](https://www.evlog.dev/raw/reference/best-practices.md): Security guidelines, data sanitization, and production tips for evlog. Learn what not to log and how to protect sensitive data.
- [evlog vs pino, winston, consola](https://www.evlog.dev/raw/reference/vs-other-loggers.md): [object Object]
- [Agent Skills](https://www.evlog.dev/raw/reference/agent-skills.md): AI-assisted code review and evlog adoption using Agent Skills. Let AI review your logging patterns and guide migration to wide events.
- [Log cost](https://www.evlog.dev/raw/reference/cost.md): [object Object]

## Notes

- evlog is MIT-licensed and drop-in for console.log, pino, or consola.
- Wide events replace log lines: log.set accumulates context, createError carries why and fix.
- The CLI ships `evlog map`, a deterministic observability score that gates in CI.