Observability Score with evlog map

Before changing your logging, inspect which supported entry points meet evlog's logging checks. evlog map reads source files and reports missing context, structured errors, and other recognized patterns. Its score summarizes those static checks, not the percentage of your application that can explain a production failure.

Check the supported scope first

The CLI currently has adapters for Nuxt, Nitro, Next.js, TanStack Start, and Hono. Run it from the application package, not a monorepo root without a detected framework. An unsupported Node.js project cannot be scored by these adapters.

You can scan a supported project without installing evlog in it. However, checks such as wide-event and context recognize evlog conventions. Existing Pino or LogTape instrumentation can receive a low score even when it produces useful logs. Use the report to plan evlog adoption, not to rank logging libraries.

This command inspects the project without writing evlog.map.json. The examples on this page were checked with CLI 0.6.2:

npx @evlog/cli@0.6.2 map --no-write

The scan does not execute handlers or require traffic. It only sees entry points and code patterns its adapter recognizes. Check the detected framework and entry-point count before interpreting the number.

Read a real report

This output comes from the repository's Next.js example at commit 42eb1ab2. It has five detected entry points, two with failed requirements:

█▀█ ▀▀█   score /100              evlog-nextjs-example · Next.js
█▀█   █   ▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▰▱▱▱    5 entry points scanned
▀▀▀   ▀   good                    ▆▆█▁█

COVERAGE
● API handlers       ▰▰▰▰▰▰▰▰▰▱   92  1 of 3 have gaps
● Pages              ▰▰▰▰▰▰▰▰▱▱   80  1 swallows fetch errors
● Money & auth       ▰▰▰▰▰▰▰▰▱▱   75  missing audit trails

FIX FIRST
1. POST   /api/checkout $ — moves money with no audit trail
   app/api/checkout/route.ts:3 · evlog.dev/use-cases/audit/overview
2. PAGE   / — swallows fetch errors — users see a blank page
   app/page.tsx:1 · evlog.dev/learn/lifecycle

✓ Already solid: /api/error · /api/health
▲ 87 → 100 by fixing the 2 above

────────────────────────────
how this score works → evlog.dev/cli/scoring
▸ evlog map --all every entry point · evlog map <file> inspect one
  --min-score 80 CI gate

The 87/100 score is a weighted average of checks on those entries. It does not mean 87% of the application's execution paths are covered. FIX FIRST highlights requirements to inspect, and the projected 100 means those static requirements would pass. It does not prove delivery to a backend or usefulness during an incident.

The Scoring reference owns the weights, aggregation formula, grades, and sensitivity classification. Rules explains what each check recognizes.

Fix one context gap

In a Next.js App Router application with evlog installed, this handler is wrapped for logging but adds no application context:

import { withEvlog } from 'evlog/next'

export const GET = withEvlog(async (request: Request) => {
  const name = new URL(request.url).searchParams.get('name') ?? 'world'
  return Response.json({ message: `Hello ${name}` })
})

Inspect that file directly:

npx @evlog/cli@0.6.2 map app/api/hello/route.ts --no-write

The context requirement fails because the handler has no recognized set() call. Attach a useful decision without recording the user's name:

import { useLogger, withEvlog } from 'evlog/next'

export const GET = withEvlog(async (request: Request) => {
  const log = useLogger()
  const name = new URL(request.url).searchParams.get('name') ?? 'world'
  log.set({ greeting: { personalized: name !== 'world' } })
  return Response.json({ message: `Hello ${name}` })
})

Run the same command again. The context requirement now passes, removing its 15-point penalty. In this isolated example the route moves from 85 to 100. In a larger application the global change depends on all scored entries and their weights.

A passing check establishes that the pattern exists. It does not judge whether greeting.personalized is the field your incident investigation needs. Review the event output and required business fields separately.

Know what a high score leaves untested

• Source patterns do not prove runtime execution, complete error-path coverage, or successful delivery to a backend.
• Sensitivity classification uses imports and route paths. Inspect the reported reasons for money, authentication, or personal-data flags.
• The current CLI can show 100 when no scorable entries are found. An empty scan is no evidence of instrumentation, so inspect the count and scope first.
• Logging through wrappers or abstractions the analyzer does not recognize can produce false positives. Look at the code before applying a suggestion.

A high score is useful for checking agreed conventions alongside runtime tests and sampled production events.

Add a CI gate after reviewing the baseline

Pin the CLI version and keep the analyzed package, configuration, and exclusions consistent. Rule changes can change a score without an application edit.

Commit a reviewed evlog.map.json baseline and use --baseline to detect recognized requirement or score regressions on existing entries. It does not track every context field: removing one set() call may still leave another call that satisfies context. New entries also need review. Add --min-score when you want a floor on the current aggregate score, understanding that an average can hide one weak route.

The CI guide covers exit codes and gate configuration. Use the map reference for command options and report formats.