aubes/correlation-bundle

Lightweight distributed tracing for Symfony. Propagates a correlation ID across your entire stack (HTTP, HTTP Client, Monolog, Messenger, Mercure, Twig) without the overhead of a full APM solution.

Worker-mode ready: the storage implements ResetInterface and is scoped per request/message. Works out of the box with FrankenPHP worker mode and Messenger workers.

Requirements

• PHP >= 8.2
• Symfony 6.4 / 7.4 / 8.x

Installation

composer require aubes/correlation-bundle

The bundle auto-registers via Symfony Flex.

How it works

The bundle captures or generates a correlation ID at the start of each HTTP request or console command, stores it in a request-scoped storage, and propagates it to all configured integrations.

Core (always active)

• Storage: CorrelationIdStorage is final, self-materializes an ID via the configured generator on first get(), and memoizes the result
• Contract: CorrelationIdProviderInterface::get() always returns a valid, non-null string
• Validation: set() validates its input (printable ASCII, 1-255 chars) and throws InvalidCorrelationIdException on invalid values. Last write wins
• Reset: implements ResetInterface for worker/long-running process safety
• Console: correlation ID generated automatically per command, overridable via --correlation-id

HTTP (always active)

• Captures X-Correlation-Id from incoming requests (configurable header name)
• Generates a new ID when the header is missing
• Echoes the ID in the response header

Optional integrations

Each integration activates automatically when its dependency is installed, and can be explicitly disabled.

Configuration

# config/packages/correlation.yaml
correlation:
    # Core
    generator: 'Aubes\CorrelationBundle\Generator\UuidCorrelationIdGenerator'  # or Hex32CorrelationIdGenerator
    uuid_version: 7  # 4, 6, or 7 (ignored when using a non-UUID generator)

    # HTTP
    http:
        header_name: 'X-Correlation-Id'
        send_response_header: true

    # Optional integrations
    http_client:
        enabled: true
        header: 'X-Correlation-Id'
        force_header: true  # false = caller-provided header takes precedence
        clients: ['http_client']

    monolog:
        enabled: true
        field_name: 'correlation_id'
        channels: []   # empty = all channels
        handlers: []   # empty = all handlers

    messenger:
        enabled: true
        buses: []      # empty = all buses

    mercure:
        enabled: true
        field_name: 'correlation_id'
        hubs: ['default']

    twig:
        enabled: true

All values shown above are defaults. Zero configuration is needed for the common case.

Interfaces

CorrelationIdProviderInterface

Read-only access. Inject this when you only need to read the current ID.

use Aubes\CorrelationBundle\Storage\CorrelationIdProviderInterface;

final class MyService
{
    public function __construct(private readonly CorrelationIdProviderInterface $provider) {}

    public function doSomething(): void
    {
        $correlationId = $this->provider->get(); // guaranteed non-null
    }
}

CorrelationIdStorageInterface

Full access: read, write, and reset. Extends CorrelationIdProviderInterface and ResetInterface.

public function get(): string;
public function set(string $id): void; // throws InvalidCorrelationIdException
public function reset(): void;

CorrelationIdGeneratorInterface

public function generate(): string;

Extension points

Built-in generators

To switch generator:

correlation:
    generator: 'Aubes\CorrelationBundle\Generator\Hex32CorrelationIdGenerator'

Custom generator

Implement CorrelationIdGeneratorInterface and reference your service:

use Aubes\CorrelationBundle\Generator\CorrelationIdGeneratorInterface;

final class MyGenerator implements CorrelationIdGeneratorInterface
{
    public function generate(): string
    {
        // must return 1-255 printable ASCII characters
        return my_custom_id();
    }
}

correlation:
    generator: App\MyGenerator

Note: the service referenced by generator must implement Aubes\CorrelationBundle\Generator\CorrelationIdGeneratorInterface.

Seed the ID from a custom context

Inject CorrelationIdStorageInterface and call $storage->set($id) before the first downstream read:

use Aubes\CorrelationBundle\Exception\InvalidCorrelationIdException;

try {
    $storage->set($idFromExternalSource);
} catch (InvalidCorrelationIdException) {
    // untrusted source: fall back to the generator
}

Debug

The correlation:debug command displays active integrations, the generator class, and the current correlation ID:

php bin/console correlation:debug

When the Web Profiler is enabled, a correlation ID panel shows the ID source (generated vs provided) and the list of active integrations.

License

MIT