Symfony Yoandev Observability

Observability

Tier: on demand — channels and redaction matter from the first production deploy; correlation ids, the worker heartbeat and health probes are switched on by a real worker, a real orchestrator, a real incident.

An application that reaches production and then goes silent is not finished. This skill covers what the application emits and how it is structured: channels, levels, processors, redaction, alerts, health. Where logs go is infrastructure and out of scope — a file, stdout, a managed aggregator, a Grafana stack. The prod handler configuration (php://stderr, JSON) is already symfony-yoandev-deployment's; profiling and Stopwatch are symfony-yoandev-performance's; the dev server's log stream is symfony-yoandev-local-dev's.

The pact this suite already made

The standard mandates #[WithLogLevel] on expected business exceptions so they stop drowning real failures. That only pays off if something watches what remains. The ladder Symfony applies, from ErrorListener::resolveLogLevel():

So critical means "a request or a message died on something nobody planned for", and that is the level an alert handler subscribes to; error is not a useful threshold, because every 404 that excluded_http_codes does not filter lands there. framework.exceptions also takes a log_channel, moving a whole family of expected exceptions off the request channel entirely — log_channel: business with log_level: info produces business.INFO, verified on 8.1 (check config:dump-reference framework exceptions on an older version).

Channels

A single log stream stops being readable at the size where you would actually need it: on any real page Doctrine alone emits one record per statement, Messenger one per dispatch, the cache one per miss, and the ten lines your own code wrote are a rounding error. Channels are how you filter before the data leaves the process. Symfony ships them already — doctrine, messenger, request, security, cache, http_client, mailer, console, router, event, php, deprecation — so add your own with monolog.channels: ['deprecation', 'business', 'alert'] for anything worth watching separately, then inject that channel's logger. Four ways work, verified on monolog-bundle 4.0:

One trap, measured. #[Target] and #[Autowire(service:)] fail at compile time on a typo, listing every channel that does exist. #[WithMonologChannel] does not: a misspelt channel is silently created, escapes every handler filter, and nothing warns you. debug:container --tag=monolog.channel_logger lists them; a name you do not recognise is a typo.

fingers_crossed, and why a working request logs nothing

The prod recipe wraps the stream handler in fingers_crossed. It buffers everything and writes nothing until one record reaches action_level (error by default), then flushes the entire buffer — the debug trail that led to the failure — and keeps passing records through for the rest of the process. Two consequences people report as bugs: a successful request writes zero lines (so info calls tracing a happy path never appear in production), and a failing one dumps up to buffer_size (50 in the recipe) records at once, including every Doctrine statement with its bound parameter values — the point of the mechanism, and the biggest single source of secrets in logs.

In a Messenger worker the handler is reset between messages (kernel.reset, via Messenger's ResetServicesListener), so a failing message flushes its own trail and a successful one stays silent, exactly as in a request. passthru_level and excluded_http_codes: references/monolog.md.

One user action, several processes

A correlation id is what makes a request and the workers it spawned readable as one story. Three pieces: a holder service resolving the id from an X-Request-Id header or generating one (implementing ResetInterface, so a long-running worker does not reuse it); a Monolog processor putting it on every record; a Messenger middleware stamping outgoing envelopes and restoring the id in the worker.

#[AsMonologProcessor]
final readonly class CorrelationIdProcessor
{
    public function __construct(private CorrelationId $correlationId) {}

    public function __invoke(LogRecord $record): LogRecord
    {
        $record->extra['correlation_id'] = $this->correlationId->get();

        return $record;
    }
}

Measured end to end: an id generated in the dispatching process appeared on all 29 records the worker wrote while handling that message, including the framework's own messenger.CRITICAL. This needs no kernel listener — the holder reads RequestStack, which keeps it inside the "kernel listeners are a last resort" rule. Full code, plus the user/token processor: references/monolog.md. #[AsMonologProcessor] is monolog-bundle 3.8+ (priority:, Monolog 3.4 and monolog-bundle 3.11); below that, tag monolog.processor in YAML.

What must never be logged

A log ends up in a backup, in a third-party aggregator, and in a support screenshot. Passwords, tokens, API keys, session ids, card and bank numbers, and personal data beyond what you need to identify the actor do not belong there.

The mechanism is a redacting processor at low priority — it runs before the handlers' own PSR-3 interpolation, so {password} in a message string is redacted too (verified). The trap it cannot fix is a value you concatenated into the message yourself: put data in the context array, never in the message string. The leak to check first is doctrine.dbal.logging — it defaults to %kernel.debug%, so it is off in production, but anyone who switches it on to chase a slow query starts writing every bound parameter at debug, and fingers_crossed flushes those on the next error. Sinks and the processor code: references/sensitive-data.md.

The Messenger failure alert

symfony-yoandev-async states the rule — a message reaching the failure transport must raise an alert — without the mechanism. Here it is: what the framework already does, what a listener adds, and the sink that decides whether any of it is an alert.

The framework already logs it. SendFailedMessageForRetryListener writes messenger.CRITICAL: Error thrown while handling message … Removing from transport after N retries the moment retries are exhausted, before SendFailedMessageToFailureTransportListener (priority -100) moves the envelope. If critical already reaches a human, you are done.

A listener adds the structure — #[AsEventListener] on WorkerMessageFailedEvent, guarded on willRetry() so the three retries stay quiet:

// The canonical copy is references/alerting.md; this one is identical to it.
#[AsEventListener]
#[WithMonologChannel('alert')]
final readonly class AlertOnMessageSentToFailureTransport
{
    public function __construct(private LoggerInterface $logger) {}

    public function __invoke(WorkerMessageFailedEvent $event): void
    {
        if ($event->willRetry()) {
            return;
        }

        $envelope = $event->getEnvelope();

        $this->logger->critical('Message moved to the failure transport', [
            'message_class' => $envelope->getMessage()::class,
            'transport' => $event->getReceiverName(),
            'retries' => RedeliveryStamp::getRetryCountFromEnvelope($envelope),
            'exception' => $event->getThrowable(),
        ]);
    }
}

The sink is the part that decides whether it is an alert. And here is the finding that matters: do not send it by email. Verified — with SendEmailMessage routed to async as this standard requires, a symfony_mailer Monolog handler produces messenger.INFO: Sending message SendEmailMessage with async sender. The alert about the broken queue is queued on the broken queue. Use a sink that does not re-enter Messenger — a slackwebhook handler, error_log, Sentry, or critical on stderr with the platform's own alerting rule — and wrap a third-party sink in a fallbackgroup handler: an unreachable webhook throws, and Monolog lets that exception turn a logged error into a 500 (measured).

A listener cannot fire if no worker is running, which is the most common reason a queue rots. That needs the second mechanism: a worker heartbeat written on WorkerRunningEvent, plus a probe on queue depth — both in references/alerting.md, with the console commands (messenger:stats --format=json, messenger:failed:show --stats) for the shell-script version.

Health checks

A route returning 200 unconditionally tells the orchestrator the container has booted, not that the application works. Test the dependencies:

public function run(): bool
{
    return 1 === (int) $this->connection
        ->executeQuery($this->connection->getDatabasePlatform()->getDummySelectSQL())
        ->fetchOne();
}

Two deliberate exceptions to the standard live in this endpoint, and both are exceptions rather than oversights. The first is here: this is SQL outside a repository. It is allowed because it is not a query about the domain — there is no intent to name and no result to map, it is a connectivity probe — so it stays in a dedicated Health\ service where the exception remains visible instead of spreading. The second is below.

getDummySelectSQL() is portable where a literal SELECT 1 is not (Oracle needs FROM DUAL). Collect the checks with #[AutoconfigureTag] on a HealthCheck interface and #[AutowireLocator] in the controller — with an iterator each check is built by the foreach, outside any try, and one unbuildable check 500s the whole endpoint (measured). Return 503 when any check fails; a probe that always answers 200 is decorative.

That is the second exception: the standard says an action returns data and #[Serialize] decides the representation, but #[Serialize]'s code is fixed at attribute level, so it cannot express a status that depends on the result. A bare JsonResponse is therefore correct here — because the attribute genuinely cannot do it, not because it was more convenient — and nowhere else.

Verified running: {"status":"degraded","checks":{"database":"ok","failure_queue":"failed","worker":"ok"}} with HTTP 503. Full implementation, and which checks belong on a liveness versus a readiness probe: references/alerting.md.

Error tracking

Sentry or an equivalent adds what a log line cannot: the same exception grouped across occurrences, a release marker, the request and user attached, and a notification the first time a fingerprint appears. It replaces nothing — the logs are still the trail that led there. On monolog-bundle 4.0 the built-in sentry and raven handler types were removed; integrate through sentry/sentry-symfony and a service-type handler.

The one thing that matters when wiring it: do not send the exceptions #[WithLogLevel] already marked as expected. The log-level route does this for free — an SDK integrated as a Monolog handler at level: critical never sees the info the attribute produced. The SDK's own ignore list is the second lever; read its current config key with debug:config rather than copying one from a blog post.

When nothing shows up

Reference files