---
title: "evlog logs"
description: "Read the wide events your app wrote to .evlog/logs from the terminal — the latest requests, the failures, the slowest, or one request in full."
canonical_url: "https://www.evlog.dev/cli/logs"
---
# evlog logs

> Read the wide events your app wrote to .evlog/logs from the terminal — the latest requests, the failures, the slowest, or one request in full.

`evlog logs` reads the events the [file system drain](https://www.evlog.dev/integrate/adapters/self-hosted/fs) wrote and shows them the way you would want to read them: one line per request, the thing that mattered at the end of it, and one request in full when you have its id. It reads files; it never touches the app.

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

The newest event is at the bottom, like `tail`. Nothing is written: the fs drain writes on every request and this reads what it wrote, both the compact and the `pretty: true` layout, across the dated files. The files are read one event at a time, so memory does not grow with the log: a view keeps the `--limit` events it shows, and `stats` one duration per event for the percentiles.

## Five views

<table>
<thead>
  <tr>
    <th>
      Command
    </th>
    
    <th>
      Shows
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        evlog logs
      </code>
    </td>
    
    <td>
      The last 50 events, oldest first
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs errors
      </code>
    </td>
    
    <td>
      Events that failed: a <code>
        5xx
      </code>
      
       status, an <code>
        error
      </code>
      
       or <code>
        fatal
      </code>
      
       level, or an <code>
        error
      </code>
      
       block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs slow
      </code>
    </td>
    
    <td>
      Events over 500ms, worst first (<code>
        --over 1s
      </code>
      
       to move the bar)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs <requestId>
      </code>
    </td>
    
    <td>
      Every event carrying that id, in full: request, error with <code>
        why
      </code>
      
       and <code>
        fix
      </code>
      
      , audit record, then the business fields. The first block of a UUID is enough
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evlog logs stats
      </code>
    </td>
    
    <td>
      The shape of the traffic: per route, count, errors, p50 and p95, routes with the most errors first; then counts by status class and by level
    </td>
  </tr>
</tbody>
</table>

## Filters

Filters compose with any view.

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      What it does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --since <when>
      </code>
    </td>
    
    <td>
      Only events after: a duration back from now (<code>
        15m
      </code>
      
      , <code>
        2h
      </code>
      
      , <code>
        3d
      </code>
      
      ) or a date (<code>
        2026-10-01
      </code>
      
      , <code>
        2026-10-01T09:00
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --until <when>
      </code>
    </td>
    
    <td>
      Only events before, same spellings
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --level <a,b>
      </code>
    </td>
    
    <td>
      Only these levels: <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>
      Only requests on this exact path
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --status <n>
      </code>
    </td>
    
    <td>
      Only this status (<code>
        404
      </code>
      
      ) or class (<code>
        4xx
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --where <clause>
      </code>
    </td>
    
    <td>
      Only events where a field matches, see below; repeat the flag for several clauses, all must hold
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --over <duration>
      </code>
    </td>
    
    <td>
      For <code>
        slow
      </code>
      
      : what a request has to exceed (default <code>
        500ms
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --limit <n>
      </code>
    </td>
    
    <td>
      Most events to show (default 50)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --ask <question>
      </code>
    </td>
    
    <td>
      Rank the selected events by a yes/no question a decision model answers, see below
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dry-run
      </code>
    </td>
    
    <td>
      With <code>
        --ask
      </code>
      
      : print how many model calls and input tokens it would take, and send nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dir <path>
      </code>
    </td>
    
    <td>
      Read another directory (default: the project's <code>
        .evlog/logs
      </code>
      
      ; in a workspace with no logs at the root, every <code>
        apps/*/.evlog/logs
      </code>
      
       and the like, merged by time with the app in a column)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --url <endpoint>
      </code>
    </td>
    
    <td>
      Read the <a href="https://www.evlog.dev/integrate/adapters/self-hosted/memory">
        memory drain
      </a>
      
      's dev endpoint instead of files: a JSON array of events, or <code>
        { "events": [...] }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        -f
      </code>
      
      , <code>
        --follow
      </code>
    </td>
    
    <td>
      Keep reading as the app writes, like <code>
        tail -f
      </code>
      
      ; <code>
        Ctrl-C
      </code>
      
       stops
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      The events as JSON on stdout
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cwd <dir>
      </code>
    </td>
    
    <td>
      Another project in the workspace
    </td>
  </tr>
</tbody>
</table>

A time, level, status or limit that cannot be read stops the command (exit 2) rather than silently widening the query.

`--dir` and `--limit` can be set once for the project in [`evlog.config.ts`](https://www.evlog.dev/cli/config), as `logs.dir` and `logs.limit`. The flag wins when both are set.

```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`: any field on the event

A clause is a dotted field, an operator, and a value. Numbers compare as numbers, everything else as text, and the field can sit anywhere in the event, which is the point of a wide event: the business fields are there to be queried.

A value is a number when it spells one exactly: `5000`, `-3`, `12.5`. Leading zeros, an exponent, or more digits than a 64-bit float holds keep it as text, so `zip=00123` and a 19-digit id match only themselves. The same reading applies to a field that arrived as text. `>`, `>=`, `<` and `<=` against a number never match a field that is not one.

<table>
<thead>
  <tr>
    <th>
      Clause
    </th>
    
    <th>
      Matches when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        user.id=usr_42
      </code>
    </td>
    
    <td>
      the field equals the value (<code>
        true
      </code>
      
      /<code>
        false
      </code>
      
       and numbers are read as such)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audit.outcome!=success
      </code>
    </td>
    
    <td>
      the field differs
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payment.amount>5000
      </code>
    </td>
    
    <td>
      greater; also <code>
        >=
      </code>
      
      , <code>
        <
      </code>
      
      , <code>
        <=
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        error.message~declined
      </code>
    </td>
    
    <td>
      the field matches the regular expression, case-insensitive; an object is matched as JSON
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audit
      </code>
    </td>
    
    <td>
      the field is present
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        !error
      </code>
    </td>
    
    <td>
      the field is absent
    </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'
```

Quote the whole clause whenever it carries `>`, `<` or `!`, which the shell reads as redirection or history before `evlog` ever sees them, and whenever the value has a space: `'payment.amount>5000'`, `'!error'`, `'error.data.why~card declined'`.

## Ask a question no filter can

Some questions are not a field. "The customer tried to pay but did not end up with a confirmed order" covers a declined card (a `402` with an error), a payment taken without an order (a `200` with no `order`), and the shapes nobody has written a `--where` for yet: a filter needs one clause per case you already know. `--ask` puts the question to a decision model and ranks the events by the probability that the answer is yes:

```bash [Terminal]
evlog logs --path /api/checkout --ask 'The customer tried to pay but did not end up with a confirmed order'
```

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

ranked by P(yes) · The customer tried to pay but did not end up with a confirmed order

0.96  10:05:00  POST   /api/checkout                          402    412ms  ✗ Error: Payment processing failed · Card declined by issuer
0.81  10:10:00  POST   /api/checkout                          200    380ms  cart.items=2 payment.provider=stripe
0.03  10:20:00  POST   /api/checkout                          200    290ms  cart.items=1 order.id=ord_9

model calls 3 · input tokens 1429
```

The filters run first and the question ranks what is left, so the model sees at most `--limit` events (50 by default). Three things keep a large `--limit` affordable:

- **Each event is cut down before it is sent.** Every string stops at 256 characters, every array at 10 items and every stack at 3 lines, each cut saying how much it left out. No field is dropped, so a request body or an agent turn's tool list no longer sets the bill: for the agent turns in the CLI's scale test, with 3 to 30 tool calls each, the state sent is under a third of the event.
- **Events that differ only in what is per-event by construction share one call.** The timestamp, the request id, the idempotency key, and the trace, span and parent span ids are left out of the comparison, and durations and token counts are floored to two significant figures, so 412ms and 419ms match and 412ms and 490ms do not. Every other value has to match, ids included, so a question that names a user or an order is never answered from another one's event. A thousand health checks cost a handful of calls; a thousand checkouts, each with its own order id, cost a thousand.
- **--dry-run counts first.** It prints the events, the calls after grouping and the input tokens, and sends nothing:

```bash [Terminal]
evlog logs --limit 10000 --ask 'The customer tried to pay but did not end up with a confirmed order' --dry-run
```

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

The customer tried to pay but did not end up with a confirmed order

would judge 10000 events in 8457 model calls, about 6765112 input tokens. Nothing was sent
```

The token count is fitted to what `typesafe-ai/jev` reports, and lands within 1% of it on the runs it was fitted to; another model tokenizes differently. The calls run one at a time, so a run's length follows the call count: 100 calls took 18 seconds against Jev.

Read the result as a ranking, not a verdict. On a day of synthetic shop events, Jev put every declined card and every checkout that took payment without creating an order above the rest, but gave the second kind 0.06 to 0.20 rather than a yes: a `payment.status` of `captured` reads as success. Open the top of the list rather than filtering on a probability.

Each event leaves your machine cut down as above, less any `signals` column it already carries, so narrow with `--path`, `--since` or `--where` before asking about anything sensitive.

It needs `@evlog/signals` 0.2.0 or later and `ai` 7 from 7.0.130 (`>=7.0.130 <8`) installed in the project beside `@evlog/cli` (`pnpm add -D @evlog/cli @evlog/signals 'ai@^7.0.130'`, then `pnpm evlog logs --ask …`): the CLI loads them from where it is installed, so a copy fetched by `npx` or `bunx` does not find them. It also needs a key for the model, `AI_GATEWAY_API_KEY` through Vercel AI Gateway. `--model` picks the decision model by its gateway id (`--model liquid/d1`); without it the question goes to the `@evlog/signals` default, `typesafe-ai/jev` today. A failed call, or an event still over the 100000 characters of JSON that `@evlog/signals` sends once cut down, stops the run with the reason rather than ranking with holes in it; an event the model declines to answer is left out. `--ask` does not combine with `--follow` or `stats`. `--json` carries `answers`, each a `{ probability, event }`, and `shared`, the events that took another event's verdict, in place of `events`; with `--dry-run` it carries `estimate` instead.

## For agents

`--json` returns one envelope: the directory, the view, how many events matched, and the events shown.

```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` carries `stats` (`total`, `errors`, `byRoute`, `byStatus`, `byLevel`) in place of `events`. With `--follow --json`, each new event is one JSON line on stdout, since a stream has no end. The [`analyze-logs` skill](https://www.evlog.dev/reference/agent-skills) calls `evlog logs` first and falls back to reading the files only when the CLI is not available.

## A workspace, and a running app

Run from a monorepo root with no `.evlog/logs` of its own, it reads every app that has one (`apps/*`, `packages/*`, `examples/*`, `services/*`), merges the events by time, and shows the app in a column. `--cwd apps/web` reads one app; `--dir` reads one directory.

An app on the [memory drain](https://www.evlog.dev/integrate/adapters/self-hosted/memory) (Cloudflare Workers, where there is no file system) has no files to read, but it can expose `readMemoryLogs()` on a dev route. Point `--url` at it; every view and filter works the same, and `-f` polls it once a second. A failed poll is a gap rather than the end, since the app restarting under a follower is normal; if the endpoint stays quiet the run says so once and keeps trying.

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

## What it will not do

- **It reads local files and a dev endpoint.** A remote drain (Axiom, Datadog, …) has its own query language and UI; this command does not wrap them.

## Next

- [File system drain](https://www.evlog.dev/integrate/adapters/self-hosted/fs): what writes the files, rotation, `pretty`
- [`evlog map`](https://www.evlog.dev/cli/map): which handlers emit a wide event at all

---

- [File system adapter](https://www.evlog.dev/integrate/adapters/self-hosted/fs)


## Sitemap

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