Skip to content

Sentry — Exceptions ​

You want to see exceptions with stack traces, breadcrumbs, and request context — but you don't want to deploy a full Sentry instance just for local development. Buggregator accepts the same Sentry SDK protocol, so you change one line in your config and get exception tracking alongside all your other debug data — logs, dumps, emails, profiling — in a single UI.

No registration. No limits. No heavy infrastructure.

Sentry exceptions

Use cases ​

  • Long-running apps (RoadRunner, Swoole, queue workers) — exceptions don't show in the browser, but they show in Buggregator.
  • Microservices / Docker Compose — collect exceptions from all services in one place instead of checking each container's logs.
  • Frontend + Backend — catch JavaScript errors alongside PHP exceptions in the same dashboard.
  • Quick local debugging — don't wait for errors to appear in a remote Sentry instance. See them instantly.

What you see in the UI ​

  • Exception — frame-by-frame stack trace with file paths, line numbers, and code context. Click to open in your IDE.
  • Breadcrumbs — timeline of user actions and system events leading up to the error.
  • Request — HTTP method, URL and headers.
  • Device — browser, OS, device type.
  • App — application name, version, build.
  • Tags & Extra — custom key-value data attached to the event.
  • Modules — loaded packages with versions.

Configuration ​

Point your Sentry DSN at Buggregator. The format is the same for all platforms:

dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1

In Docker Compose, replace 127.0.0.1 with the Buggregator service name (e.g., buggregator).

Laravel ​

dotenv
SENTRY_LARAVEL_DSN=http://sentry@127.0.0.1:8000/1

Install the SDK: docs.sentry.io/platforms/php/guides/laravel

Spiral Framework ​

dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1

Install the SDK: spiral.dev/docs/extension-sentry

Symfony ​

dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1

Install the SDK: docs.sentry.io/platforms/php/guides/symfony

Magento 2 ​

Using justbetter/magento2-sentry:

dotenv
CONFIG__SENTRY__ENVIRONMENT__DSN=http://sentry@127.0.0.1:8000/1

or in app/etc/env.php:

php
'sentry' => [
    'dsn' => 'http://sentry@127.0.0.1:8000/1',
    ...
]

WordPress ​

WP_ENVIRONMENT_TYPE must be set to local. Local does that by default.

  1. Install WP Sentry (no need to activate).
  2. Add to wp-config.php:
php
if (defined('WP_ENVIRONMENT_TYPE') && 'local' === WP_ENVIRONMENT_TYPE) {
	define( 'WP_SENTRY_PHP_DSN', 'http://sentry@127.0.0.1:8000/1' );
	define( 'WP_SENTRY_ERROR_TYPES', E_ALL & ~E_NOTICE & ~E_USER_NOTICE );
	require_once __DIR__ . '/wp-content/plugins/wp-sentry-integration/wp-sentry.php';
}

JavaScript, Python, Go ​

Since server v2.9.0, Buggregator accepts events from the official JavaScript, Python and Go SDKs. They were tested with real requests from these versions:

SDKTested version
@sentry/browser11.11
@sentry/node11.11
sentry-python2.74 (also with Brotli-compressed bodies)
sentry-go0.50

What Buggregator stores and shows from them: errors, messages, transactions and traces with their spans, and logs. What it does not store: sessions, client reports, profiles, replays, attachments and minidumps.

Two settings matter in every SDK:

  • The DSN. Any key before @ works, e.g. http://sentry@127.0.0.1:8000/1. A number at the end puts the event into the default project; a name such as /shop puts it into that project. The key before @ can also pick an existing project (see Projects).
  • The trace sample rate. Set it to 1.0, or traces are sampled away and never sent.

In Docker, replace 127.0.0.1 with the Buggregator host or service name, e.g. http://sentry@buggregator:8000/1.

Browser JavaScript ​

javascript
import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "http://sentry@127.0.0.1:8000/1",
  integrations: [Sentry.browserTracingIntegration()],
  tracesSampleRate: 1.0,
  enableLogs: true,
});

No CORS setup is needed: Buggregator accepts requests from any origin by default.

Node.js ​

javascript
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: "http://sentry@127.0.0.1:8000/1",
  tracesSampleRate: 1.0,
  enableLogs: true,
});

Next.js ​

@sentry/nextjs is built on the Node.js and browser SDKs above. Set the same DSN and options in each Sentry.init call of its setup (Next.js SDK docs):

javascript
Sentry.init({
  dsn: "http://sentry@127.0.0.1:8000/1",
  tracesSampleRate: 1.0,
  enableLogs: true,
});

@sentry/nextjs itself was not run against Buggregator; the SDKs it wraps were.

Python ​

python
import sentry_sdk

sentry_sdk.init(
    dsn="http://sentry@127.0.0.1:8000/1",
    traces_sample_rate=1.0,
    enable_logs=True,
)

Django ​

Django uses the same sentry-python SDK. Call sentry_sdk.init(...) as above in settings.py; the SDK turns on its Django integration by itself. The Django integration itself was not run against Buggregator; the SDK was.

Go ​

go
err := sentry.Init(sentry.ClientOptions{
    Dsn:              "http://sentry@127.0.0.1:8000/1",
    EnableTracing:    true,
    TracesSampleRate: 1.0,
})
if err != nil {
    log.Fatal(err)
}
defer sentry.Flush(2 * time.Second)

In sentry-go 0.50, logs from sentry.NewLogger(ctx) are sent without any extra option.

Other platforms ​

The Java SDK was checked with Spring Boot: see the Spring Boot guide. Other Sentry SDKs (Ruby, .NET and others) are not verified yet. Set the DSN as above and try; if an event does not show up, please open an issue with the SDK name and version.

dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/1

Projects ​

Send each app to its own project, and the Sentry page shows only that project's data. Without a project, everything goes to default.

With the Sentry PHP SDK, put the project key in the DSN path instead of the number:

dotenv
SENTRY_DSN=http://sentry@127.0.0.1:8000/shop

A number in the path (/1, /42) is the SDK's own project id, not a Buggregator project. Such events go to default, unless the key before @ or the headers below name a project.

Project per service with a numeric DSN ​

Other SDKs accept only a number at the end of the DSN. The Sentry JavaScript and Python SDKs, for example, refuse http://sentry@127.0.0.1:8000/shop. Since server v2.10.0, you can keep the number and put the project key before @ instead:

dotenv
# PHP backend
SENTRY_DSN=http://billing@127.0.0.1:8000/1
# JavaScript frontend
SENTRY_DSN=http://storefront@127.0.0.1:8000/1

The JavaScript SDK takes only letters, digits and _ before @. A key with -, like store-front, makes the DSN invalid and the SDK sends nothing. Since server 2.11.0, write _ instead of -: the key store_front finds the project store-front. A project whose key matches exactly still wins. On older servers, name such a project store_front or storefront.

The key before @ is the DSN's public key. The SDK sends it with every event, and Buggregator uses it as the project key, but only when that project already exists. List the projects in buggregator.yaml:

yaml
projects:
  - key: billing
    name: Billing
  - key: storefront
    name: Storefront

A project also exists once an event has created it, for example an error sent earlier to http://sentry@127.0.0.1:8000/billing.

What happens with other keys:

  • sentry (the key in our examples) never names a project. Such events go to default, as before.
  • A key with no such project, such as a random key copied from a real Sentry DSN, sends events to default. Buggregator does not create a project from a key.

Project by headers ​

If your SDK lets you add HTTP headers, you can send two headers together:

X-Buggregator-Event: sentry
X-Buggregator-Project: shop

X-Buggregator-Project alone is not enough: a Sentry SDK request is recognized by its X-Sentry-Auth header, and that path ignores X-Buggregator-Project.

Which one wins ​

When a request carries more than one, the first match in this list wins:

OrderHowExample
1DSN pathhttp://sentry@127.0.0.1:8000/shop
2HeadersX-Buggregator-Event: sentry + X-Buggregator-Project: shop
3DSN public key, existing project onlyhttp://billing@127.0.0.1:8000/1
4Nothing of the abovedefault

A project that does not exist yet is added to the project list when its first error arrives. A project that receives only traces, logs or metrics is not added: put it in buggregator.yaml (see Projects).

Errors, traces, logs and metrics all land in the same project, however you set it.

Upgrading to v2.6.0: Sentry errors sent with a numeric DSN, and traces, logs and metrics stored by earlier versions, had no project. On first start, v2.6.0 moves them to default. Nothing is deleted.

Traces, logs and metrics ​

Besides errors, Buggregator stores what the Sentry SDK sends as traces (transactions and spans), logs and metrics. The Sentry page has a tab for each:

  • Exceptions — errors, as a list or grouped by fingerprint.
  • Traces — transactions with their spans.
  • Logs — Sentry structured logs.
  • Metrics — Sentry metrics.

Traces and logs from OpenTelemetry (OTLP) land in the same Traces and Logs tabs, marked OTel: see OpenTelemetry.

Filters ​

Every tab shows the current project and the chosen period (last hour, last 24 hours, last 7 days, all time, …). Filtering happens on the server, so a filter does not miss rows past the first page.

The REST API accepts more filters than the page shows:

EndpointFilters
GET /api/sentry/exceptionsproject, environment, level, handled, grouped=true, from, to, window
GET /api/sentry/tracesproject, environment, release, from, to, window
GET /api/sentry/logsproject, level (several, comma-separated), trace_id, from, to, window
GET /api/sentry/metricsproject, name, type, trace_id, search (part of the name), from, to, window
GET /api/sentry/countsproject, from, to, window

window is a period like 15m, 24h or 7d. from and to take unix seconds or ISO 8601.

Live updates ​

The tabs refresh by themselves when new rows arrive. Example: your app writes a Sentry log, and the open Logs tab shows it without a reload. Each tab reloads only for its own kind of data.

For clients of the WebSocket: when a request stored logs, metrics or traces, the server sends one sentry.stored notice on the project's channel events.project.<key>:

json
{"project": "default", "kinds": ["log", "metric"]}

Kinds are log, metric and trace. An error alone sends the usual event.received.

Cron monitors ​

Check-ins from Sentry Crons (check_in) are stored: see Cron Monitoring.

User feedback ​

Since server 2.13.0 Buggregator keeps the feedback your users send through a Sentry SDK: the feedback widget, captureFeedback, or the older captureUserFeedback. Nothing to set up beyond the usual DSN.

js
const eventId = Sentry.captureException(new Error('Checkout failed'))

Sentry.captureFeedback({
  name: 'Jane Doe',
  email: 'jane@example.com',
  message: 'The pay button did nothing',
  associatedEventId: eventId,
})
  • Feedback tied to an error shows on that error's page, above the tabs: name, email, message, page URL and time.
  • The Feedback tab on the Sentry page lists all feedback, also the one sent without an error.
  • Feedback makes no card of its own in the event feed.
  • Screenshots attached to feedback are not stored.
  • API: GET /api/sentry/feedback (filters event_id, project, from, to, window).

Clearing Sentry data clears feedback too, except the feedback of pinned errors.

Desktop notifications ​

Want to know about a new error while you work in another window? Turn on Settings › Notifications › Desktop notifications (since server 2.13.0). The browser asks for permission once and shows a test notice.

  • You get a notice for each new Sentry error (an exception, or a message at level error or fatal) from any project, while the Buggregator tab is in the background. Click it to open the error.
  • Several errors within 10 seconds come as one notice: «3 new errors».
  • With several Buggregator tabs open, only one notifies, and none while you are looking at one of them.
  • The tab must stay open; a closed tab shows nothing.
  • It works only when you open Buggregator as https or localhost, e.g. http://localhost:8000. Chrome on Android does not show notifications from a page.

Clearing data ​

Clear on the Sentry page deletes the Sentry data of the current project only: errors, traces, logs, metrics, user feedback and the run history of cron monitors. Pinned errors stay, and so does their feedback. The cron monitors stay with their settings; their last status starts over. Other projects are not touched.

The same through the API:

CallDeletes
DELETE /api/sentry/all?project=shopeverything Sentry stored for shop
DELETE /api/sentry/all?project=shop&keep_pinned=1the same, but pinned errors stay
DELETE /api/sentry/allSentry data of every project

A trace can hold spans of several projects. After a project is cleared, a trace with no spans left is deleted; a trace with spans of other projects stays.

DELETE /api/sentry/all clears the Sentry tables (traces, logs, metrics, error details). The error cards in the event feed are events: clear them with DELETE /api/events and the body {"type": "sentry", "project": "shop", "keep_pinned": true}.