---
title: "evlog logs"
description: "在终端读取应用写入 .evlog/logs 的宽事件：最新请求、失败请求、最慢请求，或完整查看某个请求。"
canonical_url: "https://evlog.zhcndoc.com/cli/logs"
---
# evlog logs

> 在终端读取应用写入 .evlog/logs 的宽事件：最新请求、失败请求、最慢请求，或完整查看某个请求。

`evlog logs` 会读取[文件系统 drain](https://evlog.zhcndoc.com/integrate/adapters/self-hosted/fs)写入的事件，并按你希望的方式展示：每个请求一行，在末尾显示最重要的信息；如果你有请求 ID，还可以完整查看一个请求。它只读取文件，不会触碰应用。

```bash [Terminal]
evlog logs
```

```text [Output]
6 events · .evlog/logs

08:00:00  GET    /api/health                                 200      2ms
10:00:00  POST   /api/checkout                               402    412ms  ✗ Error: Payment processing failed · Card declined by issuer
10:30:00  GET    /api/reports                                200    1.2s   report.id=r-1
11:00:00  POST   /api/refund                                 200     80ms  audit billing.refund user:usr_42 → invoice:inv_1 success
11:30:00  GET    /api/items                                  500     30ms
11:45:00  GET    /api/items                                  warn   700ms  user.id=usr_7

evlog logs errors — the 2 that failed · evlog logs <requestId> — one request in full · evlog logs slow — worst first
```

最新事件位于底部，就像 `tail` 一样。此命令不会写入任何内容：fs drain 会在每个请求时写入，而它读取这些写入内容，包括紧凑格式和 `pretty: true` 布局，并跨日期文件读取。

## 五种视图

<table>
<thead>
  <tr>
    <th>
      命令
    </th>
    
    <th>
      内容
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        evlog logs
      </code>
    </td>
    
    <td>
      最近 50 个事件，按时间从旧到新
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs errors
      </code>
    </td>
    
    <td>
      失败事件：<code>
        5xx
      </code>
      
       状态、<code>
        error
      </code>
      
       或 <code>
        fatal
      </code>
      
       级别，或包含 <code>
        error
      </code>
      
       块的事件
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs slow
      </code>
    </td>
    
    <td>
      超过 500ms 的事件，最慢的排在前面（使用 <code>
        --over 1s
      </code>
      
       调整阈值）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs <requestId>
      </code>
    </td>
    
    <td>
      完整显示携带该 ID 的每个事件：请求、带有 <code>
        why
      </code>
      
       和 <code>
        fix
      </code>
      
       的错误、审计记录，然后是业务字段。UUID 的第一段即可
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs stats
      </code>
    </td>
    
    <td>
      流量形态：按路由统计数量、错误、p50 和 p95，错误最多的路由排在前面；然后按状态类别和级别统计
    </td>
  </tr>
</tbody>
</table>

## 过滤器

过滤器可以与任何视图组合。

<table>
<thead>
  <tr>
    <th>
      标志
    </th>
    
    <th>
      作用
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --since <when>
      </code>
    </td>
    
    <td>
      只显示此时间之后的事件：从现在往前的时长（<code>
        15m
      </code>
      
      、<code>
        2h
      </code>
      
      、<code>
        3d
      </code>
      
      ）或日期（<code>
        2026-10-01
      </code>
      
      、<code>
        2026-10-01T09:00
      </code>
      
      ）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --until <when>
      </code>
    </td>
    
    <td>
      只显示此时间之前的事件，写法相同
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --level <a,b>
      </code>
    </td>
    
    <td>
      只显示这些级别：<code>
        trace
      </code>
      
      、<code>
        debug
      </code>
      
      、<code>
        info
      </code>
      
      、<code>
        warn
      </code>
      
      、<code>
        error
      </code>
      
      、<code>
        fatal
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --path <path>
      </code>
    </td>
    
    <td>
      只显示此精确路径上的请求
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --status <n>
      </code>
    </td>
    
    <td>
      只显示此状态（<code>
        404
      </code>
      
      ）或状态类别（<code>
        4xx
      </code>
      
      ）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --where <clause>
      </code>
    </td>
    
    <td>
      只显示字段匹配的事件，见下文；多个条件可以重复使用该标志，并且必须全部满足
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --over <duration>
      </code>
    </td>
    
    <td>
      对于 <code>
        slow
      </code>
      
      ：请求必须超过的时长（默认 <code>
        500ms
      </code>
      
      ）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --limit <n>
      </code>
    </td>
    
    <td>
      最多显示的事件数（默认 50）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dir <path>
      </code>
    </td>
    
    <td>
      读取其他目录（默认：项目的 <code>
        .evlog/logs
      </code>
      
      ；如果工作区根目录没有日志，则读取所有类似 <code>
        apps/*/.evlog/logs
      </code>
      
       的目录，按时间合并并在一列中显示应用）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --url <endpoint>
      </code>
    </td>
    
    <td>
      不读取文件，而读取<a href="https://evlog.zhcndoc.com/integrate/adapters/self-hosted/memory">
        memory drain
      </a>
      
      的开发端点：事件 JSON 数组，或 <code>
        { "events": [...] }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -f
      </code>
      
      、<code>
        --follow
      </code>
    </td>
    
    <td>
      应用写入时持续读取，类似 <code>
        tail -f
      </code>
      
      ；<code>
        Ctrl-C
      </code>
      
       停止
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      将事件以 JSON 输出到 stdout
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cwd <dir>
      </code>
    </td>
    
    <td>
      工作区中的另一个项目
    </td>
  </tr>
</tbody>
</table>

无法解析的时间、级别、状态或限制会停止命令（退出码 2），而不会静默扩大查询范围。

可以在项目的 [`evlog.config.ts`](https://evlog.zhcndoc.com/cli/config) 中使用 `logs.dir` 和 `logs.limit` 一次设置 `--dir` 和 `--limit`。两者同时设置时，以标志为准。

```bash [Terminal]
evlog logs errors --since 1h
evlog logs slow --over 2s --path /api/reports
evlog logs --status 5xx --level error,fatal --limit 20
evlog logs -f --path /api/checkout
```

### `--where`：事件中的任意字段

条件由点号字段、运算符和值组成。数字按数字比较，其他内容按文本比较；字段可以位于事件的任何位置，这正是宽事件的意义：业务字段可以直接查询。

<table>
<thead>
  <tr>
    <th>
      条件
    </th>
    
    <th>
      匹配条件
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        user.id=usr_42
      </code>
    </td>
    
    <td>
      字段等于该值（<code>
        true
      </code>
      
      /<code>
        false
      </code>
      
       和数字会按对应类型读取）
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audit.outcome!=success
      </code>
    </td>
    
    <td>
      字段不等于该值
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment.amount>5000
      </code>
    </td>
    
    <td>
      大于；也支持 <code>
        >=
      </code>
      
      、<code>
        <
      </code>
      
      、<code>
        <=
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error.message~declined
      </code>
    </td>
    
    <td>
      字段匹配正则表达式，不区分大小写；对象会按 JSON 匹配
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audit
      </code>
    </td>
    
    <td>
      字段存在
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        !error
      </code>
    </td>
    
    <td>
      字段不存在
    </td>
  </tr>
</tbody>
</table>

```bash [Terminal]
evlog logs --where 'payment.amount>5000' --where audit.outcome=failure
evlog logs errors --where 'error.data.why~card declined'
evlog logs stats --where user.plan=pro
evlog logs -f --where '!error' --where 'durationMs>1000'
```

只要条件包含 `>`、`<` 或 `!`，就应将整个条件加引号，因为 shell 会在 `evlog` 看到它之前把它当作重定向或历史展开；值包含空格时也要加引号，例如：`'payment.amount>5000'`、`'!error'`、`'error.data.why~card declined'`。

## 面向 agents

`--json` 返回一个封装对象：目录、视图、匹配的事件数量，以及显示的事件。

```bash [Terminal]
evlog logs errors --since 30m --json
```

```json
{
  "schemaVersion": 2,
  "dir": "/app/.evlog/logs",
  "view": "errors",
  "count": 2,
  "matched": 2,
  "events": [ { "timestamp": "…", "path": "/api/checkout", "status": 402, "error": { "data": { "why": "…", "fix": "…" } } } ]
}
```

`stats --json` 用 `stats`（`total`、`errors`、`byRoute`、`byStatus`、`byLevel`）替代 `events`。使用 `--follow --json` 时，每个新事件都会作为一行 JSON 输出到 stdout，因为流没有终点。[`analyze-logs` 技能](https://evlog.zhcndoc.com/reference/agent-skills) 会先调用 `evlog logs`，仅在 CLI 不可用时才回退到读取文件。

## 工作区与运行中的应用

从没有自己的 `.evlog/logs` 的单仓库根目录运行时，它会读取所有拥有该目录的应用（`apps/*`、`packages/*`、`examples/*`、`services/*`），按时间合并事件，并在一列中显示应用。`--cwd apps/web` 读取一个应用；`--dir` 读取一个目录。

使用[memory drain](https://evlog.zhcndoc.com/integrate/adapters/self-hosted/memory)的应用（例如没有文件系统的 Cloudflare Workers）没有可读取的文件，但可以在开发路由上暴露 `readMemoryLogs()`。将 `--url` 指向它；每种视图和过滤器都以相同方式工作，`-f` 每秒轮询一次。轮询失败会被视为空缺而不是结束，因为 follower 下的应用重启是正常情况；如果端点持续没有响应，命令会提示一次并继续尝试。

```bash [Terminal]
evlog logs errors --url http://localhost:8787/_evlog/logs
```

## 它不会做什么

- **它读取本地文件和开发端点。**远程 drain（Axiom、Datadog 等）有自己的查询语言和 UI；此命令不会封装它们。

## 下一步

- [文件系统 drain](https://evlog.zhcndoc.com/integrate/adapters/self-hosted/fs)：文件如何写入、轮换以及 `pretty`
- [`evlog map`](https://evlog.zhcndoc.com/cli/map)：哪些处理器会发出宽事件

---

- [文件系统适配器](https://evlog.zhcndoc.com/integrate/adapters/self-hosted/fs)


## Sitemap

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