Skip to main content

One Buggregator for all your apps, each in its own project

Run one Buggregator for all your services and give each one a project key. The key goes in the Sentry DSN path (http://sentry@127.0.0.1:8000/shop), the SMTP user name, or the profiler URL. Each service's errors, mail and profiles then stay in their own project, and the project switcher in the sidebar shows one at a time.

Steps

1. List your projects

Create buggregator.yaml with one entry per service. This step is optional: a new key is also added on its first event card, with the key as its name.

yaml
projects:
  - key: shop
    name: Shop
  - key: billing
    name: Billing

2. Mount the file into the container

Buggregator reads buggregator.yaml from its working directory.

yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:1025:1025
    volumes:
      - ./buggregator.yaml:/buggregator.yaml

3. Put the key in each service's Sentry DSN

Use the project key as the last part of the DSN path. Inside Compose, use the service name as the host.

dotenv
# shop service
SENTRY_DSN=http://sentry@buggregator:8000/shop

# billing service
SENTRY_DSN=http://sentry@buggregator:8000/billing

A numeric path like /1 sends events to default. If your SDK accepts only a number there, put the key before @ instead, for example http://billing@buggregator:8000/1. That works since server v2.10.0, and only for a project that already exists.

4. Put the key in the SMTP user name

The SMTP user name picks the project; the password can be anything.

dotenv
MAILER_DSN=smtp://shop:any@buggregator:1025

In Laravel, set MAIL_USERNAME=shop and any MAIL_PASSWORD.

5. Other event types

Each module takes the key in its own place:

dotenv
# XHProf profiler
PROFILER_ENDPOINT=http://profiler:shop@buggregator:8000

# Ray
RAY_HOST=ray:shop@buggregator
RAY_PORT=8000

For Monolog, add project to the record's context: $logger->error('Payment failed', ['project' => 'shop']). Records and dumps without it land in default.

6. Switch between projects

Open http://127.0.0.1:8000 and pick a project in the sidebar. You see only that service's events.

Why it works

Every event carries a project key, read from the DSN path, the user name or the context. Without one, it goes to the default project. For Sentry the order is: DSN path, then the X-Buggregator-Project header or Basic Auth, then the DSN public key, then default.

Checked on with Buggregator v2.13.0

Setup in 60 seconds

No registration. No account. Start it and point your app at it.

1

Start Buggregator

One file, installed with one command. The web UI opens on port 8000. Prefer containers? Use the Docker tab.

$ curl -fsSL https://raw.githubusercontent.com/buggregator/server/master/scripts/install.sh | sh
$ HTTP_ADDR=127.0.0.1:8000 \
  SMTP_ADDR=127.0.0.1:1025 \
  VAR_DUMPER_ADDR=127.0.0.1:9912 \
  MONOLOG_ADDR=127.0.0.1:9913 \
  PROXY_ADDR=127.0.0.1:8080 \
  ~/.local/bin/buggregator

The script picks the file for your CPU: Intel/AMD or ARM.

One file for Linux, macOS and Windows, about 40 MB. Nothing else to install.

This run line keeps it on this computer. Without the *_ADDR settings it listens on all network interfaces

Rather not run a script? Download the file yourself

Runs on Windows, macOS and Linux, on Intel/AMD and ARM.

Prefer not to do it yourself? Your AI agent can set Buggregator up for you