evlog.config

Without a config file, the CI gate is a flag on every evlog map run, a check you decided not to care about is disabled file by file, and sampling and redaction live in whichever file calls initLogger. evlog.config.ts holds all of it, and a preset carries it from one repository to the next. The CLI reads the file without running it. The app runs it: the Nuxt and Nitro modules load it on their own, and any other app imports it.

Here an app builds on a shared preset, turns a check back on, and leaves its dev routes out of the map:

import { defineEvlog } from 'evlog'
import { createAxiomDrain } from 'evlog/axiom'
import preset from './evlog.preset'

export default defineEvlog({
  extends: preset,
  service: 'checkout',
  drain: createAxiomDrain(),
  sampling: { rates: { info: 25 } },
  map: {
    rules: { 'audit-coverage': 'on' },
    ignore: ['src/routes/_dev/**'],
  },
  logs: { limit: 100 },
})

import { defineEvlog } from 'evlog'

export default defineEvlog({
  sampling: { rates: { info: 10, debug: 0 } },
  redact: { paths: ['user.password', 'card.number'] },
  map: { rules: { 'error-catalog': 'off', 'audit-coverage': 'off' }, minScore: 70 },
})

evlog config prints the merged result grouped by what each setting does, with the line it is written on, and fills in what evlog uses where the file says nothing:

evlog config

evlog.config.ts · extends ./evlog.preset → evlog.preset.ts

Service
  service      checkout       evlog.config.ts:7
  environment  from NODE_ENV  default

Sampling
  trace  0%      default
  debug  0%      evlog.preset.ts:4
  info   25%     evlog.config.ts:9
  warn   100%    default
  error  100%    default
  fatal  always  default

Redaction
  redact    on                                                 evlog.preset.ts:5
  builtins  creditCard, email, ipv4, phone, jwt, bearer, iban  default
  paths     user.password                                      evlog.preset.ts:5
            card.number                                        evlog.preset.ts:5

Pipeline
  drain  createAxiomDrain()  evlog.config.ts:8

CLI · read by evlog map and evlog logs
  map.rules.error-catalog   'off'                   evlog.preset.ts:6
  map.rules.audit-coverage  'on'                    evlog.config.ts:11
  map.minScore              70                      evlog.preset.ts:6
  map.ignore                ['src/routes/_dev/**']  evlog.config.ts:12
  logs.limit                100                     evlog.config.ts:14

Each redaction path keeps the line of the file that adds it, so a path the preset redacts never looks like the app's own. With routes, the Service section becomes Services and lists each route's service in the order evlog matches them, the first match winning. A rate that changes nothing gets a warning under its row, such as a fatal rate, since fatal events are always kept.

A value the file computes, like createAxiomDrain(), is shown as the code that produces it. --json returns the settings written in the files as cli and app lists of { path, value, source }, one entry per item of redact.paths, redact.patterns and sampling.keep, with a computed value written as { "runtime": "createAxiomDrain()" } and a regular expression as { "regexp": "/acct_\\w+/g" }. moduleOptions is { file, readable } when nuxt.config.ts or nitro.config.ts passes options to the evlog module, with readable false when they are computed at runtime, and null otherwise. A setting those options replace carries overrides: { value, source } with the value of the file.

Where evlog finds the file

The CLI and the Nuxt and Nitro modules look for evlog.config.ts, evlog.config.mts, evlog.config.js and evlog.config.mjs, in that order, starting in the app's package and walking up to the workspace root. The first file found applies on its own. Configs do not cascade, so an app with its own evlog.config.ts ignores the one at the root unless it extends it.

Paths in map.ignore, map.baseline and logs.dir are relative to the package being mapped or read, not to the config file. One config at the root of a monorepo therefore fits every app in it.

Gate the map from the config

evlog map reads the map section, and a flag passed on the command line wins over the same setting.

map.ignore matches the file an entry point is declared in. A Hono app that declares several routes in one file leaves them all out with one glob, and cannot leave out one of them alone.

The ids are the ones on Rules. Every check can be turned off except wide-event and context, because the map sorts entry points into instrumented, partial and dark by them. Leave those entry points out with map.ignore instead.

A check turned off in the config becomes n/a on every entry point, with turned off in evlog.config as its message in --json. The report says what the config changed above the score, and names the setting the gate came from:

evlog.config.ts: error-catalog off, 1 entry point ignored
█▀█ ▀▀█   score /100              checkout · Hono
█▀█  ▀█   ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱    2 entry points scanned
▀▀▀ ▀▀▀   good                    ▆█

 GATE  score 83 meets map.minScore 70 — exit code 0

evlog map --min-score 95 on the same project gates on 95 and says --min-score 95. To turn a check off for one handler rather than the whole project, keep using a disable comment next to the code.

Read logs from another directory

evlog logs reads the logs section, and its flags win the same way.

--format, --verbose, and --limit on evlog map stay flags only. They describe one run, not the project.

Write values the CLI can read

The CLI parses evlog.config.ts and never runs it, so every value under map and logs has to be a literal, a const, or a value imported from a local file. A call, an environment variable, or a value imported from a package stops the command:

logs.limit in evlog.config.ts:14 is computed at runtime
→ Write the value inline, as a const, or import it from a local file

The rest of the file is for the app and can compute anything: a drain, an enrich function, a sampling rate read from process.env. The CLI lists those values without evaluating them.

Share settings with extends

extends takes another config, imported from a local file or from a package. A preset published to npm is an ordinary module whose default export is defineEvlog({ ... }), so a team installs it and extends it:

import { defineEvlog } from 'evlog'
import preset from '@acme/evlog-preset'

export default defineEvlog({
  extends: preset,
  service: 'checkout',
})

The CLI follows the package's exports to the file it ships and reads it the same way, so the preset's map and logs have to be literals too.

Settings merge by kind:

Redaction paths and kept events add up rather than being replaced, so an app that lists its own paths cannot drop the ones the preset redacts.

A config extends one level only. When evlog.preset.ts itself extends a config, extending it fails and names both files:

./evlog.preset extends another config, so evlog.config.ts:6 cannot extend it
→ Extend the config it extends directly, or copy the settings you need into one of the two files

Every setting is then at most one file away from where it applies, and evlog config names that file.

extends takes the config itself, the value the app merges at runtime, so a path string is refused rather than resolved:

extends in evlog.config.ts:4 is the path './evlog.preset', not a config
→ Import the config from that path as base, then set extends: base

Publish a preset for your organization

A preset package is one module and a package.json. Ship it as JavaScript, so every app can bundle it without compiling a dependency, and list evlog as a peer so the preset and the app share one copy:

{
  "name": "@acme/evlog-preset",
  "type": "module",
  "exports": "./index.mjs",
  "peerDependencies": {
    "evlog": ">=2.31.0"
  }
}

import { defineEvlog } from 'evlog'

export default defineEvlog({
  sampling: { rates: { info: 10 } },
  redact: { paths: ['user.email', 'card.number'] },
  map: { minScore: 70 },
})

Every repository that extends it starts from the same redaction, sampling and CI gate. A new rule rolls out as a version bump of the preset, and an app that needs an exception writes it in its own config, where evlog config shows it next to the setting it overrides.

Use the config in your app

The app runs the file, so the values the CLI only lists, a drain, an enrich function, a rate read from process.env, apply there. map and logs are left out. How the file reaches the app depends on the framework:

Nuxt and Nitro load it for you

The module looks the file up the same way the CLI does and bundles it into the server, so import.meta.dev and process.env work in it as they do in server code. Options passed to the module override the file, merged with the extends rules:

export default defineNuxtConfig({
  modules: ['evlog/nuxt'],
  evlog: {
    sampling: { rates: { info: 100 } },
  },
})

This app keeps every info event whatever the file says, and the other rates in the file still apply. evlog config reads these options too. A note under the file name says they override it, and each setting they replace shows the value that wins, the line that sets it, and the value of the file under it:

evlog.config.ts · extends ./evlog.preset → evlog.preset.ts
nuxt.config.ts passes options to the evlog module, and they override this file

Sampling
  trace  0%      default
  debug  0%      evlog.preset.ts:4
  info   100%    nuxt.config.ts:4
         overrides 25 at evlog.config.ts:9
  warn   100%    default
  error  100%    default
  fatal  always  default

Options computed at runtime, like a value read from a function call, keep the note but are not listed, since evlog config reads the files without running them.

The drain, enrich and keep of the file run next to the evlog:drain, evlog:enrich and evlog:emit:keep hooks. A server plugin hooked there keeps working, and an event reaches both drains. A drain wrapped in createDrainPipeline is flushed when the server closes, so the file needs no close hook.

On Nuxt the browser logger also takes enabled, pretty and minLevel from the file. The evlog key in nuxt.config.ts and the NUXT_PUBLIC_EVLOG_* variables still win, so NUXT_PUBLIC_EVLOG_MIN_LEVEL=debug lowers the threshold of a single deployment. The browser reads console and transport from nuxt.config.ts only.

Other apps import it

toLoggerConfig keeps the options initLogger takes, and toMiddlewareOptions keeps the ones a framework middleware takes:

import { Hono } from 'hono'
import { initLogger, toLoggerConfig, toMiddlewareOptions } from 'evlog'
import { evlog, type EvlogVariables } from 'evlog/hono'
import config from '../evlog.config'

initLogger(toLoggerConfig(config))

const app = new Hono<EvlogVariables>()
app.use(evlog(toMiddlewareOptions(config)))

An Eve agent spreads the config into its hook and adds its own options, see Eve.

The evlog/vite plugin does not read the file. Its auto-init is serialized at build time and cannot carry a drain, so import the config where you call initLogger instead.

When the config cannot be read

evlog map and evlog config exit 1 on a config they cannot read, and evlog logs exits 2. evlog doctor reports the same error as a failing config check. Each error carries a code from the CLI's catalog:

A misspelt key is an error rather than a setting quietly ignored:

logs.limt in evlog.config.ts:14 is not a setting; expected dir, limit
→ Use a setting and a value the config reference lists

Next

• Rules: the ids map.rules takes, and what each check expects
• CI: gate a pull request on the score