---
title: "What's coming in evlog 3"
description: "Every breaking change in evlog 3, who it affects, and what you can switch on evlog 2 today so the upgrade leaves nothing to change."
canonical_url: "https://www.evlog.dev/reference/migrate-v3"
---
# What's coming in evlog 3

> Every breaking change in evlog 3, who it affects, and what you can switch on evlog 2 today so the upgrade leaves nothing to change.

evlog 3 removes the APIs deprecated in 2.x, changes a few defaults, and raises the Node.js floor to 22. It is in beta, and evlog 3.0.0 is planned for January 18, 2027. This page lists every breaking change merged for it so far. When 3.0 is released, the full migration guide replaces this page at the same address, with the same sections.

Most removed APIs already have their replacement in evlog 2. Switch to it now, and the upgrade leaves nothing to change for that entry. Each section below says whether you can.

## Find what affects your app

evlog 2 prints a warning in development the first time your code uses most of the APIs that evlog 3 removes, or relies on a default that evlog 3 changes. Each warning names the replacement and links to its section on this page:

```txt
[evlog/posthog] createPostHogEventsDrain() is deprecated and removed in v3. Use createPostHogDrain({ mode: 'events' }). See https://www.evlog.dev/reference/migrate-v3#posthog-events-drain-removed
```

A warning prints once per process, through `console.warn`, and never reaches your drains. It is silent when `NODE_ENV` is `production` or `test`, under Vitest and Jest, and when `EVLOG_NO_DEPRECATION_WARNINGS` is `1` or `true`.

Some changes cannot warn: a field renamed in the logged event, a type, the Node.js version. The [checklist](#checklist) says which ones do.

## Try the beta

The beta is published on the `beta` tag. `@evlog/cli` 1.0 ships alongside it.

<code-group>

```bash [pnpm]
pnpm add evlog@beta
```

```bash [bun]
bun add evlog@beta
```

```bash [yarn]
yarn add evlog@beta
```

```bash [npm]
npm install evlog@beta
```

</code-group>

Report what breaks in [GitHub issues](https://github.com/evloghq/evlog/issues).

## Removed

APIs that are deprecated in evlog 2 and no longer exist in evlog 3.

### Browser entry removed

**Who:** projects that import from the deprecated `evlog/browser` entry.

The entry re-exports `evlog/http` under other names. The types follow the rename: `BrowserDrainConfig` is `HttpDrainConfig`, and `BrowserLogDrainOptions` is `HttpLogDrainOptions`.

```diff
- import { createBrowserDrain, createBrowserLogDrain } from 'evlog/browser'
+ import { createHttpDrain, createHttpLogDrain } from 'evlog/http'
```

**On evlog 2:** switch now. `evlog/http` exports the same functions.

### Credential aliases removed

**Who:** projects that pass `token` to the Axiom drain or `sourceToken` to the Better Stack drain, set the matching environment variables, or set `evlog.axiom.token` in the Nuxt module.

In evlog 3 the drains and the Nuxt module read the key from `apiKey` only. A project that sets only the old name has no key, so the drain logs a missing-key error and sends nothing. `applyDeprecatedAlias` is no longer exported from `evlog/toolkit`.

<table>
<thead>
  <tr>
    <th>
      Removed
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Axiom <code>
        token
      </code>
      
       option
    </td>
    
    <td>
      <code>
        apiKey
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AXIOM_TOKEN
      </code>
      
       / <code>
        NUXT_AXIOM_TOKEN
      </code>
    </td>
    
    <td>
      <code>
        AXIOM_API_KEY
      </code>
      
       / <code>
        NUXT_AXIOM_API_KEY
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Better Stack <code>
        sourceToken
      </code>
      
       option
    </td>
    
    <td>
      <code>
        apiKey
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BETTER_STACK_SOURCE_TOKEN
      </code>
      
       / <code>
        NUXT_BETTER_STACK_SOURCE_TOKEN
      </code>
    </td>
    
    <td>
      <code>
        BETTER_STACK_API_KEY
      </code>
      
       / <code>
        NUXT_BETTER_STACK_API_KEY
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Nuxt <code>
        evlog.axiom.token
      </code>
    </td>
    
    <td>
      <code>
        evlog.axiom.apiKey
      </code>
    </td>
  </tr>
</tbody>
</table>

```ts
// before
createAxiomDrain({ token: process.env.AXIOM_TOKEN, dataset: 'logs' })
createBetterStackDrain({ sourceToken: process.env.BETTER_STACK_SOURCE_TOKEN })

// after
createAxiomDrain({ apiKey: process.env.AXIOM_API_KEY, dataset: 'logs' })
createBetterStackDrain({ apiKey: process.env.BETTER_STACK_API_KEY })
```

**On evlog 2:** switch now, in your code and in the environment of every deployment. evlog 2 reads every new name.

### PostHog events drain removed

**Who:** projects that call `createPostHogEventsDrain()` or import `PostHogEventsConfig`.

Use the main drain in events mode, which takes the same options. `sendToPostHogEvents()` and `sendBatchToPostHogEvents()` are unchanged.

```diff
- import { createPostHogEventsDrain } from 'evlog/posthog'
- initLogger({ drain: createPostHogEventsDrain({ eventName: 'server_request' }) })
+ import { createPostHogDrain } from 'evlog/posthog'
+ initLogger({ drain: createPostHogDrain({ mode: 'events', eventName: 'server_request' }) })
```

**On evlog 2:** switch now. Use `PostHogConfig` where you imported `PostHogEventsConfig`.

### Logger storage moved

**Who:** custom framework integrations and drains that import `createLoggerStorage` from `evlog/toolkit`.

`createLoggerStorage` is exported from `evlog/toolkit/storage` only, so the main toolkit no longer pulls in `node:async_hooks` and integrations built on it stay edge-safe.

```diff
- import { createLoggerStorage, defineFrameworkIntegration } from 'evlog/toolkit'
+ import { defineFrameworkIntegration } from 'evlog/toolkit'
+ import { createLoggerStorage } from 'evlog/toolkit/storage'
```

**On evlog 2:** switch now. `evlog/toolkit/storage` exports the same function.

### eve moves to @evlog/eve

**Who:** every eve agent that imports `evlog/eve`.

The `evlog/eve` subpath is removed. eve 1.0 mounts packages as [extensions](https://eve.dev/docs/extensions), and evlog for eve becomes one: `@evlog/eve`, which requires eve 1.0 and evlog 3.

<table>
<thead>
  <tr>
    <th>
      evlog 2
    </th>
    
    <th>
      evlog 3
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        agent/hooks/evlog.ts
      </code>
      
       exporting <code>
        defineEvlogHook(config)
      </code>
      
       from <code>
        evlog/eve
      </code>
    </td>
    
    <td>
      <code>
        agent/extensions/evlog.ts
      </code>
      
       exporting <code>
        evlog(config)
      </code>
      
       from <code>
        @evlog/eve
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        useLogger
      </code>
      
       from <code>
        evlog/eve
      </code>
    </td>
    
    <td>
      <code>
        useLogger
      </code>
      
       from <code>
        @evlog/eve/logger
      </code>
    </td>
  </tr>
</tbody>
</table>

`defineEvlogInstrumentation` and `evlogRuntimeContext` are removed with no replacement, and so are the `message`, `redactMessage`, `sessionEvent`, `subagentEvents`, `enrichTurn`, `cost`, `model` and `maxSessions` options. The turn event also changes: its AI fields move under [`gen_ai`](#ai-fields-renamed-to-genai-conventions), its `path` is `/agents/<agent>/turns`, and its `requestId` is `sessionId:turnId`.

**On evlog 2:** nothing to switch. `@evlog/eve` only runs on evlog 3, so the agent moves when you upgrade both packages and eve together.

### Error status fields

**Who:** code that reads `statusCode`, `statusText` or `statusMessage` on an `EvlogError`, and drains or saved queries that read those fields from logged events.

The three getters are removed. Read `status` for the HTTP status and `message` for the text. Errors thrown by h3 and Nuxt keep their own `statusCode`, and evlog still reads it from them.

```diff
const error = createError({ message: 'Payment failed', status: 402 })
-error.statusCode    // 402
-error.statusMessage // 'Payment failed'
+error.status        // 402
+error.message       // 'Payment failed'
```

A logged error also stops carrying them:

```diff
"error": {
   "name": "EvlogError",
   "message": "Payment failed",
   "stack": "...",
-  "statusCode": 402,
-  "statusText": "Payment failed",
-  "statusMessage": "Payment failed",
   "status": 402
 }
```

**On evlog 2:** switch your code and queries to `status` and `message` now. Both are already on every `EvlogError` and every logged error. The getters do not print a warning, because h3, Nitro and evlog's own serializer read them on every error.

## Changed

APIs and defaults that still exist in evlog 3 and behave differently.

### Node 22 or later

**Who:** every project.

`engines.node` is `>=22.0.0` in every published package: `evlog`, `@evlog/cli`, `@evlog/nuxthub`, `@evlog/telemetry` and `@evlog/signals`.

**On evlog 2:** move your runtime to Node.js 22 or later before you upgrade. evlog 2 supports it.

### Nitro entry points

**Who:** projects that import `evlog/nitro` or `evlog/nitro/v3`.

`evlog/nitro` becomes the Nitro 3 module, and the nitropack (Nitro 2) module moves to `evlog/nitro/v2`. `evlog/nitro/v3` is removed. Nitro 2 stays supported, and the Nuxt module needs no change.

<table>
<thead>
  <tr>
    <th>
      Server
    </th>
    
    <th>
      evlog 2
    </th>
    
    <th>
      evlog 3
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Nitro 3
    </td>
    
    <td>
      <code>
        evlog/nitro/v3
      </code>
    </td>
    
    <td>
      <code>
        evlog/nitro
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      nitropack (Nitro 2)
    </td>
    
    <td>
      <code>
        evlog/nitro
      </code>
    </td>
    
    <td>
      <code>
        evlog/nitro/v2
      </code>
    </td>
  </tr>
</tbody>
</table>

**On evlog 2:** nothing to switch. `evlog/nitro/v2` does not exist in evlog 2, so change the imports when you upgrade.

### Compact output by default

**Who:** anyone who sends logs to `evlog/otlp`, PostHog (logs or events mode), HyperDX or Sazabi. HyperDX and Sazabi are built on the OTLP encoder and follow the same defaults.

OTLP records default to the compact shape, with OpenTelemetry semantic conventions on:

- `recordShape` defaults to `'compact'`. The body is a one-line summary such as `POST /api/checkout (500)`, and nested fields become dotted attributes such as `user.id`. In PostHog events mode, nested properties are flattened the same way.
- `semanticConventions` defaults to `true`. Records also carry `http.request.method`, `url.path`, `http.response.status_code`, `exception.*` and `gen_ai.*`. The evlog field names stay.

**On evlog 2:** set the options explicitly. To keep today's output after the upgrade:

```ts
createOTLPDrain({ recordShape: 'json', semanticConventions: false })
createPostHogDrain({ recordShape: 'json' })
```

To see the new output now, set `recordShape: 'compact'` and `semanticConventions: true` instead. On evlog 2, the PostHog and Sazabi drains take `recordShape` only, and HyperDX takes neither. What a drain cannot set follows the new defaults once you upgrade.

### AI fields renamed to GenAI conventions

**Who:** anyone who uses `evlog/ai` or `evlog/eve` and queries, charts or alerts on the AI fields of a wide event, or reads `AILogger.getMetadata()`.

The `ai` block becomes `gen_ai`. Fields take the [OpenTelemetry GenAI](https://github.com/open-telemetry/semantic-conventions-genai) names where the conventions define one, and evlog's own fields sit under the same key in snake_case:

<table>
<thead>
  <tr>
    <th>
      evlog 2
    </th>
    
    <th>
      evlog 3
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ai.model
      </code>
      
       / <code>
        ai.models
      </code>
    </td>
    
    <td>
      <code>
        gen_ai.request.model
      </code>
      
       / <code>
        gen_ai.request.models
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.provider
      </code>
    </td>
    
    <td>
      <code>
        gen_ai.provider.name
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.inputTokens
      </code>
      
       / <code>
        ai.outputTokens
      </code>
      
       / <code>
        ai.totalTokens
      </code>
    </td>
    
    <td>
      <code>
        gen_ai.usage.input_tokens
      </code>
      
       / <code>
        output_tokens
      </code>
      
       / <code>
        total_tokens
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.costUsd
      </code>
      
       / <code>
        ai.estimatedCost
      </code>
    </td>
    
    <td>
      <code>
        gen_ai.usage.cost
      </code>
      
       / <code>
        gen_ai.usage.estimated_cost
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.finishReason
      </code>
      
       (last call)
    </td>
    
    <td>
      <code>
        gen_ai.response.finish_reasons
      </code>
      
       (one entry per call)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.msToFirstChunk
      </code>
    </td>
    
    <td>
      <code>
        gen_ai.response.time_to_first_chunk
      </code>
      
      , in seconds
    </td>
  </tr>
</tbody>
</table>

The full table is in the migration guide when 3.0 ships.

**On evlog 2:** nothing to switch. Field names in saved queries and dashboards live outside your code, so list the ones that read `ai.*` and update them when you upgrade.

### Logged error guidance

**Who:** drains and saved queries that read `error.data.why` or `error.data.fix` from a logged event.

A logged `EvlogError` carries `code`, `why`, `fix` and `link` once, at the top of `error`. Its `data` is only the payload passed to `createError({ data })`. The HTTP response is unchanged, and `parseError()` still reads the guidance on the client.

**On evlog 2:** switch now. evlog 2 already logs `error.why` and `error.fix` at the top of `error`, so read them there.

### Status is optional

**Who:** code that reads `error.status` as a number, alert or sampling rules that match on it, and projects that log errors outside HTTP, such as agent turns, jobs, cron tasks and CLI scripts.

`status` is optional on `EvlogError`, on `createError()` options, and on error catalog entries. Core no longer defaults it to 500, so an error that never reaches an HTTP response logs no `status`. Every HTTP boundary still answers 500 for an error without one.

**On evlog 2:** nothing to switch. Find the rules that match `status: 500` on errors outside HTTP, and change them when you upgrade.

### A second error replaces the first

**Who:** code that calls `log.error()` more than once on the same request or job logger.

A second `log.error()` replaces the first error on the event. In evlog 2 the event takes the second error's `message` and `code` but keeps fields only the first one had, such as its `fix` or `cause`. To keep both failures, record the earlier one under its own key:

```ts
log.set({ receipt: { error } })
```

**On evlog 2:** switch now. The `log.set()` call works the same way in both majors.

### Nitro and Nuxt error body

**Who:** client code that reads `statusCode` or `statusMessage` from the JSON body of an error response.

The error body from the Nitro, Nuxt and SvelteKit error handlers carries the status in `status` and the text in `message`. The `statusCode`, `statusText` and `statusMessage` fields are gone.

**On evlog 2:** switch now. The evlog 2 body already carries `status` and `message`, and `parseError()` reads them.

### CLI peer range

**Who:** projects that install `@evlog/cli` next to `evlog`.

`@evlog/cli` 1.0 ships alongside evlog 3, with the peer range `evlog ^2.31.0 || >=3.0.0-beta.0`. The CLI and the library keep separate version lines, so check both in your lockfile after you upgrade.

### Framework peer ranges

**Who:** projects that plan to move to NestJS 13, React Router 9 or Hono 6.

The optional peer ranges for `@nestjs/common` and `@nestjs/core`, `react-router` and `hono` stop at the majors evlog's tests run on. A version outside the range installs with a peer warning.

### Two majors in one process

**Who:** projects where a dependency still loads evlog 2 while your app loads evlog 3.

Each major keeps its own logger configuration, drain and redaction, and evlog prints a warning when both load. Run `pnpm why evlog` or `npm ls evlog --all` to find the dependency that pulls in the 2.x copy. Deduplicating cannot satisfy a dependency that requires evlog 2, so update it to a version that supports evlog 3, or replace it.

### Credentials detected by value

**Who:** anyone whose logs carry a provider credential that key-based redaction misses, and anyone who reads masked values in logs, alerts or tests.

The `apiKeys`, `privateKey` and `urlPassword` built-ins are on by default. They mask provider keys by their prefix, PEM private key blocks, and the password in a URL. The `secrets` key list also covers `apiKey`, `api_key`, `privateKey`, `credentials`, `authorization`, `dsn` and `connectionString`.

**On evlog 2:** turn them on now to see the result. List them in `redact.builtins` with the other built-ins you use, as [credentials by value](https://www.evlog.dev/learn/redaction#credentials-by-value) shows.

### File system drain permissions

**Who:** projects that use `evlog/fs` on macOS or Linux and read its files from another account, such as a log shipper running as its own user.

The drain creates its directories with mode `0700` and each log file with mode `0600`, so only the account that runs the app can read them. On Windows, nothing changes.

**On evlog 2:** run the readers as the account that runs the app. To restrict the files that already exist, run `chmod -R go= .evlog`.

## Checklist

<table>
<thead>
  <tr>
    <th>
      Change
    </th>
    
    <th>
      Warns in evlog 2
    </th>
    
    <th>
      Switch on evlog 2
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="#browser-entry-removed">
        Browser entry removed
      </a>
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#credential-aliases-removed">
        Credential aliases removed
      </a>
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#posthog-events-drain-removed">
        PostHog events drain removed
      </a>
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#logger-storage-moved">
        Logger storage moved
      </a>
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#eve-moves-to-evlogeve">
        eve moves to @evlog/eve
      </a>
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      no
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#error-status-fields">
        Error status fields
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#node-22-or-later">
        Node 22 or later
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#nitro-entry-points">
        Nitro entry points
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      no
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#compact-output-by-default">
        Compact output by default
      </a>
    </td>
    
    <td>
      yes, OTLP and PostHog
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#ai-fields-renamed-to-genai-conventions">
        AI fields renamed to GenAI conventions
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      no
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#logged-error-guidance">
        Logged error guidance
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#status-is-optional">
        Status is optional
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      no
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#a-second-error-replaces-the-first">
        A second error replaces the first
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#nitro-and-nuxt-error-body">
        Nitro and Nuxt error body
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#credentials-detected-by-value">
        Credentials detected by value
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      yes
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="#file-system-drain-permissions">
        File system drain permissions
      </a>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      yes
    </td>
  </tr>
</tbody>
</table>

---

- [Installation](https://www.evlog.dev/start/installation)


## Sitemap

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