---
title: "使用 evlog map 的可观测性评分"
description: "根据 evlog 日志规则检查受支持的入口点，了解评分，并在添加 CI 门禁前修复一个具体缺口"
canonical_url: "https://evlog.zhcndoc.com/cli/observability-score"
---
# 使用 evlog map 的可观测性评分

> 根据 evlog 日志规则检查受支持的入口点，了解评分，并在添加 CI 门禁前修复一个具体缺口

在修改日志记录之前，请检查哪些受支持的入口点满足 evlog 的日志检查。`evlog map` 会读取源文件并检查六项要求，包括缺少的上下文和结构化错误。它的评分总结的是这些静态检查。

## 阅读一份真实报告

请从应用程序包中运行它，而不是从未检测到框架的 monorepo 根目录运行。[检查受支持的范围](#check-the-supported-scope)一节列出了支持的框架。此命令会检查项目，但不会写入 `evlog.map.json`。本页面上的示例使用 CLI 0.10.0（`evlog --version`）进行检查：

```bash [Terminal]
npx evlog map --no-write
```

扫描不会执行处理程序，也不要求有流量。它只能看到其适配器能够识别的入口点和代码模式。在解读数字之前，请检查检测到的框架和入口点数量。

此输出来自仓库在提交 `e154fa9c` 时的 Next.js 示例。它检测到了五个入口点，其中两个未通过要求：

<code-collapse>

```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 <file> inspect one
  --min-score 80 CI gate
```

</code-collapse>

当标记为资金或身份验证的路由调用 `log.audit()` 时，`audit` 检查才会通过；[审计日志](https://evlog.zhcndoc.com/use-cases/audit/overview)概览介绍了审计轨迹本身。

87/100 的评分是对四个参与评分的入口点进行加权平均的结果。豁免的 evlog ingest 路由会计入检测到的五个入口点，但会从平均值中排除。它并不意味着应用程序 87% 的执行路径都已覆盖。`FIX FIRST` 会突出显示需要检查的要求，而预计达到的 100 表示这些静态要求将会通过。但这并不能证明日志已交付到后端，或在事故期间有用。

[评分参考](https://evlog.zhcndoc.com/cli/scoring)规定了权重、聚合公式、等级和敏感性分类。[规则](https://evlog.zhcndoc.com/cli/rules)解释了每项检查能够识别的内容。

## 检查受支持的范围

CLI 目前为 Nuxt、Nitro、Next.js、TanStack Start、Hono、Express 和 Fastify 提供适配器。不受支持的 Node.js 项目无法由这些适配器评分。

你可以在不将 evlog 安装到项目中的情况下扫描受支持的项目。不过，`wide-event` 和 `context` 等检查会识别 evlog 约定。即使现有的 Pino 或 LogTape 插桩能够产出有用的日志，也可能获得较低的评分。请使用报告来规划 evlog 的采用，而不是用它来给日志库排名。

扫描不会执行处理程序，也不要求有流量。它只能看到其适配器能够识别的入口点和代码模式。在解读数字之前，请检查上方检测到的框架和入口点数量。

## 修复一个上下文缺口

在安装了 evlog 的 Next.js App Router 应用程序中，此处理程序已包装以进行日志记录，但没有添加应用程序上下文。`@/lib/evlog` 导入来自 `lib/evlog.ts`，你可以按照 [Next.js 指南](https://evlog.zhcndoc.com/integrate/frameworks/nextjs)中的说明，使用 `evlog/next` 的 `createEvlog()` 创建它：

```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}` })
})
```

直接检查该文件：

```bash [Terminal]
npx evlog map app/api/hello/route.ts --no-write
```

`context` 要求未通过，因为处理程序没有已识别的 `set()` 调用。在不记录用户姓名的情况下，附加一个有用的决策：

```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}` })
})
```

再次运行相同的命令。现在 `context` 要求通过，移除了 15 分的扣分。在这个独立示例中，路由评分从 85 提升到 100。在更大的应用程序中，全局变化取决于所有参与评分的入口点及其权重。

通过检查只能证明该模式存在。它无法判断 `greeting.personalized` 是否是事故调查所需的字段。请分别检查事件输出和所需的业务字段。

## 了解高评分未覆盖的内容

- 源代码模式无法证明运行时执行、完整的错误路径覆盖，或成功交付到后端。
- 敏感性分类使用导入和路由路径。个人数据标记需要同一文件中出现 `email` 或 `phone` 等字段名，以及 `create` 或 `update` 等写入调用。请检查报告的原因，了解资金、身份验证或个人数据标记。
- 找不到可评分入口点时，人类报告不会显示评分，只会显示 `--` 和“没有可扫描内容”。JSON 输出仍会在 `map.score` 旁将其设置为 100，并将 `grade` 设置为 `"unscored"`，因此应读取等级而不是数字。空扫描不能证明存在插桩，因此请首先检查范围。
- 通过分析器无法识别的包装器或抽象层进行日志记录，可能会产生误报。在应用建议之前，请查看代码。

高评分有助于结合运行时测试和[抽样的生产事件](https://evlog.zhcndoc.com/learn/sampling)检查既定约定。

## 审查基线后添加 CI 门禁

固定 CLI 版本，并保持分析的软件包以及 `evlog.config.ts` 中的 [`map.ignore` 和 `map.rules` 设置](https://evlog.zhcndoc.com/cli/config)一致。规则变化可能会在应用程序没有修改的情况下改变评分。

提交经过审查的 `evlog.map.json` 基线，并使用 `--baseline` 检测现有入口点上已识别要求或评分的回归。直接使用 `--baseline` 会读取工作树中的 `evlog.map.json`，因此提交重新生成的 map 的拉取请求会与自身比较。默认浅克隆（fetch depth 1）只会获取触发运行的提交，因此基准分支不存在，必须先获取；完整历史的 checkout 已经包含它，可以跳过获取。在拉取请求中，应改为与目标分支比较。目标分支必须已经包含经过审查的 `evlog.map.json`；如果没有，该命令会退出 1 并显示“origin/<base-branch>

中没有 evlog.map.json，棘轮需要一个已提交的 map”，这属于配置缺口而不是回退：

</base-branch>



```bash [Terminal]
git fetch origin <base-branch>
npx evlog map --baseline git:origin/<base-branch>
```

将 `<base-branch>` 替换为拉取请求的目标分支。

相对于基线的回退，或低于 `--min-score` 的评分，都会退出 1 并使作业失败。`--baseline` 不会跟踪每个上下文字段：移除一个 `set()` 调用后，只要仍有另一个调用满足 `context`，就可能不会被检测到。新入口点也需要审查。当你希望为当前聚合评分设置下限时，添加 `--min-score`，但要注意平均值可能会掩盖某个较弱的路由。

[CI 指南](https://evlog.zhcndoc.com/cli/ci)介绍退出代码和门禁配置。有关命令选项和报告格式，请参阅 [map 参考](https://evlog.zhcndoc.com/cli/map)。

---

- [evlog map](https://evlog.zhcndoc.com/cli/map)
- [评分](https://evlog.zhcndoc.com/cli/scoring)


## Sitemap

See the full [sitemap](https://evlog.zhcndoc.com/sitemap.md) for all pages.