# Logs

`logs` adds a Logs tab to the panel, beside Problems. It records what the console methods are
called with, uncaught errors, failed resource loads and rejected promises, and can also receive
lines from anywhere else in your code.

```ts
import { logs } from "codelet/extensions/logs";
import { Workbench, FileSystem } from "codelet/workbench";

const workbench = new Workbench({
  parent: document.getElementById("app")!,
  fs: new FileSystem({ "/README.md": "# Hello" }),
  extensions: [logs()],
});
```

## Options

| Option    | Type                                                  | Default   | Description                                                                                                  |
| --------- | ----------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------ |
| `limit`   | `number`                                              | `500`     | How many entries are kept. The oldest are dropped first.                                                     |
| `level`   | `"error" \| "warn" \| "info" \| "debug"`              | `"debug"` | The quietest level kept, whatever raised it. Entries below this level are dropped entirely, not just hidden. |
| `methods` | `("error" \| "warn" \| "log" \| "info" \| "debug")[]` | all five  | Which `console` methods are spied on.                                                                        |
| `errors`  | `boolean`                                             | `true`    | Capture uncaught errors, failed resource loads and unhandled promise rejections.                             |
| `reveal`  | `boolean`                                             | `true`    | Open the panel onto the Logs tab the first time a new error appears.                                         |

## Try it

The panel starts empty: Logs only captures console calls made after the workbench mounts.
Open your browser's DevTools console and run `console.log("hello")` — the line lands here as
a new row, since Logs wraps the real `console`.

::codelet-playground{mode="workbench" extensions="logs" view="logs" height="420"}

```md [README.md]
# Logs demo

Open your browser's DevTools console and call `console.log("hello")` to see a row appear in
the panel below.
```

::

## What it captures

Only what happens after the workbench mounts is captured, since capturing works by wrapping the
five console methods and listening for `error` and `unhandledrejection` events. Nothing said
before that is replayed automatically.

To feed the log anything from earlier, or from a source `logs` can't see for itself, run the
`logs.append` command with a level and any number of arguments. Commands are run through the
`vscode` namespace, so this is typically called from another extension's `activate`:

```ts
vscode.commands.executeCommand("logs.append", "info", "server ready");
```

## Output channels

`window.createOutputChannel`, part of the extension API, works without this extension: it
writes to the console when no Logs panel is running. With `logs` installed, a channel's lines
land here instead, each row prefixed with the channel's name in brackets, like `[my-channel]`.
A row with no such prefix is the page's own console output.

## Filtering

Above the rows, a filter box narrows by text and a dropdown narrows by level. The dropdown
offers `All` plus a step for each level above the `level` option, so a panel keeping nothing
below `info` never offers a step that would show nothing new.

## Copying a row

Rows are chrome and take no text selection, so a right-click is how anything gets out of the
panel: **Copy** puts the whole entry on the clipboard — the channel name, the message, and
every detail line under it, whether or not the row is unfolded. On one of those detail lines it
copies that line alone.

The browser only gives a page a clipboard in a secure context, so a workbench served over plain
http shows no Copy item at all rather than one that silently does nothing.

## The status bar item

A footer item opens and closes the panel. Its icon becomes an error count, such as `$(error) 3`,
whenever the log holds one or more errors, and reverts once none remain.

An error opens the panel automatically once per burst, controlled by `reveal`. A repeat of the
same error only increments the count on its existing row rather than reopening the panel again.

:read-more{to="/extensions"}