---
title: "Logs"
description: "Wide events per request, console output and isolate events, searchable for 14 days."
canonical_url: "https://docs.lightdrop.cloud/guides/logs"
---
# Logs

> Wide events per request, console output and isolate events, searchable for 14 days.

Everything an app writes to the console ends up in its logs, together with what the runtime knows
about its isolates: boots, boot failures, uncaught exceptions and shutdowns (including CPU and
memory limits), and errors of the runtime about the app, such as an isolate that couldn't start for
a request (`type:=Runtime`). Logs are kept for 14 days. Read them on the app's **Logs** page in the dashboard or
with `wervt logs`.

When an isolate is stopped for its CPU or memory limit, the entry says which (`Stopped: memory limit reached`) and carries a `hint` on what to change; requests in flight were cancelled. See the
[limits](https://docs.lightdrop.cloud/self-hosting/architecture#isolate-limits).

## Wide events

`@wervt/nuxt` sets up [evlog](https://www.evlog.dev): every request logs **one event** with its
method, path, status, duration and request id, and the error with its stack when it failed. Add
what matters for the request to that same event instead of logging separate lines:

```ts [server/api/rooms/[id].post.ts]
import { useLogger } from '@wervt/nuxt/server'
import { defineEventHandler, getRouterParam } from 'nuxt/server'

export default defineEventHandler(async (event) => {
  const log = useLogger(event)
  const user = await requireUser(event)
  log.set({ user: { id: user.id }, room: { id: getRouterParam(event, 'id') } })
  // …
})
```

Each field becomes searchable: `user.id:u_123`, `room.id:abc`. For a line outside a request, use
`log.info('sync', 'calendar refreshed')` (or `console.log`, which works too).

Requests that fail with a 5xx are logged as `error`, with a 4xx as `warn`.

### Personal data

Logged values are masked when they look like an email, a card number, an IP address, a phone
number, a JWT or a bearer token. Don't put request bodies or secrets into events. Logs may be read
by people and agents debugging the app.

### Configuration

Pass evlog's options under `evlog` in `nuxt.config.ts`, for example to sample routine requests:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@wervt/nuxt'],
  $production: {
    evlog: { sampling: { rates: { info: 20 } } },
  },
})
```

## Searching

Queries are [LogsQL](https://docs.victoriametrics.com/victorialogs/logsql/):

<table>
<thead>
  <tr>
    <th>
      Query
    </th>
    
    <th>
      Finds
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        level:error
      </code>
    </td>
    
    <td>
      errors, uncaught exceptions, failed boots
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status:>=500
      </code>
    </td>
    
    <td>
      requests that failed on the server
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path:/api/rooms
      </code>
    </td>
    
    <td>
      requests to a path (prefix: <code>
        path:/api/*
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        user.id:u_123
      </code>
    </td>
    
    <td>
      a field you set with <code>
        log.set
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type:=BootFailure
      </code>
    </td>
    
    <td>
      releases that didn't start
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type:=Shutdown reason:=CPUTime
      </code>
    </td>
    
    <td>
      isolates stopped for using too much CPU
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type:=Shutdown reason:=Memory
      </code>
    </td>
    
    <td>
      isolates stopped for running out of memory
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        requestId:="<id>"
      </code>
    </td>
    
    <td>
      everything one request logged
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type:=Alert
      </code>
    </td>
    
    <td>
      alerts that fired (see below)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type:=Runtime
      </code>
    </td>
    
    <td>
      requests the runtime couldn't hand to the app
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type:=Service
      </code>
    </td>
    
    <td>
      output of the app's <a href="https://docs.lightdrop.cloud/guides/services">
        service containers
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type:=Service stream:=runner
      </code>
    </td>
    
    <td>
      their starts, stops, crashes and out-of-memory kills
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        timeout
      </code>
    </td>
    
    <td>
      any entry containing the word
    </td>
  </tr>
</tbody>
</table>

## Requests

Every wide event carries a `requestId`, and so does whatever the app logs with it. **Requests** in
the explorer (or `wervt logs --requests`) shows one row per request instead of one per entry: the
method, path, status and duration from its wide event, and how many entries, errors and warnings it
logged. Pick a row, or **Show the whole request** on an entry, to search `requestId:="<id>"` and
see everything that request logged.

## Saved queries and alerts

**Saved** next to the search keeps a query with its levels under a name, per app; picking it runs it
again. A saved query can have an **alert**: the control plane counts its matches every minute, and
when at least *n* entries matched within the window (1 minute to 24 hours), the app's owner and
members get a mail with the newest matches and a link to the logs. After that it stays quiet for
its cooldown (15 minutes to 1 day), even while entries keep matching, so a burst of errors is one
mail. Every alert also writes an entry to the app's logs (`type:=Alert`).

**Errors** (`level:error`) and **Boot failures** (`type:=BootFailure`) are suggested as alerts.
Admins can save queries across all apps on the **Logs** page; their alerts go to the admins.

## `wervt logs`

```bash
wervt logs todos                        # the last hour, oldest first
wervt logs todos 'level:error' --since 1d
wervt logs todos 'status:>=500' --json  # every field, one JSON object per line
wervt logs todos -f                     # keep printing new entries
wervt logs todos --requests --since 6h  # one line per request
wervt logs todos --saved Errors         # a saved query
```

## `wervt queries`

```bash
wervt queries todos                                          # saved queries and their alerts
wervt queries todos --save Errors --query 'level:error' --alert on
wervt queries todos --save Errors --threshold 5 --window 15m --cooldown 6h
wervt queries todos --save Errors --alert off                # keep the query, drop the alert
wervt queries todos --delete Errors
wervt queries                                                # across apps (admins)
```

To let an agent or a script read logs without deploy rights, give it the **read token**: it can
list apps and read logs, nothing else.

```bash
WERVT_URL=https://api.lightdrop.cloud WERVT_TOKEN=<read token> wervt logs todos 'level:error'
```


## Sitemap

See the full [sitemap](https://docs.lightdrop.cloud/sitemap.md) for all pages.
