README

Sauron is a transparent HTTP proxy and APM dashboard for API observability. This bundle instruments Symfony applications by reading the traceparent header the Sauron proxy injects and reporting controller and db spans to the dashboard — giving you end-to-end trace waterfalls with zero manual code changes.

Architecture

Browser / API client
        │
        ▼
Sauron proxy  :8080   ──────────────────────────▶  Symfony app  :9000
  (profiler)          injects traceparent header     (your app)
        │                                                 │
        │  stores proxy spans                             │  kernel.terminate
        ▼                                                 ▼
  profiler.db  ◀─────────── shared storage ─────  Sauron dashboard  :9090
  (SQLite/PG)                                       POST /ingest/spans

Traffic goes through the Sauron proxy, which records latency, status codes, and injects a W3C traceparent header. The bundle picks up that header inside Symfony and reports child spans (controller timing, DB queries) back to the dashboard after the response is sent.

Installation

composer require sauron/symfony-bundle

Register the bundle in config/bundles.php:

return [
    // ...
    Sauron\Bundle\SauronBundle::class => ['all' => true],
];

Create config/packages/sauron.yaml:

sauron:
  enabled: true
  endpoint: '%env(SAURON_ENDPOINT)%'
  service_name: '%env(APP_NAME)%'

Add to .env:

SAURON_ENDPOINT=http://localhost:9090/ingest/spans
APP_NAME=my-symfony-app

That's it. Requests routed through the Sauron proxy will now appear as full trace waterfalls in the dashboard.

Prerequisites

• PHP ≥ 8.1, Symfony ≥ 6.0
• Sauron binaries built from cmd/profiler and cmd/dashboard (see Step 1)
• ext-curl or allow_url_fopen=1 for flushing spans
• (Optional) doctrine/dbal ≥ 3.0 and DoctrineBundle for automatic DB query spans

Step-by-step integration

Step 1 — Build Sauron binaries

go build -o profiler ./cmd/profiler
go build -o dashboard ./cmd/dashboard

Step 2 — Start the proxy and dashboard

Point the proxy at your Symfony app and use a shared storage file:

./profiler --upstream http://localhost:9000 --port 8080 --storage-dsn profiler.db
./dashboard --listen :9090 --storage-dsn profiler.db

profiler key flags

dashboard key flags

Step 3 — Install the bundle

composer require sauron/symfony-bundle

Step 4 — Register the bundle

Add to config/bundles.php:

return [
    // ...
    Sauron\Bundle\SauronBundle::class => ['all' => true],
];

Step 5 — Create config/packages/sauron.yaml

sauron:
  enabled: true
  endpoint: '%env(SAURON_ENDPOINT)%'
  service_name: '%env(APP_NAME)%'
  instrument_doctrine: true
  timeout_ms: 2000

Step 6 — Add environment variables

Add to .env:

SAURON_ENDPOINT=http://localhost:9090/ingest/spans
APP_NAME=my-symfony-app

Step 7 — Verify

Send a request through the proxy and check the dashboard:

curl http://localhost:8080/api/your-endpoint
# Open http://localhost:9090 → Traces → click the trace → see waterfall

How it works

The bundle registers a TraceSubscriber that hooks into the Symfony kernel event lifecycle:

The flush happens in kernel.terminate, after the response is sent to the client — so there is zero latency impact on your users.

The Doctrine middleware wraps the DBAL driver and records one db span per query, parented to the active controller span.

Span hierarchy in the waterfall

HTTP proxy span (created by Sauron proxy)
└── controller  App\Controller\UserController::index   140ms
    ├── db  SELECT users                                  8ms
    ├── db  SELECT orders WHERE user_id = ?              12ms
    └── db  INSERT audit_log                              3ms

Configuration reference

Doctrine instrumentation

• Requires doctrine/dbal ^3.0|^4.0 and DoctrineBundle to be configured
• The bundle auto-registers a doctrine.middleware tag — no manual wiring needed
• Each SQL query becomes a db span, child of the controller span
• SQL is normalized (literals replaced with ?) before storage — safe to log

Adding custom spans

Inject SauronClient and call recordSpan() anywhere in your application:

use Sauron\Bundle\SauronClient;

class MyService
{
    public function __construct(private readonly SauronClient $client) {}

    public function doWork(): void
    {
        $start = microtime(true);

        // ... do work ...

        $this->client->recordSpan(
            name:       'my-service.doWork',
            kind:       'rpc',                        // controller|db|cache|event|view|rpc
            startTime:  new \DateTimeImmutable(),
            durationMs: (microtime(true) - $start) * 1000,
            attributes: ['key' => 'value'],
            status:     'ok',
        );
    }
}

Disabling per environment

# config/packages/test/sauron.yaml
sauron:
  enabled: false

Using PostgreSQL instead of SQLite

Both binaries must point to the same database:

./profiler --storage-driver postgres \
           --storage-dsn "postgres://user:pass@localhost:5432/sauron" \
           --upstream http://localhost:9000

./dashboard --storage-driver postgres \
            --storage-dsn "postgres://user:pass@localhost:5432/sauron"

Troubleshooting