Getting Started
Installation
Install evlog in your Nuxt, Nitro, or standalone TypeScript project.
evlog supports multiple environments: Nuxt, Nitro, and standalone TypeScript.
Nuxt
Add evlog as a Nuxt module:
pnpm add evlog
npm install evlog
yarn add evlog
bun add evlog
Then add it to your Nuxt config:
nuxt.config.ts
export default defineNuxtConfig({
modules: ['evlog/nuxt'],
evlog: {
env: {
service: 'my-app',
},
// Optional: only log specific routes (supports glob patterns)
include: ['/api/**'],
},
})
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
env.service | string | 'app' | Service name shown in logs |
env.environment | string | Auto-detected | Environment name |
include | string[] | undefined | Route patterns to log. Supports glob (/api/**). If not set, all routes are logged |
pretty | boolean | true in dev | Pretty print with tree formatting |
sampling.rates | object | undefined | Sampling rates per log level (0-100%). See Sampling |
Sampling
At scale, logging everything can become expensive. Use sampling to keep only a percentage of logs per level:
nuxt.config.ts
export default defineNuxtConfig({
modules: ['evlog/nuxt'],
evlog: {
sampling: {
rates: {
info: 10, // Keep 10% of info logs
warn: 50, // Keep 50% of warning logs
debug: 5, // Keep 5% of debug logs
error: 100, // Always keep errors (default)
},
},
},
})
Errors are always logged by default. Even if you don't specify
error: 100, error logs are never sampled out unless you explicitly set error: 0.Tip: Use Nuxt's
$production override to sample only in production while keeping full visibility in development:export default defineNuxtConfig({
modules: ['evlog/nuxt'],
evlog: {
env: { service: 'my-app' },
},
$production: {
evlog: {
sampling: { rates: { info: 10, warn: 50, debug: 0 } },
},
},
})
That's it! You can now use useLogger(event) in any API route.
Nitro
For standalone Nitro projects (without Nuxt), add evlog as a plugin:
nitro.config.ts
export default defineNitroConfig({
plugins: ['evlog/nitro'],
})
Standalone TypeScript
For scripts, workers, CLI tools, or any TypeScript project:
scripts/sync-job.ts
import { initLogger, createRequestLogger } from 'evlog'
// Initialize once at startup
initLogger({
env: {
service: 'my-worker',
environment: 'production',
},
// Optional: sample logs
sampling: {
rates: { info: 10, debug: 5 },
},
})
// Create a logger for each operation
const log = createRequestLogger({ jobId: job.id })
log.set({ source: job.source, target: job.target })
log.set({ recordsSynced: 150 })
log.emit() // Manual emit required in standalone mode
In standalone mode, you must call
log.emit() manually. In Nuxt/Nitro, this happens automatically at request end.TypeScript Configuration
evlog is written in TypeScript and ships with full type definitions. No additional configuration is required.
evlog requires TypeScript 5.0 or higher for optimal type inference.
Next Steps
- Quick Start - Learn the core concepts and start using evlog