Get started

Install

Install by framework, paste the project key, send the first event, then name the person.

For LLMs

You are integrating Bugwalk into an existing application. Bugwalk keeps events, errors, and logs on one timeline per person (after identify()), so an AI debug engineer can explain a failure from that visit and the connected repositories.

Ask these questions one at a time and wait for each answer unless it was already provided:

1. Project key (DSN) from Bugwalk Setup? (placeholder in docs: YOUR_PROJECT_KEY)

2. Frontend stack? Options include: Angular, Next.js, Nuxt, React, Script tag, SvelteKit, Vue

3. Backend stack, if any? Options include: Django, Echo, Express, FastAPI, Fastify, Flask, Gin, Hono, Koa, NestJS, net/http, or none

… full prompt includes every framework snippet.

Run the wizard

In the app you want to watch, run the wizard. It finds the framework, installs the package, and writes the project key from Setup.

The wizard opens a browser tab so you can approve the terminal. Approve it, go back to the terminal, and let it finish. If you would rather paste, use the snippets below. They are the same edits the wizard makes.

  1. 01

    From the app you want to watch

    npx @bugwalk/wizard
  2. 02

    Replace the project key

    Every snippet uses YOUR_PROJECT_KEY. Copy the real key from Setup and paste it in place of that string.

Frontend integrations

Install the package, drop the project key in, and wrap or register the SDK once at startup. Use the same key on the backend half of the app.

Angular

TypeScript

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$npx @bugwalk/wizard
@bugwalk/angularView on npm

Next.js

TypeScript

Install

$npm install @bugwalk/next
@bugwalk/nextView on npm

Add to app/layout.tsx

app/layout.tsx
import { BugwalkProvider } from '@bugwalk/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <BugwalkProvider dsn="YOUR_PROJECT_KEY">{children}</BugwalkProvider>
      </body>
    </html>
  );
}

Nuxt

TypeScript

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$npx @bugwalk/wizard
@bugwalk/nuxtView on npm

React

TypeScript

Install

$npm install @bugwalk/react
@bugwalk/reactView on npm

Add to src/main.tsx

src/main.tsx
import { BugwalkProvider } from '@bugwalk/react';

createRoot(document.getElementById('root')!).render(
  <BugwalkProvider dsn="YOUR_PROJECT_KEY">
    <App />
  </BugwalkProvider>,
);

Script tag

HTML

Install

$<script src="https://cdn.bugwalk.app/v1.js" data-dsn="YOUR_PROJECT_KEY" async></script>
@bugwalk/browserView on npm

Add to index.html

index.html
<script src="https://cdn.bugwalk.app/v1.js" data-dsn="YOUR_PROJECT_KEY" async></script>

SvelteKit

TypeScript

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$npx @bugwalk/wizard
@bugwalk/svelteView on npm

Vue

TypeScript

Install

$npm install @bugwalk/vue
@bugwalk/vueView on npm

Add to src/main.ts

src/main.ts
import { bugwalk } from '@bugwalk/vue';

createApp(App).use(bugwalk, { dsn: 'YOUR_PROJECT_KEY' }).mount('#app');

Backend integrations

Register middleware or a module before your routes. Requests from an identified browser session attach to the same person automatically.

Django

Python

Install

$pip install "bugwalk-sdk[django]"

Add to settings.py

settings.py
BUGWALK_DSN = "YOUR_PROJECT_KEY"

MIDDLEWARE = [
    "bugwalk.django.BugwalkMiddleware",
    *MIDDLEWARE,
]

Echo

Go

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$go get github.com/bugwalk-dev/bugwalk/sdks/go/echo

Express

TypeScript

Install

$npm install @bugwalk/express
@bugwalk/expressView on npm

Add to src/server.ts

src/server.ts
import {
  bugwalkErrorHandler,
  bugwalkMiddleware,
  identify,
} from '@bugwalk/express';

const app = express();
app.use(bugwalkMiddleware({ dsn: 'YOUR_PROJECT_KEY' }));
// After sign-in, in the handler: identify({ id: user.id, email: user.email });
// ... routes ...
app.use(bugwalkErrorHandler());

FastAPI

Python

Install

$pip install "bugwalk-sdk[fastapi]"

Add to main.py

main.py
from bugwalk.fastapi import BugwalkMiddleware

app.add_middleware(BugwalkMiddleware, dsn="YOUR_PROJECT_KEY")

Fastify

TypeScript

Install

$npm install @bugwalk/fastify
@bugwalk/fastifyView on npm

Add to src/server.ts

src/server.ts
import { bugwalkPlugin } from '@bugwalk/fastify';

const app = fastify();
await app.register(bugwalkPlugin, { dsn: 'YOUR_PROJECT_KEY' });

Flask

Python

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$pip install "bugwalk-sdk[flask]"

Gin

Go

Install

$go get github.com/bugwalk-dev/bugwalk/sdks/go/gin

Add to main.go

main.go
import bugwalkgin "github.com/bugwalk-dev/bugwalk/sdks/go/gin"

router.Use(bugwalkgin.Middleware("YOUR_PROJECT_KEY"))

Hono

TypeScript

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$npx @bugwalk/wizard
@bugwalk/honoView on npm

Koa

TypeScript

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$npx @bugwalk/wizard
@bugwalk/koaView on npm

NestJS

TypeScript

Install

$npm install @bugwalk/nestjs
@bugwalk/nestjsView on npm

Add to src/app.module.ts

src/app.module.ts
import { BugwalkModule } from '@bugwalk/nestjs';

@Module({
  imports: [BugwalkModule.forRoot({ dsn: 'YOUR_PROJECT_KEY' })],
})
export class AppModule {}

net/http

Go

No paste snippet here yet. Run npx @bugwalk/wizard in this repo and it writes the file for you.

Install

$go get github.com/bugwalk-dev/bugwalk/sdks/go

Use the exports each package ships

Packages do not all export a default bugwalk object. Express ships bugwalkMiddleware and bugwalkErrorHandler — register middleware before routes and the error handler after routes, then call identify from @bugwalk/express in sign-in handlers. Calling app.use(bugwalk({ dsn })) throws because that export does not exist.

Next.js and React ship BugwalkProvider, useIdentify, and a named identify function. After sign-in, use useIdentify(user) in a client component or import { identify } and call it once you know the id or email. Do not dynamic-import { bugwalk } from @bugwalk/next; there is no bugwalk.identify on that path.

Fastify uses bugwalkPlugin. Vue uses the bugwalk plugin with app.use(bugwalk, { dsn }). The script tag CDN uses the global Bugwalk.identify — that shape is only for the CDN, not for npm imports.

When in doubt, open the installed package’s index.d.ts or match the snippets on this page before writing imports.

Java, .NET, Ruby, and PHP

No Bugwalk package goes into those services. Point the OpenTelemetry agent you already run at Bugwalk and send the project key in a header.

Java, .NET, Ruby, and PHP

OpenTelemetry

Install

$OTEL_EXPORTER_OTLP_ENDPOINT=https://api.bugwalk.app

Add to environment

environment
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.bugwalk.app
OTEL_EXPORTER_OTLP_HEADERS=x-bugwalk-key=YOUR_PROJECT_KEY

How the first event arrives

You do not click a button to send the first event. The SDK sends a batch in the background after the app starts. A page view is usually enough.

Setup polls every few seconds. While it is waiting, the corner says Waiting for the first event. When a batch lands, that becomes Open the dashboard. The first page view is often there within a few seconds of the app starting.

If nothing arrives, the app is not running, the project key is a different project, or the request never left the browser. The key on the Setup page has to be the one in the snippet.

Name the person

Events record even if you never say who they belong to. They show up on Overview as sessions. They do not show up under People, and they are not a journey, until you call identify().

Call it once you know the id or email, usually right after sign-in. Events before and after that call join the same person, including requests the backend made during the visit.

People shows the email when you sent one, otherwise the id. Search accepts either, including a partial email.

Call once you know who the person is. useIdentify skips work while user is undefined.

Next.js / React (recommended)
import { useIdentify } from '@bugwalk/next';

export function HomePage({ user }: { user?: { id: string; email?: string } }) {
  useIdentify(user ? { id: user.id, email: user.email } : undefined);
}

Imperative call in an event handler. Import identify from the same package you installed.

Next.js / React (after sign-in handler)
import { identify } from '@bugwalk/next';

async function onLoginSuccess(user: { id: string; email: string }) {
  identify({ id: user.id, email: user.email });
}

End the Bugwalk visit when auth clears so the next sign-in gets a new session id. Required for shared-browser / multi-user SPAs.

Next.js / React (sign out)
import { resetSession } from '@bugwalk/next';

async function onLogout() {
  await fetch('/api/logout', { method: 'POST' });
  resetSession();
  setUser(null);
}

After the person is authenticated on the server.

Express (sign-in handler)
import { identify } from '@bugwalk/express';

app.post('/api/login', (req, res) => {
  // ... validate credentials ...
  identify({ id: user.id, email: user.email });
  res.json({ token, user });
});

Only when using the script tag / Bugwalk global, not npm packages.

Browser CDN global
Bugwalk.identify({ id: user.id, email: user.email });

When you have an internal id but no email yet.

id only
identify({ id: user.id });

When email is what support already has.

email only
identify({ email: user.email });

After the next event, People looks like this. Email is the title when you sent one.

Search on People accepts sam@ or u_42. Open a row to see their journey.

Sign out

Clearing your app session does not end the Bugwalk visit. The browser keeps the same session id until you call resetSession() from @bugwalk/next or @bugwalk/react in the same handler where you drop the token or user.

useIdentify with no user does not rotate that id. If someone else signs in on the same tab without resetSession(), API calls still send the old x-bugwalk-session header and ingest keeps the first person linked to that session.

Backend identify on login only names the person for that request. The client still owns when a new visit starts.

Background work

A cron, a queue message, a webhook, or a script answers two questions, and either one can be left out. What is the work? Pass a stable id and a kind: cron, queue, or task. Who is it for? Pass the same id or email you would pass to identify().

withWork names the run and starts a new session. forPerson attributes one iteration to a person, then clears that person so the next iteration does not inherit them. Call forPerson inside withWork when the job runs for many people. Call forPerson alone when the work is for one person and has no job name.

A run with no person shows on Overview as a session. It does not show under People. A run that calls forPerson shows each person under People, the same way a signed-in visit does. An error is still an issue. It names the person when one was set, and it keeps the job when the run was named.

Leave identify() for web requests. Calling it with an id such as cron:daily-digest files that string under People.

Nobody owns this run. It shows on Overview as a session. It does not show under People.

unscoped cron
import { withWork } from '@bugwalk/node';

await withWork({ id: 'temp-cleanup', kind: 'cron' }, async () => {
  await deleteOldFiles();
});

The job is the whole run. forPerson uses the same id and email as identify(), on that person’s own session, then clears them.

cron for each person
import { forPerson, withWork } from '@bugwalk/node';

await withWork({ id: 'daily-digest', kind: 'cron' }, async () => {
  for (const person of people) {
    await forPerson({ id: person.id, email: person.email }, async () => {
      await sendDigest(person);
    });
  }
});

kind is queue. The person is still forPerson, not a fake identify() id.

queue message for one person
await withWork({ id: 'process-order', kind: 'queue' }, async () => {
  await forPerson({ id: message.personId }, async () => {
    await fulfill(message);
  });
});

An invoice, a webhook, or a retry. forPerson alone puts them under People. Add withWork with kind task when you also want a name on the run.

work for a person, not a cron
await forPerson({ id: person.id, email: person.email }, async () => {
  await sendInvoice(person);
});

await withWork({ id: 'send-invoice', kind: 'task' }, async () => {
  await forPerson({ id: person.id }, () => sendInvoice(person));
});

@Cron sits above @BugwalkJob so the scheduler calls the wrapped method. The decorator does not walk the list. The loop calls forPerson.

Nest cron
import { BugwalkJob, forPerson } from '@bugwalk/nestjs';

@Cron('0 2 * * *')
@BugwalkJob({ id: 'daily-digest', kind: 'cron' })
async sendDigests() {
  for (const person of await this.people.due()) {
    await forPerson({ id: person.id, email: person.email }, () => this.mailer.send(person));
  }
}

with_work and for_person. The person does not stick to the process.

Python
def send(person):
    bugwalk_sdk.capture("digest_sent")

def run(_run):
    for person in people:
        bugwalk_sdk.for_person(
            lambda person=person: send(person),
            id=person["id"],
            email=person["email"],
        )

bugwalk_sdk.with_work(run, id="daily-digest", kind="cron")

Pass the context into Capture. Identify on the client would leak across goroutines.

Go
err := bugwalk.WithWork(ctx, bugwalk.Work{ID: "daily-digest", Kind: "cron"}, func(ctx context.Context, _ bugwalk.Run) error {
    for _, person := range people {
        if err := bugwalk.ForPerson(ctx, bugwalk.Person{ID: person.ID, Email: person.Email}, func(ctx context.Context) error {
            return sendDigest(ctx, person)
        }); err != nil {
            return err
        }
    }
    return nil
})

Java, .NET, Ruby, and PHP set bugwalk.job.id on the span. bugwalk.job.runner is cron, queue, or task. Person attributes stay as they are. One span per person is the same record as one forPerson call.

Still have a question?

Check the troubleshooting page, or write to us. A person replies by email.