# Buggregator

> Buggregator is a free, open-source debugging server. Debug everything — install nothing. One docker run (or a single binary) gives you exceptions, dumps, emails, profiling, and logs in a single real-time UI. Written in Go with an embedded SQLite database. Runs beside your app, not inside it.

- Install: `docker run --pull always -p 127.0.0.1:8000:8000 -p 127.0.0.1:1025:1025 -p 127.0.0.1:9912:9912 ghcr.io/buggregator/server:latest`
- GitHub: https://github.com/buggregator/server
- Lightweight CLI alternative (no Docker): `composer require --dev buggregator/trap`
- JetBrains IDE plugin: https://plugins.jetbrains.com/plugin/26344-buggregator
- Supported integrations: Sentry SDK, Symfony VarDumper, Monolog, Spatie Ray, Inspector, SMTP, HTTP dumps, XHProf, SMS
- Works with: Laravel, Symfony, Spiral, WordPress, Yii, Drupal — and JS, Python, Ruby, Go via Sentry SDK

---

# Configuration — Database

Buggregator uses [SQLite](https://www.sqlite.org/) as its database. SQLite is embedded directly into the binary —
no external database server is needed.

## Storage Modes

### In-Memory (Default)

By default, Buggregator stores everything in memory. This is the fastest option but **all data is lost when the
server restarts**.

```yaml
database:
  dsn: ":memory:"
```

This is the default — no configuration needed.

### File-Based

To persist data across restarts, specify a file path:

```yaml
database:
  dsn: data.db
```

Or via environment variable:

```bash
DATABASE_DSN=data.db
```

The database file will be created next to the binary (or at the specified path). In Docker, make sure to
mount a volume:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e DATABASE_DSN=/data/buggregator.db \
  -v buggregator-data:/data \
  ghcr.io/buggregator/server:latest
```

### Docker Compose Example

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:1025:1025
      - 127.0.0.1:9912:9912
      - 127.0.0.1:9913:9913
    environment:
      DATABASE_DSN: /data/buggregator.db
      STORAGE_MODE: filesystem
      STORAGE_PATH: /data/storage
    volumes:
      - buggregator-data:/data

volumes:
  buggregator-data:
```

## Attachment Storage

SMTP attachments and HTTP dump files are stored separately from the database. Two modes are available:

| Mode | Environment Variable | Description |
|------|---------------------|-------------|
| `memory` (default) | `STORAGE_MODE=memory` | Stored in RAM. Fast but lost on restart. |
| `filesystem` | `STORAGE_MODE=filesystem` | Stored on disk in the directory specified by `STORAGE_PATH`. |

```yaml
storage:
  mode: filesystem
  path: ./storage
```

> **Tip:** If you use `DATABASE_DSN=:memory:` but `STORAGE_MODE=filesystem`, the event metadata will be lost on
> restart but the attachment files will remain on disk (orphaned). For consistency, either persist both or
> keep both in memory.

## Migrations

Buggregator automatically creates and migrates database tables on startup. No manual migration steps are required.

---

# Configuration — Helm Chart

Deploy Buggregator on Kubernetes using the official Helm chart. The chart deploys a single Go binary
with an embedded SQLite database — no external dependencies required.

## Prerequisites

- Kubernetes 1.23+
- Helm 3.x

## Installation

### Standalone (default)

The simplest setup — uses embedded SQLite, no external dependencies:

```bash
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator
```

Open the web UI:

```bash
kubectl port-forward svc/buggregator 8000:8000
```

Then navigate to http://localhost:8000.

### With SSO

Enable SSO to restrict access to the web UI. Supported providers: Auth0, Google, GitHub, Keycloak,
GitLab, and generic OIDC.

```bash
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator \
  --set auth.enabled=true \
  --set auth.provider=auth0 \
  --set auth.providerUrl=https://your-tenant.auth0.com \
  --set auth.clientId=YOUR_CLIENT_ID \
  --set auth.clientSecret=YOUR_CLIENT_SECRET \
  --set auth.callbackUrl=https://buggregator.example.com/auth/sso/callback \
  --set auth.jwtSecret=YOUR_JWT_SECRET
```

For detailed SSO configuration, see the [SSO guide](./sso.md).

### With Ingress

Expose the web UI via an Ingress controller:

```bash
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set 'ingress.hosts[0].host=buggregator.example.com' \
  --set 'ingress.hosts[0].paths[0].path=/' \
  --set 'ingress.hosts[0].paths[0].pathType=Prefix'
```

With TLS (using cert-manager):

```yaml
ingress:
  enabled: true
  className: nginx
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: buggregator.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: buggregator-tls
      hosts:
        - buggregator.example.com
```

## Connecting your application

Once deployed, configure your application to send data to Buggregator using the Kubernetes service name.

Assuming the release is named `buggregator` in the `default` namespace:

```dotenv
# Sentry
SENTRY_LARAVEL_DSN=http://sentry@buggregator.default.svc:8000/1

# Ray
RAY_HOST=buggregator.default.svc
RAY_PORT=8000

# SMTP
MAIL_MAILER=smtp
MAIL_HOST=buggregator.default.svc
MAIL_PORT=1025

# VarDumper
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=buggregator.default.svc:9912

# Monolog (SocketHandler)
LOG_CHANNEL=socket
LOG_SOCKET_URL=buggregator.default.svc:9913
```

If your application runs in the same namespace, you can use the short service name `buggregator` instead of the FQDN.

## Prometheus Metrics

Enable metrics and create a ServiceMonitor for automatic scraping:

```yaml
metrics:
  serviceMonitor:
    enabled: true
    interval: 30s
```

## Using Existing Secrets

For production environments, store sensitive values in pre-created Kubernetes secrets:

```bash
# Create secrets
kubectl create secret generic buggregator-auth \
  --from-literal=client-id=YOUR_CLIENT_ID \
  --from-literal=client-secret=YOUR_CLIENT_SECRET

# Reference them in values
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator \
  --set auth.existingSecret=buggregator-auth
```

## Storage

The chart creates a PersistentVolumeClaim for data persistence (SQLite database, attachments). To customize:

```yaml
storage:
  enabled: true
  size: 10Gi
  storageClassName: fast-ssd
```

Disable if you don't need persistent storage (data will be lost on pod restart):

```yaml
storage:
  enabled: false
```

## Full Configuration Reference

| Parameter | Description | Default |
|------------------------------------|----------------------------------------------|------------------------------|
| `replicaCount` | Number of replicas | `1` |
| `image.repository` | Container image | `ghcr.io/buggregator/server` |
| `image.tag` | Image tag (defaults to appVersion) | `""` |
| `auth.enabled` | Enable SSO | `false` |
| `auth.provider` | SSO provider | `auth0` |
| `auth.providerUrl` | Provider URL | `""` |
| `auth.clientId` | OAuth client ID | `""` |
| `auth.clientSecret` | OAuth client secret | `""` |
| `auth.callbackUrl` | OAuth callback URL | `""` |
| `auth.scopes` | OAuth scopes | `openid,email,profile` |
| `auth.existingSecret` | Existing secret for auth | `""` |
| `supportedEvents` | Enabled event types | all |
| `service.type` | Service type | `ClusterIP` |
| `service.httpPort` | Web UI port | `8000` |
| `service.smtpPort` | SMTP port | `1025` |
| `service.varDumperPort` | VarDumper port | `9912` |
| `service.monologPort` | Monolog port | `9913` |
| `ingress.enabled` | Enable Ingress | `false` |
| `storage.enabled` | Enable PVC | `true` |
| `storage.size` | PVC size | `5Gi` |
| `metrics.serviceMonitor.enabled` | Enable ServiceMonitor | `false` |

## Uninstall

```bash
helm uninstall buggregator
```

> **Note:** The PVC is not deleted automatically. To remove it:
> ```bash
> kubectl delete pvc buggregator-storage
> ```

---

# HTTP Dumps — Request Inspection

Your app calls external APIs, sends webhooks, or receives callbacks — and you need to see exactly what goes over
the wire. Buggregator captures full HTTP requests: method, URI, headers, cookies, POST data, and uploaded files.
You get a ready-to-use cURL command for any captured request. No need to set up a separate service like
webhook.site — it's built into the same Buggregator where you already see your logs and exceptions.

> **Need to see responses too?** Use the [HTTP Proxy](/config/http-proxy) — it captures both request and response
> by acting as a forward proxy between your app and external services.

![http dumps](https://github.com/buggregator/server/assets/773481/fc823390-b490-4bbb-a787-44471eca9fb6)

## Use cases

- **Webhook development** — build a webhook endpoint and see exactly what the other service sends you.
- **API debugging** — redirect outgoing HTTP calls to Buggregator to inspect request structure before hitting the real API.
- **Replay requests** — copy the generated cURL command and replay any captured request from your terminal.
- **All in one place** — HTTP requests alongside exceptions, logs, and dumps in the same dashboard.

## What you see in the UI

- **HTTP method** — GET, POST, PUT, DELETE, PATCH, etc. (color-coded).
- **Full URI** — complete request URL with path segments.
- **Query parameters** — parsed URL query parameters.
- **POST/form data** — submitted fields and values.
- **Headers** — all request headers.
- **Cookies** — cookies sent with the request.
- **Uploaded files** — attached files, available for download.
- **cURL command** — generated automatically for easy replay.

## Configuration

Send any HTTP request to Buggregator and mark it as a dump. Two ways:

### Using HTTP auth

Add `http-dump` to the URL username:

```bash
curl 'http://http-dump@127.0.0.1:8000/any/path?foo=bar'
```

### Using header

Add the `X-Buggregator-Event` header:

```bash
curl 'http://127.0.0.1:8000/any/path?foo=bar' \
  --header 'X-Buggregator-Event: http-dump'
```

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

---

# HTTP Proxy — Request & Response Capture

Your app calls external APIs — payment gateways, webhooks, third-party services — and you need to see both what
you send **and** what you get back. Buggregator's HTTP proxy sits between your app and the internet, capturing
full request/response pairs without changing your application code. Just point your HTTP client at the proxy.

> **Looking for one-way request capture?** See [HTTP Dumps](/config/http-dumps) — it captures incoming requests
> without proxying to a real server.

## Use cases

- **API debugging** — see exactly what your app sends to Stripe, Twilio, or any external API, and what comes back.
- **Webhook testing** — send webhooks through the proxy to inspect both the outgoing payload and the remote server's response.
- **Response inspection** — view response bodies with syntax highlighting (JSON, HTML, XML) and an interactive JSON tree view.
- **Performance monitoring** — see response times for every external call your app makes.
- **No code changes** — configure the proxy at the HTTP client level; your application logic stays untouched.

## What you see in the UI

Proxied requests appear as HTTP dump events with additional data:

- **Full URL** — the complete destination URL including host and port.
- **Request and response** — headers, body, and status code for both directions.
- **Status code** — color-coded badge (green for 2xx, amber for 4xx, red for 5xx).
- **Response time** — duration in milliseconds.
- **Proxy label** — purple badge to distinguish proxied requests from regular HTTP dumps.
- **Response body viewer** — JSON tree view with collapsible nodes, HTML preview in a sandboxed iframe, syntax highlighting for XML/CSS/JS.
- **Tab navigation** — Response, Request, and Raw tabs on the detail page.

## Configuration

The proxy listens on port **8080** by default. Configure it via environment variable or config file:

```dotenv
PROXY_ADDR=:8080
```

```yaml
# buggregator.yaml
tcp:
  proxy:
    addr: ":8080"
```

In Docker Compose, expose the port:

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - "8000:8000"   # UI + API
      - "8080:8080"   # HTTP Proxy
```

## Client setup

Point your HTTP client at `http://<buggregator-host>:8080` as a proxy. For HTTPS traffic, disable SSL certificate
verification — the proxy uses an in-memory CA to intercept TLS connections. This is safe for development.

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

### PHP — Guzzle

```php
use GuzzleHttp\Client;

$client = new Client([
    'proxy' => 'http://127.0.0.1:8080',
    'verify' => false,
]);

$response = $client->get('https://api.example.com/users');
```

### PHP — Laravel HTTP Client

```php
use Illuminate\Support\Facades\Http;

$response = Http::withOptions([
    'proxy' => 'http://127.0.0.1:8080',
    'verify' => false,
])->get('https://api.example.com/users');
```

To configure globally for all HTTP calls in development, add a macro in `AppServiceProvider`:

```php
// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Http;

public function boot(): void
{
    if ($this->app->isLocal()) {
        Http::globalOptions([
            'proxy' => env('BUGGREGATOR_PROXY_URL', 'http://127.0.0.1:8080'),
            'verify' => false,
        ]);
    }
}
```

```dotenv
BUGGREGATOR_PROXY_URL=http://buggregator:8080
```

### PHP — Symfony HttpClient

```php
use Symfony\Component\HttpClient\HttpClient;

$client = HttpClient::create([
    'proxy' => 'http://127.0.0.1:8080',
    'verify_peer' => false,
    'verify_host' => false,
]);

$response = $client->request('GET', 'https://api.example.com/users');
```

### Go

```go
import (
    "crypto/tls"
    "net/http"
    "net/url"
)

proxyURL, _ := url.Parse("http://127.0.0.1:8080")

client := &http.Client{
    Transport: &http.Transport{
        Proxy:           http.ProxyURL(proxyURL),
        TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
    },
}

resp, err := client.Get("https://api.example.com/users")
```

### JavaScript / Node.js — fetch

```js
import { ProxyAgent } from 'undici'

const agent = new ProxyAgent({
  uri: 'http://127.0.0.1:8080',
  requestTls: { rejectUnauthorized: false },
})

const response = await fetch('https://api.example.com/users', {
  dispatcher: agent,
})
```

### JavaScript / Node.js — axios

```js
import axios from 'axios'
import { HttpsProxyAgent } from 'https-proxy-agent'

const agent = new HttpsProxyAgent('http://127.0.0.1:8080', {
  rejectUnauthorized: false,
})

const response = await axios.get('https://api.example.com/users', {
  httpsAgent: agent,
})
```

### Python — requests

```python
import requests

response = requests.get(
    'https://api.example.com/users',
    proxies={'https': 'http://127.0.0.1:8080'},
    verify=False,
)
```

### Python — httpx

```python
import httpx

client = httpx.Client(
    proxy='http://127.0.0.1:8080',
    verify=False,
)

response = client.get('https://api.example.com/users')
```

### curl

```bash
curl -x http://127.0.0.1:8080 -k https://api.example.com/users
```

### Environment variables (any language)

Most HTTP clients respect standard proxy environment variables:

```bash
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080
export NODE_TLS_REJECT_UNAUTHORIZED=0  # Node.js only

# Then run your app normally
node app.js
python main.py
go run .
```

> **Note:** `NODE_TLS_REJECT_UNAUTHORIZED=0` disables TLS verification globally for Node.js processes.
> Use it only in development.

## How it works

1. Your app sends a request to the proxy (`http://127.0.0.1:8080`).
2. For HTTPS, the proxy performs a CONNECT handshake, generates a TLS certificate for the target host on the fly
   (signed by an in-memory CA), and establishes a TLS connection with your app.
3. The proxy forwards the request to the real destination server.
4. The full request and response are captured and stored as an `http-dump` event with a `proxy: true` flag,
   response data, and timing information.
5. The event appears in the Buggregator UI in real time via WebSocket.

The in-memory CA is generated at server startup and never written to disk. Your client skips certificate
verification (`InsecureSkipVerify`, `verify: false`, `-k`), so no CA installation is required.

## Docker Compose example

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - "8000:8000"
      - "8080:8080"

  app:
    build: .
    environment:
      BUGGREGATOR_PROXY_URL: http://buggregator:8080
    depends_on:
      - buggregator
```

---

# Inspector — Application Monitoring

You want to see how long your requests take, where the bottlenecks are, and how much memory each transaction
consumes — but [Inspector.dev](https://inspector.dev/) is overkill for local development. Buggregator accepts
the same Inspector SDK protocol, so your transaction and performance data lands in the same UI where you
already see exceptions, logs, and dumps.

![inspector](https://github.com/buggregator/server/assets/773481/ab002ecf-e1dc-4433-90d4-0e42ff8c0ab3)

## Use cases

- **Local APM** — monitor request duration and memory usage without sending data to external services.
- **Debug slow requests** — use the timeline breakdown to see which parts of a request are slow.
- **All in one place** — transaction data next to exceptions, logs, and dumps from the same app.

## What you see in the UI

- **Transaction name** — the name of the monitored transaction.
- **Duration** — execution time in milliseconds.
- **Memory peak** — peak memory usage.
- **Result status** — success, error, etc.
- **Transaction type** — HTTP request, process, etc.
- **HTTP details** — method, URI, host (for HTTP transactions).
- **Timeline breakdown** — visual timeline of events within the transaction.

## Configuration

### Laravel

Install the SDK: [docs.inspector.dev/laravel](https://docs.inspector.dev/laravel)

```dotenv
INSPECTOR_URL=http://inspector@127.0.0.1:8000
INSPECTOR_API_KEY=test
INSPECTOR_INGESTION_KEY=1test
INSPECTOR_ENABLE=true
```

> In Docker Compose: `INSPECTOR_URL=http://inspector@buggregator:8000`

### Other PHP

Using `inspector-apm/inspector-php`:

```php
use Inspector\Inspector;
use Inspector\Configuration;

$configuration = new Configuration('YOUR_INGESTION_KEY');
$configuration->setUrl('http://inspector@127.0.0.1:8000');
$inspector = new Inspector($configuration);
```

Other language SDKs: [docs.inspector.dev](https://docs.inspector.dev/)

## Secret key validation

To restrict access, set a secret key on the server:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e INSPECTOR_SECRET_KEY=my-secret-key \
  ghcr.io/buggregator/server:latest
```

Then use the key as the ingestion key in your client:

**Laravel:**

```dotenv
INSPECTOR_INGESTION_KEY=my-secret-key
```

**PHP:**

```php
$configuration = new Configuration('my-secret-key');
$configuration->setUrl('http://inspector@127.0.0.1:8000');
```

---

# Configuration — MCP (Model Context Protocol)

Buggregator includes a built-in [MCP](https://modelcontextprotocol.io/) server that lets AI assistants
query your debugging data directly. Connect Claude Code, Cursor, or any MCP-compatible client to browse
events, inspect errors, analyze profiling data, and read variable dumps — without leaving your editor.

## Enabling MCP

MCP is disabled by default. Enable it in `buggregator.yaml`:

```yaml
mcp:
  enabled: true
```

Or via environment variable:

```bash
MCP_ENABLED=true
```

## Transport Modes

### Unix Socket (Default)

The server listens on a Unix domain socket. This is the recommended mode for local development.

```yaml
mcp:
  enabled: true
  transport: socket
  socket_path: /tmp/buggregator-mcp.sock
```

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `socket` | Transport type |
| `MCP_SOCKET_PATH` | `/tmp/buggregator-mcp.sock` | Unix socket path |

### HTTP/SSE

For remote access or when Unix sockets are not available, use HTTP transport:

```yaml
mcp:
  enabled: true
  transport: http
  addr: ":8001"
  auth_token: my-secret-token     # Optional bearer token
```

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `socket` | Set to `http` |
| `MCP_ADDR` | `:8001` | HTTP listen address |
| `MCP_AUTH_TOKEN` | — | Bearer token for authentication (optional) |

When `MCP_AUTH_TOKEN` is set, all requests must include the `Authorization: Bearer <token>` header.

## Integration with AI Assistants

### Claude Code

Add to your `.mcp.json` or configure via Claude Code settings:

```json
{
  "mcpServers": {
    "buggregator": {
      "command": "./buggregator",
      "args": ["mcp"]
    }
  }
}
```

The `buggregator mcp` subcommand bridges stdio to the running Buggregator instance via the Unix socket.

> **Note:** Make sure Buggregator is running with MCP enabled before connecting.

If Buggregator runs in Docker, you can use the HTTP transport instead:

```json
{
  "mcpServers": {
    "buggregator": {
      "type": "url",
      "url": "http://localhost:8001/mcp"
    }
  }
}
```

### Cursor

In Cursor settings, add the MCP server:

- **Command:** `./buggregator mcp`
- Or use the HTTP URL: `http://localhost:8001/mcp`

### Docker Setup

When running Buggregator in Docker with MCP enabled:

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:8001:8001    # MCP HTTP port
    environment:
      MCP_ENABLED: "true"
      MCP_TRANSPORT: http
      MCP_ADDR: ":8001"
```

## Available Tools

MCP clients can use the following tools to query Buggregator data:

### Event Management

| Tool | Description |
|------|-------------|
| `events_list` | List events with optional filtering by type and project. Returns metadata (uuid, type, timestamp, project) without payloads. Supports `limit` parameter (default 20, max 100). |
| `event_get` | Get a complete event by UUID, including the full payload. |
| `event_delete` | Delete an event by UUID. |

### Sentry

| Tool | Description |
|------|-------------|
| `sentry_event` | Get structured details of a Sentry error: message, severity, exception chain with stack traces, environment, platform. Returns clean, AI-friendly data. |

### VarDumper

| Tool | Description |
|------|-------------|
| `vardump_get` | Get a variable dump with HTML stripped for clean AI consumption. Returns variable type, label, and plain text representation. |

### Profiler

| Tool | Description |
|------|-------------|
| `profiler_summary` | Quick overview: total CPU/wall time/memory, slowest function, biggest memory consumer, most called function. |
| `profiler_top` | Top functions sorted by metric (cpu, wt, mu, pmu, ct, and their exclusive variants). Returns inclusive and exclusive metrics with percentages. |
| `profiler_call_graph` | Filtered call graph showing function relationships. Use `threshold` and `percentage` to control which nodes are shown. |

### Example Usage in Claude Code

Once connected, you can ask your AI assistant things like:

- "Show me the latest Sentry errors"
- "What's the stack trace for this exception?"
- "Analyze the profiling data and find the slowest functions"
- "What value was dumped in the last VarDumper event?"

---

# Configuration — Metrics

Buggregator collects metrics on how many events it receives. This feature lets you use tools like
Prometheus and Grafana to check on event trends, find issues, and set up alerts.

The metrics system keeps track of how many events Buggregator receives, sorted by their types:
sentry, monolog, var-dumper, ray, inspector, http-dump, profiler, and smtp. HTTP request metrics,
WebSocket connection gauges, and webhook delivery attempts are also tracked.

### How It Works

1. **Event Counting:** Each time an event is received, it's counted and sorted into its type.
2. **Metric Updating:** The system updates the metrics to show the latest counts for each event type.

## Enabling Metrics

Metrics are disabled by default. Enable them via environment variable or config file:

```bash
METRICS_ENABLED=true
```

Or in `buggregator.yaml`:

```yaml
metrics:
  enabled: true
```

## Prometheus Endpoint

There are two ways to expose the Prometheus endpoint:

### Option 1: On the Main HTTP Server (Default)

When `METRICS_ADDR` is not set, metrics are served at `/metrics` on the main HTTP server (port 8000 by default):

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e METRICS_ENABLED=true \
  ghcr.io/buggregator/server:latest
```

Access metrics at `http://127.0.0.1:8000/metrics`.

### Option 2: On a Separate Server

For production environments where you want to keep metrics on a separate port:

```yaml
metrics:
  enabled: true
  addr: ":9090"
```

Or via environment variable:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9090:9090 \
  -e METRICS_ENABLED=true \
  -e METRICS_ADDR=:9090 \
  ghcr.io/buggregator/server:latest
```

Access metrics at `http://127.0.0.1:9090/metrics`.

## Metric Format

Here is what the metric format looks like:

```plaintext
# HELP events The total number of received events.
# TYPE events counter
events{type="sentry"} 10
events{type="smtp"} 1
```

Each line shows how many events of a specific type have been received.

## Grafana Integration

You can use these metrics to make dashboards in Grafana. This helps you see the data in a way that makes sense for you.

### Setting Up Grafana

1. **Add Prometheus as a Data Source:** First, connect Prometheus (which scrapes your Buggregator metrics) to Grafana.
2. **Create Dashboards:** Next, create dashboards in Grafana to show the metrics. You can make graphs and charts that
   help you understand the event trends.

---

# Monolog — Logs

Your app writes logs — but where do they go during development? A file you `tail -f`? Docker container output
you scroll through? With Buggregator, logs from all your services land in the same UI where you already see
exceptions, dumps, and emails. Filter by level, see structured context, click on source locations — all without
setting up Elasticsearch or a separate logging stack.

![monolog](https://github.com/buggregator/server/assets/773481/21919110-fd4d-490d-a78e-41242d329885)

## Use cases

- **Structured log viewer** — see context and extra fields as formatted JSON, not a raw string in a terminal.
- **Multi-service logging** — collect logs from all containers in one place.
- **Debug long-running apps** — workers, daemons, and queue consumers write logs that are easy to miss in stdout. Buggregator catches them all.
- **All in one place** — correlate logs with exceptions and dumps from the same request flow.

## What you see in the UI

- **Channel** — the logger channel (`app`, `security`, `database`, etc.).
- **Message** — the log message.
- **Severity level** — all PSR-3 levels: emergency, alert, critical, error, warning, notice, info, debug.
- **Timestamp** — when the log was recorded.
- **Context** — structured context data in JSON format.
- **Extra fields** — additional data from Monolog processors.
- **Source** — file, line, and function where the log was generated.

## Configuration

Buggregator receives logs via Monolog's `SocketHandler` on port **9913**. The formatter **must** be `JsonFormatter`.

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

### Laravel

```php
// config/logging.php
return [
    // ...
    'channels' => [
        // ...
        'socket' => [
            'driver' => 'monolog',
            'level' => env('LOG_LEVEL', 'debug'),
            'handler' => \Monolog\Handler\SocketHandler::class,
            'formatter' => \Monolog\Formatter\JsonFormatter::class,
            'handler_with' => [
                'connectionString' => env('LOG_SOCKET_URL', '127.0.0.1:9913'),
            ],
        ],
    ],
];
```

```dotenv
LOG_CHANNEL=socket
LOG_SOCKET_URL=127.0.0.1:9913
```

### Spiral Framework

```php
<?php

declare(strict_types=1);

namespace App\Bootloader;

use Monolog\Formatter\JsonFormatter;
use Monolog\Handler\SocketHandler;
use Spiral\Boot\Bootloader\Bootloader;
use Spiral\Boot\EnvironmentInterface;
use Spiral\Monolog\Bootloader\MonologBootloader;

class LoggingBootloader extends Bootloader
{
    public function init(MonologBootloader $monolog, EnvironmentInterface $env): void
    {
        $handler = new SocketHandler($env->get('MONOLOG_SOCKET_HOST'), chunkSize: 10);
        $handler->setFormatter(new JsonFormatter(JsonFormatter::BATCH_MODE_NEWLINES));
        $monolog->addHandler('socket', $handler);
    }
}
```

```dotenv
MONOLOG_DEFAULT_CHANNEL=socket
MONOLOG_SOCKET_HOST=127.0.0.1:9913
```

### Symfony

```php
# config/packages/dev/monolog.php
<?php

namespace Symfony\Component\DependencyInjection\Loader\Configurator;

use Symfony\Config\MonologConfig;

return static function (MonologConfig $monologConfig): void {
    $monologConfig
        ...
        ->handler('socket')
            ->level('debug')
            ->formatter('monolog.formatter.json')
            ->type('socket')
            ->connectionString(env('MONOLOG_SOCKET_HOST'));
};
```

```dotenv
MONOLOG_SOCKET_HOST=127.0.0.1:9913
```

> **Important:** The `monolog.formatter.json` formatter is required. Without it, Buggregator cannot parse the log records.

### Any PHP project

```bash
composer require monolog/monolog
```

```php
<?php

use Monolog\Logger;
use Monolog\Handler\SocketHandler;
use Monolog\Formatter\JsonFormatter;

$log = new Logger('buggregator');
$handler = new SocketHandler('127.0.0.1:9913');
$handler->setFormatter(new JsonFormatter());
$log->pushHandler($handler);

$log->warning('Foo');
$log->error('Bar');
```

---

# JetBrains IDE Plugin

You use PhpStorm (or another JetBrains IDE) and don't want to switch to a browser to check dumps and logs.
The Buggregator plugin embeds the full debug UI directly into your IDE — dumps, logs, exceptions, and profiling
data appear in a panel next to your code. All IDE shortcuts keep working. No context switching.

**Plugin repository:** https://github.com/buggregator/phpstorm-plugin

## How it works

The plugin launches [Buggregator Trap](/trap/what-is-trap) from your project's `vendor` directory using the PHP
interpreter configured in your IDE. Trap starts collecting debug data and the plugin displays it in two tabs:

- **Web UI** — the full interactive Buggregator interface in the IDE's built-in browser. Same UI as the standalone server.
- **Terminal** — text-based output for quick inspection.

Trap opens a web interface port (configurable in settings), which works with all standard clients — VarDumper,
Monolog, Sentry, Ray, and others.

> **Tip:** If you have the plugin running in multiple IDE windows with the same port, both Web UIs share the same
> Trap instance. A second Trap will wait until the port is free.

## Requirements

- [buggregator/trap](https://github.com/buggregator/trap) installed in your project (`composer require --dev buggregator/trap`)
- A PHP interpreter configured in your IDE settings

## Installation

### From JetBrains Marketplace (recommended)

Go to the [plugin page](https://plugins.jetbrains.com/plugin/26344-buggregator) and click **Install to ...**

### From IDE

**Settings** > **Plugins** > **Marketplace** > search for **"Buggregator"** > **Install**

### Manual

1. Download the `.jar` file from [GitHub Releases](https://github.com/buggregator/phpstorm-plugin/releases) or [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/26344-buggregator/versions).
2. **Settings** > **Plugins** > **⚙️** > **Install plugin from disk...** > select the `.jar` file.
3. Restart the IDE if prompted.

After installation, find the **Buggregator** button in the top right corner of the IDE window.

## Configuration

Open the plugin settings to customize:

- **PHP interpreter** — which PHP binary to use for running Trap.
- **Path to Trap** — defaults to `vendor/bin/trap`, change if needed.
- **Web UI port** — the port for the embedded web interface.

Click the **🌐** button on the toolbar to open the Web UI in your system browser instead of the IDE.

## Supported IDEs

The plugin works with all JetBrains IDEs that support PHP development:

- PhpStorm
- IntelliJ IDEA (with PHP plugin)
- WebStorm
- And other JetBrains products

---

# Configuration — Projects

Buggregator lets you use "projects" to help organize your data. Projects are useful for keeping events from
different teams, applications, or environments separate.

![image](https://github.com/user-attachments/assets/cde794f7-83fb-4708-9eef-713c6f8be7cc)

**Here's why you might want to use projects:**

1. Projects help you keep data from different teams or parts of your app separate. This means it's easier to find what
   you're looking for and keep track of changes.
2. Teams won't get mixed up with data that isn't relevant to them, which makes their work faster and less confusing.
3. The sidebar displays a project selector dropdown, allowing you to quickly switch between projects and view only
   the events relevant to the selected project.

### Default Project

When you start the server, Buggregator automatically sets up a default project with key `default`. All your data goes
into this `default` project if a project key is not specified in the request.

## Configuration

Projects are configured in `buggregator.yaml`:

```yaml
projects:
  - key: my-app
    name: My Application
  - key: staging
    name: Staging Environment
  - key: mobile
    name: Mobile App
```

### Docker Compose Example

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

With `buggregator.yaml`:

```yaml
projects:
  - key: backend
    name: Backend API
  - key: frontend
    name: Frontend App
```

## Sentry Configuration

To use Sentry with your project, format your DSN like this:

```dotenv
SENTRY_DSN=http://<secret_key>@127.0.0.1:8000/<project_key>
```

> **Note:** Read more about Sentry configuration [here](/config/sentry.html).

## Inspector Configuration

To use Inspector with your project, format your DSN like this:

```dotenv
INSPECTOR_URL=http://inspector:<project_key>@127.0.0.1:8000
INSPECTOR_API_KEY=<secret_key>
```

> **Note:** Read more about Inspector configuration [here](/config/inspector.html).

## Xhprof Profiler Configuration

To set up the Profiler, use this:

```dotenv
PROFILER_ENDPOINT=http://profiler:<project_key>@127.0.0.1:8000
```

> **Note:** Read more about Xhprof Profiler configuration [here](/config/xhprof.html).

## Ray Configuration

For Ray, use these settings:

```dotenv
RAY_HOST=ray:<project_key>@127.0.0.1
RAY_PORT=8000
```

## VarDumper Configuration

At this moment, VarDumper does not support projects.

## Monolog Configuration

At this moment, Monolog does not support projects.

---

# Ray — Debug Tool

[Ray](https://myray.app/) by Spatie is a popular debug tool, especially in the Laravel ecosystem. Buggregator is
a free, self-hosted alternative — you get the same `ray()` calls, but the data lands in Buggregator alongside
your exceptions, logs, emails, and profiling. One place for everything.

![ray](https://github.com/buggregator/server/assets/773481/168b27f7-75b1-4837-b0a1-37146d5b8b52)

## Use cases

- **Free Ray alternative** — no license needed. Same `ray()` function, same workflow.
- **Multi-language debugging** — Ray has SDKs for PHP, JavaScript, Ruby, Go, and Bash. All output goes to Buggregator.
- **Laravel debugging** — dump Eloquent models, SQL queries, jobs, mail, events, and more with type-specific rendering.
- **All debug data in one UI** — don't switch between Ray app, Sentry, log files, and Mailhog. It's all in Buggregator.

## Supported payload types

Buggregator renders 18 Ray payload types:

| Type | What it shows |
|---|---|
| **Log** | Text logging |
| **Custom** | Custom data dumps |
| **Caller** | Call origin (file, line, function) |
| **Carbon** | Carbon date/time objects |
| **Trace** | Full stack trace |
| **Exception** | Exception with stack trace |
| **Table** | Structured data as a table |
| **Measure** | Performance timing |
| **Query** | SQL query with bindings |
| **Eloquent** | Eloquent model data |
| **Application Log** | Application log entries |
| **View** | Template rendering info |
| **Event** | Application events |
| **Job** | Queue job details |
| **Lock** | Lock status |
| **Mailable** | Laravel Mail preview |
| **Notify** | Notification data |
| **Origin** | Call origin info |

Each payload shows its origin (file, line, function). Click file paths to open in your IDE.

## Configuration

### Laravel

Publish the Ray config:

```bash
php artisan ray:publish-config
```

Set env variables:

```dotenv
RAY_HOST=ray@127.0.0.1
RAY_PORT=8000
```

> In Docker Compose: `RAY_HOST=ray@buggregator`, `RAY_PORT=8000`.

### PHP (any framework)

Create a `ray.php` file in your project root:

```php
<?php

return [
    'enable' => true,
    'host' => 'ray@127.0.0.1',
    'port' => 8000,
    'remote_path' => null,
    'local_path' => null,
    'always_send_raw_values' => false,
];
```

### Other languages

- [JavaScript](https://myray.app/docs/javascript/vanilla-javascript/getting-started)
- [Ruby](https://myray.app/docs/other-languages/ruby/getting-started)
- [Go](https://myray.app/docs/other-languages/go/getting-started)
- [Bash](https://myray.app/docs/other-languages/bash/installation)

---

# 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](https://github.com/buggregator/server/assets/773481/e979fda5-54c8-42cc-8224-a1c5d828569a)

## 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, URI, headers, cookies, POST data.
- **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](https://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](https://spiral.dev/docs/extension-sentry/3.3/en)

### Symfony

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

Install the SDK: [docs.sentry.io/platforms/php/guides/symfony](https://docs.sentry.io/platforms/php/guides/symfony/)

### Magento 2

Using [justbetter/magento2-sentry](https://github.com/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](https://localwp.com/) does that by default.

1. Install [WP Sentry](https://wordpress.org/plugins/wp-sentry-integration/) (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

Use the official [Sentry JavaScript SDK](https://docs.sentry.io/platforms/javascript/) and point the DSN at Buggregator:

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

### Other platforms

Any [Sentry SDK](https://docs.sentry.io/platforms/) works. Just set the DSN:

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

---

# Configuration — Server

Buggregator is configured through a combination of a YAML config file, environment variables, and CLI flags.
Every setting has a sensible default — no configuration file is required to get started.

## Configuration Priority

Settings are resolved in this order (highest priority first):

1. **CLI flags** (e.g., `--http-addr :9000`)
2. **Environment variables** (e.g., `HTTP_ADDR=:9000`)
3. **Config file** (`buggregator.yaml`)
4. **Defaults**

## Config File

Place a file named `buggregator.yaml` (or `buggregator.yml`) next to the binary, or specify a custom path:

```bash
./buggregator --config /path/to/buggregator.yaml
```

The config file supports environment variable substitution using `${VAR}` or `${VAR:default}` syntax.

### Full Example

```yaml
# HTTP server
server:
  addr: ${HTTP_ADDR::8000}
  cors_origins:
    - "*"

# Database (SQLite)
database:
  driver: sqlite
  dsn: ${DATABASE_DSN::memory:}       # ":memory:" or file path like "data.db"

# Attachment storage (SMTP attachments, HTTP dump files)
storage:
  mode: ${STORAGE_MODE:memory}        # "memory" or "filesystem"
  path: ${STORAGE_PATH:./storage}     # Directory for filesystem mode

# TCP servers
tcp:
  smtp:
    addr: ${SMTP_ADDR::1025}
  monolog:
    addr: ${MONOLOG_ADDR::9913}
  var-dumper:
    addr: ${VAR_DUMPER_ADDR::9912}

# Enable/disable modules
modules:
  sentry: true
  ray: true
  var-dump: true
  inspector: true
  monolog: true
  smtp: true
  sms: true
  http-dump: true
  profiler: true

# Prometheus metrics
metrics:
  enabled: ${METRICS_ENABLED:false}
  addr: ${METRICS_ADDR:}              # Separate server, e.g. ":9090". Empty = serve on main HTTP server.

# Authentication (OAuth2/OIDC)
# auth:
#   enabled: false
#   provider: oidc
#   provider_url: https://xxx.us.auth0.com
#   client_id: xxx
#   client_secret: xxx
#   callback_url: http://localhost:8000/auth/sso/callback
#   scopes: openid,email,profile
#   jwt_secret: my-secret-key

# MCP (Model Context Protocol) for AI assistants
# mcp:
#   enabled: false
#   transport: socket                  # "socket" or "http"
#   socket_path: /tmp/buggregator-mcp.sock
#   addr: :8001                        # For HTTP transport
#   auth_token:                        # Bearer token for HTTP transport

# Webhooks
# webhooks:
#   - event: "*"
#     url: https://slack.example.com/webhook
#     headers:
#       Authorization: "Bearer token"
#     verify_ssl: false
#     retry: true

# Pre-defined projects
# projects:
#   - key: my-app
#     name: My Application
```

---

## Environment Variables Reference

### HTTP Server

| Variable | Default | Description |
|----------|---------|-------------|
| `HTTP_ADDR` | `:8000` | HTTP server listen address |
| `CORS_ORIGINS` | `*` | Comma-separated list of allowed CORS origins |

### Database

| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_DSN` | `:memory:` | SQLite database path. Use `:memory:` for in-memory (data lost on restart) or a file path like `data.db` for persistence. |

### Attachment Storage

| Variable | Default | Description |
|----------|---------|-------------|
| `STORAGE_MODE` | `memory` | `memory` (lost on restart) or `filesystem` (persistent) |
| `STORAGE_PATH` | `./storage` | Directory for filesystem storage mode |

### TCP Ports

| Variable | Default | Description |
|----------|---------|-------------|
| `SMTP_ADDR` | `:1025` | SMTP server listen address |
| `MONOLOG_ADDR` | `:9913` | Monolog TCP server listen address |
| `VAR_DUMPER_ADDR` | `:9912` | VarDumper TCP server listen address |

### Modules

| Variable | Default | Description |
|----------|---------|-------------|
| `CLIENT_SUPPORTED_EVENTS` | all | Comma-separated list of enabled module types (e.g., `sentry,ray,smtp`) |

### Metrics

| Variable | Default | Description |
|----------|---------|-------------|
| `METRICS_ENABLED` | `false` | Enable Prometheus metrics |
| `METRICS_ADDR` | (empty) | Separate metrics server address (e.g., `:9090`). Leave empty to serve `/metrics` on the main HTTP server. |

### Authentication

| Variable | Default | Description |
|----------|---------|-------------|
| `AUTH_ENABLED` | `false` | Enable OAuth2/OIDC authentication |
| `AUTH_PROVIDER` | `oidc` | Provider: `auth0`, `google`, `github`, `keycloak`, `gitlab`, `oidc` |
| `AUTH_PROVIDER_URL` | — | OIDC issuer URL (e.g., `https://xxx.us.auth0.com`) |
| `AUTH_CLIENT_ID` | — | OAuth2 client ID |
| `AUTH_CLIENT_SECRET` | — | OAuth2 client secret |
| `AUTH_CALLBACK_URL` | — | Callback URL (e.g., `http://localhost:8000/auth/sso/callback`) |
| `AUTH_SCOPES` | `openid,email,profile` | Comma-separated OAuth2 scopes |
| `AUTH_JWT_SECRET` | — | Secret for signing internal JWT tokens (required when auth is enabled) |

### MCP (Model Context Protocol)

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_ENABLED` | `false` | Enable MCP server for AI assistant integration |
| `MCP_TRANSPORT` | `socket` | Transport type: `socket` (Unix socket) or `http` (HTTP/SSE) |
| `MCP_SOCKET_PATH` | `/tmp/buggregator-mcp.sock` | Unix socket path (for socket transport) |
| `MCP_ADDR` | `:8001` | HTTP listen address (for HTTP transport) |
| `MCP_AUTH_TOKEN` | — | Bearer token for HTTP transport authentication |

### Other

| Variable | Default | Description |
|----------|---------|-------------|
| `FRONTEND_DIR` | — | Serve frontend from disk instead of embedded (for development) |

---

## Docker Examples

### Using Environment Variables

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -e DATABASE_DSN=data.db \
  -e METRICS_ENABLED=true \
  -v ./data:/data \
  ghcr.io/buggregator/server:latest
```

### Using a Config File

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -v ./buggregator.yaml:/buggregator.yaml \
  ghcr.io/buggregator/server:latest
```

### Docker Compose with All Options

```yaml
services:
  buggregator:
    image: ghcr.io/buggregator/server:latest
    ports:
      - 127.0.0.1:8000:8000
      - 127.0.0.1:1025:1025
      - 127.0.0.1:9912:9912
      - 127.0.0.1:9913:9913
    environment:
      DATABASE_DSN: data.db
      STORAGE_MODE: filesystem
      STORAGE_PATH: /data/storage
      METRICS_ENABLED: "true"
    volumes:
      - buggregator-data:/data

volumes:
  buggregator-data:
```

## Disabling Modules

You can disable modules you don't need. Disabled modules won't bind their TCP port and will ignore incoming events.

In `buggregator.yaml`:

```yaml
modules:
  sentry: true
  ray: true
  var-dump: false    # Disable VarDumper
  inspector: false   # Disable Inspector
  monolog: true
  smtp: true
  sms: false         # Disable SMS
  http-dump: true
  profiler: true
```

Or via environment variable:

```bash
CLIENT_SUPPORTED_EVENTS=sentry,ray,monolog,smtp,http-dump,profiler
```

---

# SMS Gateway Interceptor

Your app sends SMS messages — OTP codes, delivery notifications, alerts. During development you don't want to send
real messages through Twilio or Vonage. Buggregator acts as a fake SMS gateway: point your app's SMS webhook URL at
Buggregator and every message shows up in the UI — with sender, recipient, message text, and detected provider.

## Use cases

- **OTP testing** — verify that verification codes are generated and sent correctly.
- **Notification preview** — see the exact text your users will receive.
- **Provider migration** — switch between Twilio, Vonage, Plivo etc. and verify the payload format.
- **Validation feedback** — use explicit provider URLs to catch missing required fields before going to production.

## How it works

Buggregator exposes a single `/sms` endpoint. When your app sends an HTTP POST with SMS data, Buggregator:

1. **Auto-detects the provider** by inspecting request body fields (e.g. `MessageSid` → Twilio, `api_key`+`api_secret` → Vonage).
2. **Extracts** `from`, `to`, and `message` using provider-specific field mappings.
3. **Displays** the SMS in the UI with a colored provider badge.

If the payload doesn't match any known provider, the generic fallback tries common field names (`from`/`to`/`message`/`body`/`text`).

### Explicit provider URL

You can also specify the provider in the URL for stricter validation:

```
POST /sms/twilio       → forces Twilio field mapping + validates required fields
POST /sms/vonage       → forces Vonage field mapping + validates required fields
POST /sms              → auto-detects provider from payload
```

When using an explicit provider URL, Buggregator validates that all required fields are present. If something is missing:
- The HTTP response returns **422** with a JSON error listing missing fields.
- The event is **still captured** in the UI with validation warnings highlighted in red.

This way your app sees the error (like it would from a real provider), and you can inspect the full payload in Buggregator.

### Project support

Append a project name as an additional URL segment:

```
POST /sms/twilio/myproject    → explicit provider + project
POST /sms/myproject           → auto-detect + project
```

## Supported providers

Over 40 providers are auto-detected. Here are the most common ones:

| Provider | Detect fields | From | To | Message |
|----------|--------------|------|-----|---------|
| Twilio | `MessageSid`, `Body` | `From` | `To` | `Body` |
| Vonage | `api_key`, `api_secret` | `from`, `msisdn` | `to` | `text` |
| Plivo | `MessageUUID` | `From`, `src` | `To`, `dst` | `Text` |
| Sinch | `batch_id`, `body` | `from` | `to` | `body` |
| Infobip | `messages` | `from` | `to` | `text` |
| MessageBird | `originator`, `recipients` | `originator` | `recipients` | `body` |
| Telnyx | `messaging_profile_id` | `from` | `to` | `text` |
| Bandwidth | `applicationId`, `text` | `from` | `to` | `text` |
| Brevo | `sender`, `recipient`, `content` | `sender` | `recipient` | `content` |
| Clickatell | `from`, `to`, `text` | `from` | `to` | `text` |
| SMS.ru | `api_id`, `msg` | `from` | `to` | `msg` |
| SMSC | `login`, `psw`, `phones` | `sender` | `phones` | `mes` |
| Generic | _(always matches)_ | `from`/`From`/`sender` | `to`/`To`/`recipient` | `message`/`body`/`text` |

Full list: Twilio, Vonage, Plivo, Sinch, Infobip, MessageBird, Telnyx, Bandwidth, Brevo, Termii, Clickatell, MessageMedia, Lox24, Unifonic, Yunpian, Octopush, GatewayApi, SevenIo, SmsFactor, Redlink, OvhCloud, Smsc, 46elks, Mobyt, Smsapi, Sendberry, TurboSms, SimpleTextin, Isendpro, RingCentral, ClickSend, SMS.ru, SMS Aero, Devino, IQSms, MTS, Beeline, Megafon.

## Configuration

### Symfony Notifier

Symfony's Notifier component uses DSN-based transport configuration. Every SMS bridge has a configurable host — change it to point at Buggregator.

```dotenv
# Default (sends to real Twilio):
TWILIO_DSN=twilio://SID:TOKEN@default?from=+1234567890

# Point to Buggregator (explicit provider URL for validation):
TWILIO_DSN=twilio://SID:TOKEN@127.0.0.1:8000/sms/twilio?from=+1234567890

# Or use auto-detect:
TWILIO_DSN=twilio://SID:TOKEN@127.0.0.1:8000/sms?from=+1234567890
```

Same pattern for any Symfony SMS bridge:

```dotenv
# Vonage
VONAGE_DSN=vonage://KEY:SECRET@127.0.0.1:8000/sms/vonage?from=MyApp

# Plivo
PLIVO_DSN=plivo://AUTH_ID:AUTH_TOKEN@127.0.0.1:8000/sms/plivo?from=+1234567890

# Sinch
SINCH_DSN=sinch://ACCOUNT_ID:AUTH_TOKEN@127.0.0.1:8000/sms/sinch?from=+1234567890
```

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

### Laravel

Laravel doesn't have built-in SMS, but if you use an HTTP-based SMS package, you can override the API base URL:

```php
// Example: sending directly via HTTP
Http::post('http://127.0.0.1:8000/sms/twilio', [
    'MessageSid' => Str::uuid(),
    'From' => '+1234567890',
    'To' => $user->phone,
    'Body' => "Your code is {$code}",
]);
```

### Any language / any framework

Send an HTTP POST to Buggregator with the provider's payload format:

```bash
# Twilio format
curl -X POST http://127.0.0.1:8000/sms/twilio \
  -H "Content-Type: application/json" \
  -d '{"MessageSid":"SM123","From":"+1234","To":"+5678","Body":"Hello!"}'

# Generic format (auto-detect)
curl -X POST http://127.0.0.1:8000/sms \
  -H "Content-Type: application/json" \
  -d '{"from":"+1234","to":"+5678","message":"Hello!"}'

# Test validation (missing required fields)
curl -X POST http://127.0.0.1:8000/sms/twilio \
  -H "Content-Type: application/json" \
  -d '{"From":"+1234","To":"+5678"}'
# Returns 422: {"error":"validation_failed","gateway":"twilio","missing_fields":["MessageSid","Body"]}
# But the event is still visible in Buggregator UI with warnings!
```

Both `application/json` and `application/x-www-form-urlencoded` are accepted.

---

# SMTP — Email Testing

Your app sends emails — registration confirmations, password resets, notifications. You need to verify they look
correct without actually delivering them. Buggregator includes a fake SMTP server: point your app's mail config at
port `1025` and every email shows up in the UI. No Mailhog, no Mailtrap, no external services — just another
module in the same Buggregator instance where you already see your logs and exceptions.

![smtp](https://github.com/buggregator/server/assets/773481/8dd60ddf-c8d8-4a26-a8c0-b05052414a5f)

## Use cases

- **Email template testing** — preview HTML emails with a desktop/mobile viewport switcher to check responsive layouts.
- **Transactional email verification** — make sure the right recipients, subject, and content are set before going to production.
- **Attachment testing** — verify that attachments are generated correctly and can be downloaded.
- **All in one place** — see emails next to the exceptions, logs, and dumps from the same request flow.

## What you see in the UI

- **HTML preview** — rendered email with desktop/mobile device viewport switcher.
- **Plain text** — the plain text version of the email.
- **Addresses** — From, To, CC, BCC, Reply-To organized by type.
- **Attachments** — download or preview any attached file. Inline images display correctly in the HTML preview.
- **Raw source** — the raw MIME source for debugging encoding or header issues.

## Configuration

Point your app's SMTP settings to `127.0.0.1:1025`. No authentication required.

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

### Laravel

```dotenv
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
```

### Spiral Framework

```dotenv
MAILER_DSN=smtp://127.0.0.1:1025
```

### Symfony

```dotenv
MAILER_DSN=smtp://127.0.0.1:1025
```

### Magento 2

```dotenv
CONFIG__DEFAULT__SYSTEM__SMTP__TRANSPORT="smtp"
CONFIG__DEFAULT__SYSTEM__SMTP__HOST="127.0.0.1"
CONFIG__DEFAULT__SYSTEM__SMTP__PORT="1025"
```

or via CLI:

```bash
bin/magento config:set system/smtp/transport smtp
bin/magento config:set system/smtp/host 127.0.0.1
bin/magento config:set system/smtp/port 1025
```

### WordPress

Save to the [mu-plugins](https://developer.wordpress.org/advanced-administration/plugins/mu-plugins/) directory (e.g., `smtp.php`):

```php
<?php
/**
 * Plugin Name: MU Buggregator SMTP
 */

if (! defined('WP_ENVIRONMENT_TYPE') || 'local' !== WP_ENVIRONMENT_TYPE) {
	return;
}

add_action( 'phpmailer_init', function( $phpmailer ) : void {
	$phpmailer->isSMTP();
    $phpmailer->Host = '127.0.0.1';
    $phpmailer->Port = 1025;
}  );
```

### Any other app

Any application that can send email via SMTP works. Set host to `127.0.0.1` and port to `1025`.

---

# Configuration — Single Sign-On (SSO)

Buggregator supports Single Sign-On (SSO) for secure user authentication via OAuth2/OIDC.

Supported providers:

- [Auth0](https://auth0.com/)
- [Google](https://console.cloud.google.com/)
- [GitHub](https://github.com/settings/developers)
- [Keycloak](https://www.keycloak.org/)
- [GitLab](https://gitlab.com/)
- Any **generic OIDC** provider

For OIDC-compatible providers (Auth0, Google, Keycloak, GitLab, generic OIDC), endpoints are auto-discovered
from the provider URL via `.well-known/openid-configuration`. For GitHub, endpoints are hardcoded (GitHub does
not support OIDC discovery).

## Configuration

### buggregator.yaml

```yaml
auth:
  enabled: true
  provider: oidc                    # auth0, google, github, keycloak, gitlab, oidc
  provider_url: https://xxx.us.auth0.com
  client_id: your-client-id
  client_secret: your-client-secret
  callback_url: http://localhost:8000/auth/sso/callback
  scopes: openid,email,profile
  jwt_secret: your-jwt-signing-secret
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `AUTH_ENABLED` | `false` | Enable authentication |
| `AUTH_PROVIDER` | `oidc` | Provider type: `auth0`, `google`, `github`, `keycloak`, `gitlab`, `oidc` |
| `AUTH_PROVIDER_URL` | — | OIDC issuer URL (e.g., `https://xxx.us.auth0.com`) |
| `AUTH_CLIENT_ID` | — | OAuth2 client ID |
| `AUTH_CLIENT_SECRET` | — | OAuth2 client secret |
| `AUTH_CALLBACK_URL` | — | Callback URL (e.g., `http://buggregator.example.com/auth/sso/callback`) |
| `AUTH_SCOPES` | `openid,email,profile` | Comma-separated OAuth2 scopes |
| `AUTH_JWT_SECRET` | — | **Required.** Secret for signing internal JWT tokens |

> **Important:** `AUTH_JWT_SECRET` is required when authentication is enabled. It is used to sign the internal
> session JWT tokens.

## Provider Setup

### Auth0

1. [Sign up](https://auth0.com/signup) for an Auth0 account.
2. Create a new **Regular Web Application**.
3. Note the `Domain`, `Client ID`, and `Client Secret`.
4. In application settings, set **Allowed Callback URLs** to `http://<your-server>/auth/sso/callback`.
5. Configure Buggregator:

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=auth0
AUTH_PROVIDER_URL=https://<domain>.auth0.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_SCOPES=openid,email,profile
AUTH_JWT_SECRET=your-secret-key
```

### Google

1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials).
2. Create a new **OAuth 2.0 Client ID** (Web application type).
3. Add `http://<your-server>/auth/sso/callback` to **Authorized redirect URIs**.
4. Configure Buggregator:

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=google
AUTH_PROVIDER_URL=https://accounts.google.com
AUTH_CLIENT_ID=xxx.apps.googleusercontent.com
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

### GitHub

1. Go to [GitHub Developer Settings](https://github.com/settings/developers).
2. Create a new **OAuth App**.
3. Set **Authorization callback URL** to `http://<your-server>/auth/sso/callback`.
4. Configure Buggregator:

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=github
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

> **Note:** GitHub does not support OIDC, so `AUTH_PROVIDER_URL` is not needed.

### Keycloak

1. Create a new **Client** in your Keycloak realm.
2. Set **Valid Redirect URIs** to `http://<your-server>/auth/sso/callback`.
3. Configure Buggregator:

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=keycloak
AUTH_PROVIDER_URL=https://keycloak.example.com/realms/your-realm
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

### GitLab

1. Go to **Admin Area > Applications** (or **User Settings > Applications** for self-managed).
2. Create a new application with `openid`, `email`, `profile` scopes.
3. Set **Redirect URI** to `http://<your-server>/auth/sso/callback`.
4. Configure Buggregator:

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=gitlab
AUTH_PROVIDER_URL=https://gitlab.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

### Generic OIDC

Any OIDC-compliant provider can be used. The server will auto-discover endpoints from
`<provider_url>/.well-known/openid-configuration`.

```dotenv
AUTH_ENABLED=true
AUTH_PROVIDER=oidc
AUTH_PROVIDER_URL=https://your-oidc-provider.com
AUTH_CLIENT_ID=xxx
AUTH_CLIENT_SECRET=xxx
AUTH_CALLBACK_URL=http://<server_address>/auth/sso/callback
AUTH_JWT_SECRET=your-secret-key
```

## Verifying the Configuration

Once you set the environment variables, start your Buggregator server. You should see a Login page with an option to
sign in. If everything is set up right, clicking this option will take you to the provider's login page.

![image](https://github.com/buggregator/server/assets/773481/3bc5dd4b-b8ac-4e2c-a9c0-5707dd053d0b)

After logging in successfully, users will be redirected back to the Buggregator server and logged in. You will see the
user's profile information in the bottom left corner of the app.

![image](https://github.com/buggregator/frontend/assets/773481/6f996c5e-f43a-4f5e-8da4-71f83110c7ba)

### Troubleshooting

If you encounter issues during the authentication process, ensure that:

- All environment variables are correctly set without any typos.
- The callback URL in your provider's configuration matches the `AUTH_CALLBACK_URL` you specified.
- `AUTH_JWT_SECRET` is set (it is required for session management).
- For OIDC providers, the `AUTH_PROVIDER_URL` points to the issuer root (e.g., `https://xxx.auth0.com`, not `https://xxx.auth0.com/authorize`).

---

# VarDumper — Variable Dumps

You call `dump()` or `dd()` and the output lands in the browser response, mixes with HTML, or gets lost in CLI
output. With Buggregator, dumps go to a dedicated TCP server and show up in a clean UI — alongside your logs,
exceptions, and everything else. No browser pollution, no output buffering issues, no lost dumps in long-running
processes.

![var-dumper](https://github.com/buggregator/server/assets/773481/b77fa867-0a8e-431a-9126-f69959dc18f4)

## Use cases

- **Long-running apps** (RoadRunner, Swoole, queue workers) — `dd()` doesn't print to a browser here, but Buggregator catches it.
- **API development** — dump variables without breaking JSON responses.
- **Microservices** — collect dumps from all services in one place.
- **IDE integration** — click the source location to jump straight to the file in your editor.

## What you see in the UI

- **Dumped value** — full variable content with type information, rendered as an interactive expandable tree.
- **Source location** — file and line where `dump()` was called. Clickable — opens in your IDE.
- **Variable name and label** — custom labels if provided.
- **Syntax highlighting** — for text-only dumps (see below).

## Setup

Install the Symfony VarDumper component:

```bash
composer require --dev symfony/var-dumper
```

Set two env variables to redirect output to Buggregator:

```dotenv
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=127.0.0.1:9912
```

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name (e.g., `VAR_DUMPER_SERVER=buggregator:9912`).

That's it. Use `dump()` and `dd()` as usual — the output goes to Buggregator.

If your project doesn't use `.env` files, set via PHP:

```php
$_SERVER['VAR_DUMPER_FORMAT'] = 'server';
$_SERVER['VAR_DUMPER_SERVER'] = '127.0.0.1:9912';
```

## Performance tip

Large objects with deep nesting can slow down the browser. Limit the preview depth on the events list page:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9912:9912 \
  -e VAR_DUMPER_PREVIEW_MAX_DEPTH=3 \
  ghcr.io/buggregator/server:latest
```

The full dump is still available when you open the event detail page.

## Syntax highlighting

Dump a text string with syntax highlighting using [Buggregator Trap](../trap/what-is-trap.md):

```php
$code = <<<PHP
<?php

declare(strict_types=1);

echo 'Hello, World!';
PHP;

trap($code)->context(language: 'php');
```

![image_2024-05-01_00-39-56](https://github.com/buggregator/frontend/assets/773481/9cddfbfa-e3a3-427e-a987-0f4aa1bdb504)

## Buggregator Trap

Consider using [Buggregator Trap](../trap/what-is-trap.md) instead of raw VarDumper — it uses VarDumper under the
hood but adds extra features like `trap()`, `tr()`, and `td()` helpers.

---

# Configuration — Webhooks

Webhooks allow Buggregator to send HTTP POST notifications to external services when events are received.
This enables integration with tools like [n8n](https://n8n.io/), Slack, PagerDuty, or any custom endpoint.

## Why Use Webhooks?

- **Automate Tasks:** Automatically trigger actions in other services when events happen in Buggregator.
- **Integrate with Other Tools:** Connect Buggregator with messaging apps, issue tracking software, or custom apps.

## Configuration

Webhooks are configured in `buggregator.yaml`:

```yaml
webhooks:
  - event: "*"                          # Fire on any event type
    url: https://slack.example.com/webhook
    headers:
      Authorization: "Bearer token123"
    verify_ssl: false
    retry: true

  - event: sentry                       # Fire only on Sentry events
    url: https://pagerduty.example.com/alert

  - event: smtp                         # Fire only on SMTP events
    url: https://my-app.example.com/email-hook
```

**Fields:**

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `event` | Yes | — | Event type to trigger on, or `"*"` for all events |
| `url` | Yes | — | URL to send the POST request to |
| `headers` | No | — | Additional HTTP headers to include |
| `verify_ssl` | No | `false` | Whether to verify SSL certificates |
| `retry` | No | `true` | Retry up to 3 times with exponential backoff on failure |

### Supported Event Types

- `sentry`
- `monolog`
- `var-dump`
- `ray`
- `inspector`
- `http-dump`
- `profiler`
- `smtp`
- `sms`
- `*` (all events)

### Webhook Payload

Each webhook sends a JSON payload with the following structure:

```json
{
  "uuid": "event-uuid",
  "type": "sentry",
  "payload": { ... },
  "timestamp": 1234567890.123,
  "project": "default"
}
```

## Docker Examples

### Docker Compose

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

With `buggregator.yaml`:

```yaml
webhooks:
  - event: "*"
    url: https://hooks.slack.com/services/xxx
    headers:
      Content-Type: application/json
```

### Docker Run with Config File

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -v ./buggregator.yaml:/buggregator.yaml \
  ghcr.io/buggregator/server:latest
```

> **Tip:** You can test webhooks using tools like https://webhook.site.

## Delivery Tracking

Buggregator tracks every webhook delivery attempt. You can view the delivery history for each webhook via the API,
including the response status code and payload. This helps you diagnose issues when webhooks fail to reach their
destination.

---

# XHProf — Performance Profiling

Your app is slow and you don't know why. Memory grows and you can't find the leak. XHProf profiling with
Buggregator lets you see exactly which functions consume CPU, wall time, and memory — without setting up
Blackfire or any paid profiling service. Profile data goes to the same Buggregator where you already see
your exceptions and logs.

Watch introduction video on [YouTube](https://www.youtube.com/watch?v=2QbgjIVnz78).

## Use cases

- **Find slow functions** — the Call Graph and Top Functions table show exactly where time is spent.
- **Detect memory leaks** — track memory allocation per function in long-running workers and daemons.
- **Measure optimizations** — compare two profiler runs side-by-side to verify your changes actually helped.
- **Profile any request** — works with web requests, CLI commands, queue jobs, and any PHP code.
- **All in one place** — profiling data next to exceptions, logs, and dumps in the same dashboard.

## Analysis modes

### Call Graph

Function calls as a tree. Nodes colored from white to dark red — the darker, the more resources consumed.

![xhprof-callgraph](https://github.com/buggregator/server/assets/773481/1cf3c587-c1df-4742-8fcd-54a320c86252)

### Flame Graph

Stacked function calls showing where time is spent. Useful for spotting repetitive or time-consuming operations.

![xhprof-flamegraph](https://github.com/buggregator/server/assets/773481/5f75e271-527d-4c6b-a0b1-a3558f8bac51)

### Top Functions

Ranked table of the most expensive function calls — CPU time, wall time, memory, and call count.

![xhprof-top-func](https://github.com/buggregator/server/assets/773481/43dbe4c8-ac23-4cfb-8715-f5141093618f)

### Profile Comparison

Compare two profiler runs side-by-side. See performance deltas (faster/slower) for CPU time, wall clock time,
and memory usage, with per-function percentage changes.

## Setup

### 1. Install the XHProf extension

```bash
pear channel-update pear.php.net
pecl install xhprof
```

### 2. Install the profiler package

#### Laravel

```bash
composer require --dev maantje/xhprof-buggregator-laravel
```

[Package documentation](https://github.com/maantje/xhprof-buggregator-laravel)

#### Spiral Framework

```bash
composer require --dev spiral/profiler:^3.0
```

[Package documentation](https://github.com/spiral/profiler/tree/3.0)

#### Symfony Framework

Please mind, bundle in early development stage - feedback much appreciated

```bash
composer require --dev velpl/buggregator-profiler-bundle:^0.2
```

[Package documentation](https://github.com/velPL/buggregator-profiler-bundle)

#### Any PHP project

```bash
composer require --dev spiral-packages/profiler
```

```php
use SpiralPackages\Profiler\Profiler;
use SpiralPackages\Profiler\DriverFactory;
use SpiralPackages\Profiler\Storage\WebStorage;
use Symfony\Component\HttpClient\NativeHttpClient;

$storage = new WebStorage(
    new NativeHttpClient(),
    'http://127.0.0.1/api/profiler/store',
);

$profiler = new Profiler(
    storage: $storage,
    driver: DriverFactory::detect(),
    appName: 'My app',
    tags: ['env' => 'local'],
);

$profiler->start();

// Your code here

$profiler->end();
```

### 3. Configure the endpoint

```dotenv
PROFILER_ENDPOINT=http://profiler@127.0.0.1:8000
PROFILER_APP_NAME="My app"
```

> In Docker Compose, replace `127.0.0.1` with the Buggregator service name.

## Custom client integration

If you're building a custom profiler client, there are three ways to send data:

- **HTTP auth** — add `profiler` to the URL: `http://profiler@127.0.0.1:8000`
- **Header** — send `X-Buggregator-Event: profiler` or `X-Profiler-Dump: true`
- **Endpoint** — POST to `/api/profiler/store`

---

# Contributing to Buggregator

We're excited to invite you to contribute to the project! Your involvement is crucial, whether it's reporting bugs,
suggesting new features, or any other form of contribution. To get started,
simply [create an issue](https://github.com/buggregator/server/issues) or submit a pull request on our GitHub
repository.

In our repository, we categorize issues that are open for community contribution using
the [`for contributors`](https://github.com/buggregator/server/issues?q=is%3Aissue+is%3Aopen+label%3A%22for+contributors%22)
label. This makes it easier for you to find ways to participate.

Additionally, we use labels such as `c:easy`, `c:medium`, and `c:difficult` to indicate the complexity level of issues,
helping you choose tasks that match your skill level.

## Benefits

Contributing to open source projects offers a wealth of benefits, particularly for junior developers.

**Here's why you should consider getting involved:**

1. **Learning Through Practical Experience:** Open source projects provide a platform to work with new technologies and
   frameworks that you might not encounter in your regular job. It's a fantastic way to broaden your technical horizons.
2. **Building a Professional Network:** By participating in open source, you connect with a global community of
   developers. This network is invaluable for exchanging knowledge, learning from others' experiences, and sharing your
   own insights.
3. **Enhancing Your Résumé:** Contributions to open source are often highly regarded by employers. They showcase your
   proactive nature, technical skills, and ability to collaborate effectively in a team.
4. **Gaining Insight into Best Practices:** Engaging with open source projects exposes you to code reviews and feedback
   from various developers. This experience is crucial for understanding diverse coding styles and improving your own
   coding practices.
5. **Making a Real-World Impact:** Your contributions can significantly influence the project and its users. The
   satisfaction of seeing your code being used and appreciated by others is incredibly rewarding.

**Help us enhance Buggregator and make a real difference!**

**We appreciate any contributions to help make Buggregator better!**

## Repositories

There are the following repositories in the Buggregator project:

1. [Server](https://github.com/buggregator/server). Manages and sends events to the client. It also serves as a REST API
   endpoint for event requests.
2. [Frontend](https://github.com/buggregator/frontend). Allows clients to view incoming events like variable dumps.
3. [Trap](https://github.com/buggregator/trap). A lightweight alternative to the full Buggregator server, designed for
   local debugging.
4. [Documentation](https://github.com/buggregator/docs). Contains all the documentation for the Buggregator project.
5. [Site](https://github.com/buggregator/buggregator.dev). The official website for Buggregator.
6. [PHPStorm Plugin](https://github.com/buggregator/phpstorm-plugin). A plugin for PHPStorm that integrates with
   Buggregator.

---

# Contributing — Documentation

Buggregator uses [VitePress](https://vitepress.dev/) for its documentation. This makes it easy to contribute to the
project's documentation by following the steps below.

## Getting Started

### Clone the Repository

First of all you need to clone the repository to your local machine.

```bash
git clone git@github.com:buggregator/docs.git
```

> **Note**: If you don't have access to the repository, you can fork it and clone your forked repository.

### Install Dependencies

After cloning the repository, navigate to the project directory and install the dependencies.

```bash
npm install
```

### Start the Development Server

To start the development server and preview the documentation, run the following command:

```bash
npm run docs:dev
```

This command will start a local development server and open the documentation in your default browser.

## Structure

The documentation is structured as follows:

- `docs/`: Contains the documentation files.
- `docs/.vitepress/config.mts`: Site configuration and navigation.

All you need is to edit the markdown files in the `docs/` directory. If you want to add a new page, create a new
markdown file in the `docs/` directory and add it to the navigation in the `docs/.vitepress/config.mts` file.

---

That's it! You're now ready to contribute to the Buggregator documentation.

---

# Contributing — Frontend side

[The Frontend Part](https://github.com/buggregator/frontend) is what users interact with. It displays the events and
information processed by the server in a user-friendly way. Users can see live updates of events like errors or logs.

## Key Technologies:

- [VueJs 3](https://v3.vuejs.org/) - This framework builds the interactive user interface.
- [TailwindCSS](https://tailwindcss.com/) - Styles the frontend, making it look good and responsive.
- [Storybook](https://storybook.js.org/) - Helps us develop and organize UI components.

This architecture supports a robust system for monitoring and managing application events. As a contributor, your work
in either part plays a crucial role in enhancing Buggregator's functionality and user experience. If you have any
specific areas you're interested in or questions about the architecture, feel free to ask!

## Server requirements

1. NodeJS >=20.x (22.x is prefare)
2. Yarn >=1.22.x

## Installation

1. Clone repository `git clone https://github.com/buggregator/frontend.git`
2. Install dependencies `yarn install`
3. Run NodeJS server `yarn dev`
4. Open http://localhost:3000

In dev mode you are able to see Storybook components in isolation with mocked data by the link http://localhost:6006.

---

### Now you can start developing your own features and share them with the community!

---

# Contributing — Server side

[The Server Part](https://github.com/buggregator/server) is where all the data processing and management happen. It's
crucial for handling the information that flows through Buggregator.

1. **Event Processing:** This part receives information (like errors or logs) from applications. It organizes and
   processes these events.

2. **API Communication:** It also communicates with clients through REST API and WebSocket, sending and receiving
   data as needed.

## Key Technologies

Buggregator v2.0 is written in Go as a single self-contained binary:

- [Go](https://go.dev/) — the server language
- [SQLite](https://www.sqlite.org/) (via [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite)) — embedded database, no external server needed
- Built-in WebSocket server implementing the [Centrifugo v5](https://centrifugal.dev/) protocol
- Embedded SPA frontend (compiled into the binary via `go:embed`)

## Architecture

### Module System

Every feature (Sentry, Ray, Monolog, etc.) is a **module** implementing the `module.Module` interface.
Modules are either HTTP-based or TCP-based:

- **HTTP modules** return an `HTTPIngestionHandler` with `Priority()`, `Match()`, and `Handle()`.
  Lower priority runs first. The http-dump module has priority 9999 as the catch-all.
- **TCP modules** return `[]tcp.ServerConfig` with connection handlers (Monolog, VarDumper) or
  self-managed servers (SMTP).

### Ingestion Pipeline

1. **Detect** — extract event type/project from URI userinfo, headers, or Basic Auth
2. **Match** — try handlers in priority order; first match wins
3. **Handle** — parse request body, return `event.Incoming`
4. **Store & Broadcast** — store in SQLite, build preview, broadcast via WebSocket, notify modules

### Storage

Single implementation: `SQLiteStore` using pure Go SQLite. Migrations live in each module and run
automatically on startup.

## Server Requirements

- Go 1.26+
- Make (for build commands)

## Build & Development

```bash
# Full build (downloads frontend, builds PHP parser for VarDumper, compiles binary)
make build

# Quick Go compilation check
go build ./...

# Run all tests
go test ./...

# Run a single test
go test ./internal/server/http/ -run TestAPI_Version

# Cross-compile
make build-cross GOOS=darwin GOARCH=arm64
```

## Installation

1. **Docker:** Use the Docker Compose setup for a quick dev environment.
   See the [Docker development guide](../cookbook/docker-install).
2. **Manual:** Download dependencies and build from source.
   See the [manual installation guide](../cookbook/manual-install.md).

---

# Cookbook — Dev environment using Docker Compose

This guide will help you quickly set up a local development environment for Buggregator.

## 1. Clone the Repository

Start by cloning the repository:

```bash
git clone git@github.com:buggregator/server.git
cd server
```

> **Note:** If you don't have access, fork the repository and clone your fork instead.

## 2. Build and Start

The repository includes a Docker Compose setup for a local development environment, including the Buggregator server
and example services.

### Build

```bash
make build
```

### Start the Server

```bash
make run
```

This will:

- Build the Buggregator Go binary
- Start the Buggregator server
- Launch example services for testing features

## 3. Access the Application

Once the server is up:

- **Buggregator:** http://localhost:8000

## 4. Development without Docker

If you prefer to develop without Docker, you need:

- **Go 1.26+**
- **Make**

```bash
# Build and run
make build
make run

# Or just compile
go build ./cmd/buggregator

# Run tests
go test ./...
```

### Frontend Development

The frontend is a pre-built SPA that gets embedded into the binary during the build process. To develop
the frontend separately:

```bash
git clone git@github.com:buggregator/frontend.git
cd frontend
yarn install
yarn dev
```

Then point Buggregator at the frontend dev server:

```bash
FRONTEND_DIR=/path/to/frontend/dist ./buggregator
```

## 5. Stop the Server

```bash
# If using Docker Compose
make down

# If running directly
Ctrl+C
```

---

That's it! Your Buggregator dev environment is ready.

---

# Cookbook — Manual Installation

Buggregator is a single self-contained binary with no external dependencies. You don't need Docker, PHP, Go, or any
runtime to run it.

## Download

Download the latest release for your platform from
[GitHub Releases](https://github.com/buggregator/server/releases):

```bash
# Linux (amd64)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-linux-amd64
chmod +x buggregator

# Linux (arm64)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-linux-arm64
chmod +x buggregator

# macOS (Apple Silicon)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-arm64
chmod +x buggregator

# macOS (Intel)
curl -L -o buggregator https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-amd64
chmod +x buggregator
```

## Run

```bash
./buggregator
```

Open http://127.0.0.1:8000 in your browser. That's it.

## Configuration

By default, Buggregator runs with in-memory storage (data is lost on restart). To persist data, create
a `buggregator.yaml` file next to the binary:

```yaml
database:
  dsn: data.db                    # Persist events to a SQLite file

storage:
  mode: filesystem                # Persist attachments to disk
  path: ./storage
```

Or specify a custom config path:

```bash
./buggregator --config /etc/buggregator/buggregator.yaml
```

See the [server configuration guide](../config/server.md) for all available options.

## Default Ports

| Port | Service |
|------|---------|
| 8000 | HTTP (Web UI + API) |
| 1025 | SMTP |
| 9912 | VarDumper (TCP) |
| 9913 | Monolog (TCP) |

All ports are configurable via environment variables or the config file.

---

# Getting Started

## Three steps. That's it.

1. **Run one command** — start Buggregator with a single command. No installation, no registration, no configuration files.
2. **Add one env variable** — change one line in your `.env` file. Your existing Sentry SDK, VarDumper, Monolog, or Ray — they all just work.
3. **Open your browser** — navigate to http://127.0.0.1:8000 and start debugging. No login required.

## Quick Start

### Standalone Binary (Recommended)

Buggregator is a single ~30 MB binary with no dependencies. Download and run:

```bash
# Linux (amd64)
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-linux-amd64 -o buggregator \
  && chmod +x buggregator \
  && ./buggregator
```

<details>
<summary>Other platforms</summary>

```bash
# Linux (arm64)
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-linux-arm64 -o buggregator \
  && chmod +x buggregator

# macOS (Apple Silicon)
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-arm64 -o buggregator \
  && chmod +x buggregator

# macOS (Intel)
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-darwin-amd64 -o buggregator \
  && chmod +x buggregator
```

</details>

Open http://127.0.0.1:8000 in your browser. Done.

### Docker

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:9912:9912 \
  -p 127.0.0.1:9913:9913 \
  ghcr.io/buggregator/server:latest
```

### Docker Compose

Add Buggregator to your `docker-compose.yml` alongside your other services:

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

No environment configuration needed. Works out of the box.

## Just change the address

If Buggregator is part of an existing Docker Compose stack, other services can reach it by its service name.
Change your app's `.env` to point at the container — that's the only change you need:

```dotenv
# Sentry — only the host changed. Your Sentry SDK keeps working exactly the same.
SENTRY_LARAVEL_DSN=http://sentry@buggregator:8000/1

# Ray
RAY_HOST=ray@buggregator
RAY_PORT=8000

# VarDumper
VAR_DUMPER_FORMAT=server
VAR_DUMPER_SERVER=buggregator:9912

# Monolog
LOG_CHANNEL=socket
LOG_SOCKET_URL=buggregator:9913

# SMTP — email capture
MAIL_HOST=buggregator
MAIL_PORT=1025
```

## Ports

Each port serves a specific module. You only need to expose the ports for the features you use:

| Port | Protocol | Module | What it does |
|------|----------|--------|-------------|
| **8000** | HTTP | [Sentry](./config/sentry.md), [Ray](./config/ray.md), [Inspector](./config/inspector.md), [HTTP Dumps](./config/http-dumps.md), [XHProf](./config/xhprof.md), [SMS](./config/sms.md) | Web UI + HTTP-based event ingestion. This is the only required port. |
| **1025** | SMTP | [Fake SMTP Server](./config/smtp.md) | Captures outgoing emails. Point your app's SMTP config here. |
| **9912** | TCP | [Symfony VarDumper](./config/var-dumper.md) | Receives `dump()` / `dd()` output. |
| **9913** | TCP | [Monolog](./config/monolog.md) | Receives log records via Monolog's `SocketHandler`. |

If you only need specific features, omit the unused ports. For example, VarDumper only:

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:9912:9912 \
  ghcr.io/buggregator/server:latest
```

## Kubernetes

The recommended way to deploy Buggregator on Kubernetes is using the [Helm chart](./config/helm-chart.md):

```bash
helm install buggregator oci://ghcr.io/buggregator/helm-chart/buggregator
```

See the [Helm chart documentation](./config/helm-chart.md) for SSO, Ingress, Prometheus, and more.

Or deploy manually as a `Deployment` + `Service`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: buggregator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: buggregator
  template:
    metadata:
      labels:
        app: buggregator
    spec:
      containers:
        - name: buggregator
          image: ghcr.io/buggregator/server:latest
          ports:
            - containerPort: 8000
            - containerPort: 1025
            - containerPort: 9912
            - containerPort: 9913
---
apiVersion: v1
kind: Service
metadata:
  name: buggregator
spec:
  selector:
    app: buggregator
  ports:
    - name: http
      port: 8000
    - name: smtp
      port: 1025
    - name: var-dumper
      port: 9912
    - name: monolog
      port: 9913
```

## Configuration

Buggregator can be configured via a YAML config file, environment variables, or CLI flags.
The priority order is: **CLI flags > Environment variables > Config file > Defaults**.

See the [server configuration guide](./config/server.md) for the full reference.

### Quick example with environment variables

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -e DATABASE_DSN=data.db \
  -e METRICS_ENABLED=true \
  -v ./data:/data \
  ghcr.io/buggregator/server:latest
```

## Image Tags

| Tag | Description |
|-----|-------------|
| `latest` | Latest stable release. **Recommended.** |
| `dev` | Latest development build. May be less stable. |
| `X.Y` (e.g., `2.0`) | A specific release version, pinned. |

## Security

By default, all ports are bound to `127.0.0.1` (localhost only). This prevents external access.
Your debug data never leaves your machine.

> **Warning:** If you remove the `127.0.0.1:` prefix (e.g., `-p 8000:8000`), the port becomes accessible from
> outside your machine. Only do this if you understand the implications.

For team environments, consider enabling [SSO authentication](./config/sso.md) to restrict access to the UI.

---

# What is Buggregator?

## Debug everything. Install nothing.

One binary. One command. Exceptions, dumps, emails, profiling, logs — all in one real-time UI.
Works with the SDKs you already have. No cloud account. No code changes. No runtime dependencies.

**Free forever. No paid plans. No feature gates. [MIT License](https://github.com/buggregator/server/blob/master/LICENSE).**

**Watch introduction video on [YouTube](https://www.youtube.com/watch?v=yKWbuw8xN_c)**

**Project repository:** https://github.com/buggregator/server

![Cover image](https://github.com/buggregator/server/assets/773481/47491a3c-57a3-4b40-b82e-37976afdf708)

## What's new in v2.0

Buggregator v2.0 is a **complete rewrite in Go**. The result is a single ~30 MB self-contained binary
with everything built in — web UI, WebSocket server, SQLite database. No PHP runtime, no external
services, no infrastructure to manage.

- **Single binary** — download, run, done. No Docker required (though Docker is still supported).
- **~30 MB** — the entire server with the embedded web UI weighs less than a typical node_modules folder.
- **Zero dependencies** — no PHP, no Go runtime, no database server, no message broker. Everything is inside.
- **Embedded SQLite** — in-memory by default for instant startup, or file-based for persistence.
- **MCP server** — AI assistants (Claude Code, Cursor) can query your debugging data directly.

> Looking for the PHP version (v1.x)? See the [1.x branch](https://github.com/buggregator/server/tree/1.x).

## Get started in 60 seconds

### Download and run

```bash
curl -sL https://github.com/buggregator/server/releases/latest/download/buggregator-linux-amd64 -o buggregator \
  && chmod +x buggregator \
  && ./buggregator
```

Open http://127.0.0.1:8000 — that's it. No installation, no registration, no configuration files.

### Or use Docker

```bash
docker run --pull always \
  -p 127.0.0.1:8000:8000 \
  -p 127.0.0.1:1025:1025 \
  -p 127.0.0.1:9912:9912 \
  -p 127.0.0.1:9913:9913 \
  ghcr.io/buggregator/server:latest
```

> No Docker? No binary? Use [Buggregator Trap](./trap/what-is-trap.md) — a lightweight PHP CLI
> alternative. Just `composer require --dev buggregator/trap`.

## Your app doesn't know we exist

Buggregator runs **beside** your application as a standalone server — not inside it. Your codebase doesn't
change. Your dependencies don't change. You already have the SDKs installed (Sentry, VarDumper, Monolog,
Ray) — they just need a different address in your `.env`.

**No new dependencies.** Your app's `composer.json` stays untouched. No service providers. No migrations.
No Buggregator code inside your project.

**One env variable.** Already using Sentry SDK, VarDumper, or Monolog? Change where they send data.
That's it. Your code doesn't need to know about Buggregator.

**One instance, all your apps.** Run one Buggregator container or binary. Point all your projects at it.
Microservices, monorepos, multiple teams — one dashboard.

## Replaces your local dev stack — for free

| Instead of | Buggregator gives you |
|---|---|
| Sentry (cloud) | Exceptions with full stack traces |
| Mailhog / Mailtrap | Email capture and preview |
| Ray (paid app) | Variable dumps with 18+ payload types |
| Blackfire / XHProf UI | Performance profiling with flame graphs |
| Kibana / Log viewers | Real-time application logs |
| RequestBin | HTTP request inspection |
| Inspector.dev | Application performance monitoring |
| Twilio console | SMS gateway testing |

**All of this. One command. Zero cost.**

## When you need it

- You have a **long-running PHP app** (RoadRunner, FrankenPHP, Swoole, Octane, queue workers) and `dd()` is not an option.
- You want to see **exceptions with stack traces** like in Sentry, but don't want to set up Sentry for local dev.
- You need to **profile performance** and find memory leaks or slow functions.
- You want to **test emails** your app sends without a real mail server.
- You want to **capture SMS messages** without sending real ones through Twilio or Vonage.
- You have **multiple services** (microservices, Docker Compose) and want all debug data in one place.
- You want to **inspect HTTP requests** your app makes to external APIs.
- You just need a better `dump()` — with syntax highlighting, IDE links, and no browser pollution.

## 9 debugging tools in one dashboard

### [XHProf Profiler](/config/xhprof) — Performance

Find slow functions and memory leaks. Visualize profiling data as a **Call Graph**, **Flame Graph**,
and **Top Functions** table. **Compare two runs** side-by-side to verify your optimizations actually helped.

![xhprof](https://github.com/buggregator/server/assets/773481/d69e1158-599d-4546-96a9-40a42cb060f4)

### [Sentry Compatibility](/config/sentry) — Exceptions

Catch unhandled exceptions with full **stack traces**, **breadcrumbs**, **request details**,
**device/browser info**, tags, and context. See exactly where your code breaks.
All Sentry SDKs are supported — PHP, JavaScript, Python, and more.

![sentry](https://github.com/buggregator/server/assets/773481/e979fda5-54c8-42cc-8224-a1c5d828569a)

### [Fake SMTP Server](/config/smtp) — Emails

Intercept outgoing emails during development. Preview HTML (with mobile/desktop viewport switcher),
plain text, all addresses, attachments, and raw source. No emails actually sent.

![smtp](https://github.com/buggregator/server/assets/773481/8dd60ddf-c8d8-4a26-a8c0-b05052414a5f)

### [SMS Gateway](/config/sms) — SMS Messages

Intercept outgoing SMS during development. Auto-detects 40+ providers including Twilio, Vonage, Plivo,
Sinch, and more. See every message with sender, recipient, text, and detected provider.

### [HTTP Dumps](/config/http-dumps) — Requests

Capture and inspect HTTP requests: method, URI, headers, cookies, POST data, uploaded files. Get a ready-to-use
**cURL command** for any captured request.

![http dumps](https://github.com/buggregator/server/assets/773481/fc823390-b490-4bbb-a787-44471eca9fb6)

### [Monolog Server](/config/monolog) — Logs

Aggregate application logs in real time. See log level, channel, message, context, extra fields, and source
location. Filter by level, search by message. Supports all PSR-3 levels.

![monolog](https://github.com/buggregator/server/assets/773481/21919110-fd4d-490d-a78e-41242d329885)

### [Symfony VarDumper](/config/var-dumper) — Variable Dumps

Inspect variables with `dump()`. See object properties, array contents, and types — right in the browser.
Click on file paths to open them in your IDE.

![var-dumper](https://github.com/buggregator/server/assets/773481/b77fa867-0a8e-431a-9126-f69959dc18f4)

### [Spatie Ray](/config/ray) — Debug Tool

Debug with `ray()` — tables, queries, models, jobs, mail, counters, and 18 more payload types.
A free alternative to the Ray app. Works with PHP, JavaScript, Ruby, Go, and Bash.

![ray](https://github.com/buggregator/server/assets/773481/168b27f7-75b1-4837-b0a1-37146d5b8b52)

### [Inspector Compatibility](/config/inspector) — Transactions

Monitor application performance with transaction tracing, memory tracking, and timeline breakdowns
to identify bottlenecks. Local APM alternative.

![inspector](https://github.com/buggregator/server/assets/773481/ab002ecf-e1dc-4433-90d4-0e42ff8c0ab3)

## Works with your framework

No vendor lock-in. Your existing SDK just works.

Buggregator is compatible with **Laravel**, **Symfony**, **Spiral**, **WordPress**, **Yii**, **Drupal**,
**Magento** — and JavaScript, Python, Ruby, Go via Sentry SDK.

Works with: **RoadRunner**, **FrankenPHP**, **Swoole**, **Laravel Octane**.

See [integration guides](/config/sentry) for framework-specific setup.

## The Buggregator ecosystem

### JetBrains IDE Plugin

Don't want to leave your IDE? The [Buggregator plugin for JetBrains IDEs](https://plugins.jetbrains.com/plugin/26344-buggregator)
brings dumps, logs, and debug data directly into PhpStorm, IntelliJ IDEA, WebStorm, and other JetBrains products.
No need to switch windows — everything is in a panel next to your code.

The plugin launches [Buggregator Trap](/trap/what-is-trap) from your project and provides two views:
- **Web UI** — the full Buggregator interface embedded in the IDE's built-in browser.
- **Terminal** — text-based output for quick inspection.

Install from **Settings** > **Plugins** > **Marketplace** > search "Buggregator", or visit the
[plugin page](https://plugins.jetbrains.com/plugin/26344-buggregator).

Read more in the [plugin documentation](/config/phpstorm-plugin).

### Buggregator Trap

No Docker? No problem. [Buggregator Trap](./trap/what-is-trap.md) is a lightweight PHP CLI alternative
to the full server. Covers most debugging needs — dumps, profiler, logs, inspections — without Docker.
Just a Composer package.

```bash
composer require --dev buggregator/trap -W
```

## Ready for production teams

Enterprise features when you need them:

- **[SSO Authentication](/config/sso)** — Auth0, Google, GitHub, Keycloak, GitLab, and generic OIDC.
- **[Database](/config/database)** — SQLite with in-memory or file-based persistence.
- **[Kubernetes Ready](/config/helm-chart)** — deploy as Deployment + Service with the official Helm chart.
- **[Webhooks](/config/webhooks)** — trigger external actions on incoming events.
- **[Prometheus Metrics](/config/metrics)** — monitor event counts with Grafana.
- **[Multi-project Support](/config/projects)** — separate events by project or team.
- **[MCP Server](/config/mcp)** — let AI assistants (Claude Code, Cursor) query your debugging data.

## Also included

- **Event pinning** — pin important events so they don't get lost.
- **Event screenshots** — export any event as an image to share with your team.
- **Keyboard shortcuts** — press `?` to see all shortcuts. Navigate with `j`/`k`, switch modules with `1`-`8`.
- **IDE integration** — click file paths to open them in VS Code, PhpStorm, or [14 other IDEs](/config/var-dumper). Custom path mappings for Docker.
- **Dark / Light themes** — follows your system preference or set manually.

## Tech stack

- [Go](https://go.dev/) (single binary, ~30 MB, no external dependencies)
- [SQLite](https://www.sqlite.org/) (embedded database, in-memory or file-based)
- [Vue 3](https://vuejs.org/) + [TypeScript](https://www.typescriptlang.org/) + [Vite](https://vite.dev/)
- [TailwindCSS](https://tailwindcss.com/) + [Pinia](https://pinia.vuejs.org/)
- Built-in WebSocket server ([Centrifugo v5](https://centrifugal.dev/) protocol)

## Open source. Built with the community.

Buggregator is free forever. No paid plans, no feature gates. If it helps you, consider
[starring the repo](https://github.com/buggregator/server).

Contributions are welcome — bugs, features, docs.

[Contribution guidelines](./contributing.md) · [GitHub](https://github.com/buggregator/server) · [Discord](https://discord.gg/vDsCD3EKUB)

### Support the project

Buggregator is and will always be free. Sponsors help fund server costs, development time, and new features.

- [Support on Patreon](https://patreon.com/butschster)
- [Browse issues](https://github.com/buggregator/server/issues) — find something to work on
- [Join Discord](https://discord.gg/vDsCD3EKUB) — ask questions, share feedback

---

# Using Buggregator docs with AI assistants

Buggregator documentation is available in a machine-readable format so that AI assistants (ChatGPT, Claude, Cursor,
Windsurf, GitHub Copilot, and others) can read it and help you set up, configure, and debug issues.

## Quick start

Give your AI assistant this URL:

```
https://docs.buggregator.dev/llms.txt
```

The assistant will read the index, understand what Buggregator is, and fetch the specific pages it needs to answer
your question.

### Example prompts

- "Read https://docs.buggregator.dev/llms.txt and help me set up Buggregator with my Laravel project"
- "I have a Symfony app. How do I send Monolog logs to Buggregator?"
- "Help me configure XHProf profiling for my PHP application"
- "What's the difference between Buggregator server and Trap?"

## Available endpoints

| URL | What it contains | When to use |
|-----|-----------------|-------------|
| [`/llms.txt`](https://docs.buggregator.dev/llms.txt) | Index with page descriptions | When the assistant supports browsing — it picks the relevant pages |
| [`/llms-full.txt`](https://docs.buggregator.dev/llms-full.txt) | Complete documentation in one file | Best for most assistants — give full context in one shot |
| `/<page>.md` | Individual page without frontmatter | When you only need a specific topic |

### Per-page URLs

If you only need help with a specific integration, you can point the assistant to a single page:

- `https://docs.buggregator.dev/config/sentry.md` — Sentry setup
- `https://docs.buggregator.dev/config/smtp.md` — SMTP / email testing
- `https://docs.buggregator.dev/config/xhprof.md` — XHProf profiling
- `https://docs.buggregator.dev/config/monolog.md` — Monolog logs
- `https://docs.buggregator.dev/config/var-dumper.md` — Symfony VarDumper
- `https://docs.buggregator.dev/config/ray.md` — Spatie Ray
- `https://docs.buggregator.dev/getting-started.md` — Installation guide

## How it works

These files follow the [llms.txt](https://llmstxt.org/) convention — a standard way to provide documentation
to AI models. The content is the same as the regular docs, just formatted for machine consumption (plain markdown,
no HTML, no navigation chrome).

The files are generated automatically during the docs build, so they're always up to date with the latest
documentation.

---

# Trap — Commands

## `run`

### Description

The `run` command starts the Trap server, which listens for debug information on specified ports and
processes it using configured senders.

### Simple Example

```bash
vendor/bin/trap run
```

### Arguments and Options

| Option     | Short | Description                                             | Default                  |
|------------|-------|---------------------------------------------------------|--------------------------|
| `--port`   | `-p`  | Port(s) to listen on (can be specified multiple times)  | `1025, 8000, 9912, 9913` |
| `--sender` | `-s`  | Sender type(s) to use (can be specified multiple times) | `console`                |
| `--ui`     | -     | Enable web UI (with optional port specification)        | `false`                  |

### Port Configuration Details

By default, Trap runs on multiple ports simultaneously: `1025, 8000, 9912, 9913`. All ports listen for the same data,
but this multi-port setup makes it compatible with various debugging tools that have their own default ports:

- Port `1025`: Default SMTP port for email testing
- Port `8000`: Used for HTTP dumps
- Port `9912`: Default port for Symfony VarDumper
- Port `9913`: Default for Monolog socket handler

If you want to listen on just one specific port, you can specify it:

```bash
vendor/bin/trap run -p 8000
```

This will make Trap listen only on port `8000`.

### Examples

Start with default settings:

```bash
vendor/bin/trap run
```

Listen on specific ports:

```bash
vendor/bin/trap run --port=8888
# or
vendor/bin/trap run -p 8888
```

Listen on multiple ports:

```bash
vendor/bin/trap run --port=8888 --port=9999
# or
vendor/bin/trap run -p 8888 -p 9999
```

Enable the web UI on default port:

```bash
vendor/bin/trap run --ui
```

Use environment variables for configuration:

```bash
TRAP_TCP_PORTS=8888,9999 TRAP_UI_PORT=8080 vendor/bin/trap run --ui
```

### Available Senders

Trap supports multiple methods ("senders") for outputting the debug information, allowing you to choose where your debug
dumps are sent:

- **Console**: Outputs dumps directly in the console.
- **Server**: Sends dumps to a remote Buggregator server for centralized management and review.
- **File**: Saves dumps to a file, useful for auditing or detailed offline analysis.

By default, dumps are displayed in the console. However, you can configure multiple senders simultaneously to suit your
workflow and requirements. For example, to use the console, file, and server senders together:

| Sender         | Description                                      |
|----------------|--------------------------------------------------|
| `console`      | Outputs debug information to the console         |
| `file`         | Writes events to files in JSON format            |
| `file-body`    | Writes event body content to separate files      |
| `mail-to-file` | Stores received emails to files                  |
| `server`       | Forwards events to a Buggregator server instance |


```bash
vendor/bin/trap run --sender=console --sender=file
```

## `test`

### Description

The `test` command sends various types of test data to the Trap server to verify that it's working correctly. This
includes XHProf data, var dumps, emails, Sentry reports, and binary data.

### Simple Example

```bash
vendor/bin/trap test
```

### Arguments and Options

The `test` command doesn't accept any arguments or options.

### Example

To send test data to a running Trap instance:

```bash
# First, start the trap server in one terminal
vendor/bin/trap run

# Then, in another terminal, run the test command
vendor/bin/trap test
```

This will:

1. Send XHProf profiling data
2. Execute various `trap()` dumps
3. Send test emails (both simple and multipart)
4. Send Sentry store and envelope data
5. Send binary data

---

## `joke`

### Description

The `joke` command prints a random joke using the trap framework. It's a fun addition that also demonstrates the trap
functionality.

### Simple Example

```bash
vendor/bin/trap joke
```

### Arguments and Options

The `joke` command doesn't accept any arguments or options.

### Example

To display a random joke:

```bash
vendor/bin/trap joke
```

The joke output will be displayed using the same output mechanism as other trap messages, which can be a good way to
verify that your trap setup is working correctly in a lightweight manner.

## Environment Variables

Trap can be configured using environment variables:

| Variable                    | Description                                | Default                             |
|-----------------------------|--------------------------------------------|-------------------------------------|
| `TRAP_TCP_PORTS`            | Comma-separated list of ports to listen on | `1025,8000,9912,9913`               |
| `TRAP_TCP_HOST`             | Host interface to bind to                  | `127.0.0.1`                         |
| `TRAP_TCP_POLLING_INTERVAL` | Socket polling interval in microseconds    | `1000`                              |
| `TRAP_UI_PORT`              | Web UI port                                | `8000`                              |
| `TRAP_UI_HOST`              | Web UI host interface                      | `127.0.0.1`                         |
| `TRAP_MAIN_LOOP_INTERVAL`   | Main loop interval in microseconds         | `100`                               |
| `TRAP_XHPROF_PATH`          | Path to XHProf files                       | Read from PHP's `xhprof.output_dir` |
| `TRAP_XHPROF_SORT`          | XHProf edges sorting algorithm (0-3)       | `3`                                 |

---

# Trap — Getting Started

There are several ways to get started with Trap, depending on your needs and preferences.

## Standalone Binary (No Project Dependencies)

Download and extract the pre-compiled binary for your platform. This method allows you to use Trap across multiple PHP
projects without modifying their dependencies.

**Available for platforms:**

- Linux (amd64, arm64)
- macOS (amd64, arm64)
- Windows (amd64)

> **Note:** Binaries can be found on release page https://github.com/buggregator/trap/releases

```bash
# Download (example for Linux amd64)
curl -L -o trap.tar.gz https://github.com/buggregator/trap/releases/latest/download/trap-1.13.13-linux-amd64.tar.gz

# Extract the archive
tar -xzf trap.tar.gz
rm trap.tar.gz

# Make executable
chmod +x trap

# Run
./trap
```

This command will start the Trap server, ready to receive any debug messages. Once a debug message is trapped, you will
see a convenient report about it right here in the terminal or in the browser.

## Composer Installation

To use Trap into your project, simply add it as a development dependency via Composer:

```bash
composer require --dev buggregator/trap -W
```

After installation, you can start the debugging server using:

```bash
vendor/bin/trap
```

Once Trap is running, you can start debugging with the `trap()` function:

```php
// Basic variable dump
trap($user);

// Named variable dumps
trap(id: $userId, email: $userEmail);

// Dump and continue using the value
$response = trap($api->getResponse())->return();

// Set dump depth for nested objects
trap($complexObject)->depth(3);
```

## User Interface

By adding the `--ui` flag when starting the Trap server, you can automatically open the web interface. This allows for a
more intuitive and graphical interaction with your debug data.

```bash
./trap --ui
# or
vendor/bin/trap --ui
```

And just open the URL in your browser: [http://127.0.0.1:8000](http://127.0.0.1:8000).

## What's Next?

- Read more about the `trap()` function in the [Usage](./usage.md) section.
- Explore the [Commands](./commands.md) for additional functionality.

---

# Trap — Functions

Trap is not just a server; it's also a useful collection of functions that help you debug your PHP applications.

## trap()

### Description

The `trap()` function is designed to capture and send variable dumps to the server. It serves as the primary entry point
for debugging PHP applications, allowing developers to inspect variables, trace execution flow, and analyze application
state at runtime.

> **Note:** When using `trap()`, it automatically configures `$_SERVER['REMOTE_ADDR']` and `$_SERVER['REMOTE_PORT']` if
> they are not already set. This ensures that the debug information is accurately captured and displayed.

### Signature

```php
function trap(mixed ...$values): TrapHandle
```

The function accepts any number of arguments (named or positional) and returns a `TrapHandle` instance that provides
additional debugging capabilities through method chaining.

### Usage Examples

#### 1. Basic Variable Dumping

```php
// Dump a simple variable
trap($user);

// Dump multiple variables
trap($request, $response, $config);

// Use named arguments for better clarity
trap(user: $user, request: $request, response: $response);
```

This sends the variables to the Buggregator server where they can be inspected in the dashboard.

#### 2. Stack Trace Inspection

```php
// Add stack trace to your dump to see the execution flow
trap()->stackTrace();

// Dump a variable along with the stack trace
trap($result)->stackTrace();
```

This adds the current stack trace to your dump, showing the execution path that led to this point in your code.

#### 3. Limiting Dump Depth

```php
// Limit the dump depth to 4 levels for deeply nested objects
trap($complexObject)->depth(4);

// Dump multiple objects with depth limit
trap(user: $user, order: $order)->depth(2);
```

This is useful for complex objects where you want to limit how deep the dump will go into nested structures.

#### 4. Conditional Dumping

```php
// Dump only if a condition is met
trap($response)->if($statusCode >= 400);

// Using a callable for complex conditions
trap($query)->if(fn() => $query->count() > 100);
```

This lets you add conditional logic to your dumps, only showing them when specific conditions are met.

#### 5. Limiting Dump Frequency

```php
// Dump only once at this location in code
trap($i)->once();

// Dump only 5 times at this location
trap($i)->times(5);

// Dump only 3 times with full stack consideration (useful in recursion)
trap($recursiveData)->times(3, true);
```

This helps when debugging loops or recursive functions by limiting how many times the dump is shown.

#### 6. Getting Values Back

```php
// Dump a value and return it immediately
$result = trap($data)->return();

// Chain operations without breaking the flow
$response = $service->process(trap($request)->return());

// Return a specific named value
$name = trap(first: $firstName, last: $lastName)->return('last');
```

This allows you to insert debugging in the middle of expressions without disrupting your code flow.

#### 7. Adding Context

```php
// Add execution context to help understand the dump
trap($phpCode)->context(language: 'php', filename: 'Controller.php');

// Add context using an array
trap($data)->context(['environment' => 'production', 'user_id' => 42]);

// Shorthand for code highlighting
trap($sqlQuery)->code('sql');
```

This adds metadata to your dumps to provide more context for debugging.

#### 8. Combining Multiple Features

```php
// Combine multiple debugging features
trap($user)
    ->depth(3)
    ->if($user->isAdmin())
    ->context(role: 'admin', permissions: $user->getPermissions())
    ->once();
```

This example uses multiple features together to create a targeted debugging setup.

#### 9. Working with Protobuf Messages

```php
// Dump Protobuf messages with improved readability
trap($protoMessage);
```

The trap function includes special handling for Protocol Buffers, making them easier to debug.

#### 10. Checking Performance with Ticks

```php
// First tick
tr();

// Some code to measure
doSomething();

// Second tick will show time elapsed since first tick
tr();
```

The `tr()` function (a short alias) can be used to measure performance between points in your code.

## tr()

### Description

The `tr()` function is a shorthand alias for `trap()->return()`. When called without arguments, it works as a
performance ticker, measuring time and memory usage between calls.

### Signature

```php
function tr(mixed ...$values): mixed
```

### Usage Examples

#### 1. Performance Measurement

```php
// Mark the starting point
tr();

// Execute the code to measure
$result = heavyComputation();

// Mark the endpoint and see elapsed time and memory usage
tr();
```

This shows time elapsed and memory usage between calls.

#### 2. Quick Value Inspection

```php
// Dump and return in one call
$user = tr($repository->findUser($id));

// Chain in expressions
return tr($response->withHeader('Content-Type', 'application/json'));
```

This lets you inspect values while keeping them in your execution flow.

## td()

### Description

The `td()` function combines `trap()` with PHP's `die` statement, allowing you to dump values and terminate script
execution. It's useful for quickly halting execution after inspecting critical values.

### Signature

```php
function td(mixed ...$values): never
```

### Usage Examples

#### 1. Debug and Die

```php
// Dump value and terminate execution
td($error);

// Dump multiple values before terminating
td($request, $exception, $context);
```

This dumps the values to Buggregator and immediately terminates script execution.

#### 2. Emergency Debugging

```php
// When you need to stop and check what's happening
if ($unexpectedCondition) {
    td(message: 'Unexpected condition', data: $data);
}
```

This is useful during development to quickly halt execution at critical points.

#### 3. Performance Check and Die

```php
// Start measuring
tr();

// Run code to analyze
$result = complexOperation();

// Check result and terminate
td($result);
```

This combines performance measurement with termination, useful for profiling.

---

# Trap — What is it?

Trap is a powerful, lightweight debugging tool designed to supercharge your PHP development experience. It
serves as an excellent alternative to Symfony VarDumper by providing all the functionality you need for debugging with
the addition of a clean, intuitive user interface built right in.

**Project repository:** https://github.com/buggregator/trap
> Star the project to show your support and help us grow! ⭐️ We appreciate your support!

## What Makes Trap Special

Unlike traditional debugging tools that output to the console or directly into your application's response, Trap
captures debugging information and presents it both in a dedicated dashboard and console. This separation keeps your
application output clean while giving you a comprehensive view of all debugging data in one place.

### Key Features:

- **Zero Configuration**: Works immediately after installation with sensible defaults.
- **Cross-Project Compatibility**: Allows to debug multiple applications simultaneously with a single Trap instance
- **Dashboard Interface:** It features the same user-friendly dashboard as the full Buggregator Server, allowing for
  seamless monitoring and management of debug outputs directly from the web.
- **Standalone Binary**: Use without adding dependencies to your project on Windows, Linux, or MacOS.
- **Console Application:** Includes a mini-server written entirely in PHP, eliminating the need for Docker or other
  container technology. This makes it easier to deploy and use in a variety of development environments.
- **Multiple Handlers:** Trap supports various handlers for debugging such as **Symfony VarDumper**,
  **Monolog**,**Sentry**, **SMTP**, **HTTP dumps**, **Ray**, and more. This versatility allows developers to tailor the
  debugging process to their specific needs and existing development stack.
- **Protobuf Debugging:** Offers an improved way to work with Google Protocol Buffers (protobuf) by providing clearer
  and more concise debugging outputs.



## Console Application

Here's a sneak peek into the console output you can expect with Trap:

### Symfony/var-dumper (proto)

![var-dumper](https://github.com/buggregator/trap/assets/4152481/f4c855f5-87c4-4534-b72d-5b19d1aae0b0)

### Binary Data

![Binary Data](https://github.com/buggregator/trap/assets/4152481/cd8788ed-b10c-4b9a-b2e2-baa8912ea38d)

### SMTP Mail Trap

![smtp](https://github.com/buggregator/trap/assets/4152481/b11c4a7f-072a-4e66-b11d-9bbd3177bfe2)

### HTTP Dump

![http-dump](https://github.com/buggregator/trap/assets/4152481/48201ce6-7756-4402-8954-76a27489b632)