> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser trace

> Debug browser automation with a Chrome DevTools Protocol trace, screenshots, DOM snapshots, and searchable per-page events.

The `browser-trace` skill records what happens during a browser run so your agent can diagnose failed requests, JavaScript errors, or unexpected navigation. It adds a separate Chrome DevTools Protocol (CDP) client alongside your automation and organizes events by page.

The tracer observes the browser. Your Browse CLI, Stagehand, or Playwright automation still drives it.

## Install

You need Node.js 18+ for the trace scripts and the [Browse CLI](/integrations/skills/browse-cli) with `browse cdp` support. Remote captures also need `BROWSERBASE_API_KEY` in your environment.

```bash theme={null}
npx skills add browserbase/skills --skill browser-trace
npm install -g browse
```

The trace scripts use Node.js built-in modules and don't need a separate dependency install.

## Capture a run

Give your agent a URL and the steps that reproduce the issue:

```text theme={null}
Use browser-trace to debug the product filter at https://app.example.com.
Create a Browserbase capture named filter-debug, attach the automation
to the same session, and reproduce the filter failure.
Stop the capture, split the events by page, and identify failed requests
or console errors. Show the relevant screenshots and release the session.
```

Your agent uses `bb-capture.mjs --new` to create a keep-alive session and start the tracer. After the run, it stops capture, runs `bisect-cdp.mjs` to group the events, and uses `bb-finalize.mjs --release` to collect platform artifacts and release the session.

You can also ask it to attach to an existing session by ID. For a session that another process owns, finalize **without `--release`** so that automation can continue. Always stop the capture, including after a failed run.

## Read the results

The skill writes artifacts under `.o11y/<run-id>/`:

| Artifact | What to inspect |
| - | - |
| `cdp/summary.json` | Pages, event counts, timing, and failed requests. |
| `cdp/pages/` | Network, console, and navigation events for each page. |
| `screenshots/` and `dom/` | Sampled screenshots and HTML snapshots. |
| `index.jsonl` | Timestamps connecting samples to the current URL. |
| `browserbase/` | Session metadata, logs, and downloads when available. |

Ask your agent to start with the summary, then narrow its investigation to the failing page and timestamp. Empty platform logs don't mean the run had no activity; inspect the CDP events.

## Capture limits

An idle browser produces few events. If the trace looks empty, confirm that your automation attached to the same session and performed the expected actions. If the remote session ended, start a new capture and check its timeout.

The CDP event stream doesn't include response bodies. For API discovery, pair the trace with `browse network on` and follow the [Browser to API guide](/integrations/skills/browser-to-api).

## Further reading

<CardGroup cols={2}>
  <Card title="Browser to API" icon="code" href="/integrations/skills/browser-to-api">
    Turn captured traffic into an OpenAPI document.
  </Card>

  <Card title="Skill source" icon="github" href="https://github.com/browserbase/skills/tree/main/skills/browser-trace">
    View capture commands, query helpers, and debugging examples.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.