--- title: "Observability Score with evlog map" description: "Inspect supported entry points against evlog logging rules, understand the score, and fix a concrete gap before adding a CI gate." canonical_url: "https://www.evlog.dev/cli/observability-score" --- # Observability Score with evlog map > Inspect supported entry points against evlog logging rules, understand the score, and fix a concrete gap before adding a CI gate. Before changing your logging, inspect which supported entry points meet evlog's logging checks. `evlog map` reads source files and checks six requirements, including missing context and structured errors. Its score summarizes those static checks. ## Read a real report Run it from the application package, not a monorepo root without a detected framework. The [supported scope](#check-the-supported-scope) section lists the frameworks. This command inspects the project without writing `evlog.map.json`. The examples on this page were checked with CLI 0.10.0 (`evlog --version`): ```bash [Terminal] pnpm dlx evlog map --no-write ``` This output comes from the repository's Next.js example at commit `e154fa9c`. It has five detected entry points, two with failed requirements: ```text [evlog map] evlog map v0.10.0 ──────────────────────────── █▀█ ▀▀█ 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 inspect one --min-score 80 CI gate ``` The `audit` check passes when a route flagged for money or auth calls `log.audit()`, and the [Audit logs](https://www.evlog.dev/use-cases/audit/overview) overview covers the trail itself. The 87/100 score is a weighted average over the four scored entry points. The exempt evlog ingest route is counted in the five scanned but left out of the average. 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](https://www.evlog.dev/cli/scoring) owns the weights, aggregation formula, grades, and sensitivity classification. [Rules](https://www.evlog.dev/cli/rules) explains what each check recognizes. ## Check the supported scope The CLI currently has adapters for Nuxt, Nitro, Next.js, TanStack Start, Hono, Express, and Fastify. 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. The scan does not execute handlers or require traffic. It only sees entry points and code patterns its adapter recognizes. Before you act on the number, check the detected framework and entry-point count above. ## 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. The `@/lib/evlog` import comes from `lib/evlog.ts`, which you create with `createEvlog()` from `evlog/next`, as the [Next.js guide](https://www.evlog.dev/integrate/frameworks/nextjs) shows: ```typescript [app/api/hello/route.ts, before] import { withEvlog } from '@/lib/evlog' 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: ```bash [Terminal] pnpm dlx evlog 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: ```typescript [app/api/hello/route.ts, after] import { useLogger, withEvlog } from '@/lib/evlog' 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 or complete error-path coverage. - Money and authentication flags come from imports and route paths. The personal-data flag needs a field name such as `email` or `phone` and a write call such as `create` or `update` in the same file. Inspect the reported reasons for money, authentication, or personal-data flags. - With no scorable entry points, the human report shows no score, only `--` and "nothing to scan". The JSON output still sets `map.score` to 100, next to `grade: "unscored"`, so read the grade, not the number. An empty scan is no evidence of instrumentation, so inspect the 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](https://www.evlog.dev/learn/sampling). ## Add a CI gate after reviewing the baseline Pin the CLI version and keep the analyzed package and the [`map.ignore` and `map.rules` settings](https://www.evlog.dev/cli/config) in `evlog.config.ts` 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. A bare `--baseline` reads the working-tree `evlog.map.json`, so a pull request that commits a regenerated map is compared with itself. With the default shallow checkout (fetch depth 1), the checkout fetches only the commit that triggered the run, so the base branch is absent and must be fetched first, while a full-history checkout already has it and can skip the fetch. On a pull request, compare against the base branch instead. The base branch must already contain a reviewed `evlog.map.json`, and without one the command exits 1 with "No evlog.map.json in origin/ , and the ratchet needs a committed map", which is a setup gap rather than a regression: ```bash [Terminal] git fetch origin pnpm dlx evlog map --baseline git:origin/ ``` Replace `` with the branch the pull request targets. A regression against the baseline, or a score under `--min-score`, exits 1 and fails the job. `--baseline` 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](https://www.evlog.dev/cli/ci) covers exit codes and gate configuration. Use the [map reference](https://www.evlog.dev/cli/map) for command options and report formats. --- - [evlog map](https://www.evlog.dev/cli/map) - [Scoring](https://www.evlog.dev/cli/scoring) ## Sitemap See the full [sitemap](https://www.evlog.dev/sitemap.md) for all pages.