Observabilité PHP — trois signaux, un fil conducteur

Logs Monolog, traces OTel et métriques — reliés par le trace_id pour une corrélation directe dans Grafana.

Observer une application PHP en production, c'est collecter trois types de signaux en continu : des logs pour comprendre ce qui s'est passé, des métriques pour mesurer le comportement global, et des traces pour suivre une requête de bout en bout.

OpenTelemetry PHP unifie les traces et les métriques sous un seul SDK. Pour les logs, Monolog reste l'outil de référence — et on les relie aux traces via le trace_id.

Monolog — logs structurés en JSON

Du texte opaque vers du JSON indexable. La différence entre grep et LogQL.

Monolog est le logger standard de l'écosystème PHP. Symfony l'intègre nativement. Son architecture en handlers, processors et formatters permet de produire des logs structurés envoyés vers plusieurs destinations simultanément.

Configuration Symfony pour des logs JSON vers stdout (idéal pour les conteneurs) :

# config/packages/monolog.yaml
monolog:
  handlers:
    main:
      type:      stream
      path:      php://stdout
      level:     debug
      formatter: Monolog\Formatter\JsonFormatter
      channels:  ["!event"]

Les processors enrichissent automatiquement chaque enregistrement. Les plus utiles :

SDK OpenTelemetry PHP — installation et configuration

Trois packages Composer, cinq variables d'environnement, zéro ligne de code de démarrage.

Le SDK OpenTelemetry PHP est composé de plusieurs packages Composer : le cœur (open-telemetry/sdk), l'exporteur OTLP (open-telemetry/exporter-otlp), et des packages d'auto-instrumentation spécifiques à chaque bibliothèque ou framework.

La quasi-totalité de la configuration se fait via des variables d'environnement, sans modifier le code applicatif :

# .env.local ou docker-compose.yml
OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=mon-service
OTEL_SERVICE_VERSION=1.4.2
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_PROPAGATORS=tracecontext,baggage

Avec OTEL_PHP_AUTOLOAD_ENABLED=true, le SDK s'initialise automatiquement via le mécanisme de hooks PHP. Il n'y a aucune ligne de code à ajouter dans public/index.php.

Parmi ces variables, OTEL_TRACES_SAMPLER=traceidratio mérite qu'on s'y arrête : en production, tracer 100 % des requêtes coûte cher en stockage. L'échantillonnage n'en garde qu'une fraction. Le simulateur ci-dessous le rend tangible — règle le taux et regarde, sur un flux continu, quelles requêtes sont tracées ou jetées. À 10 %, tu n'en stockes qu'une sur dix, assez pour observer sans exploser la facture.

Auto-instrumentation — les spans gratuits

Requêtes HTTP, controllers, clients HTTP sortants — instrumentés automatiquement par des hooks PHP.

L'auto-instrumentation installe des hooks PHP sur les fonctions des bibliothèques cibles. Tu n'écris rien — les spans apparaissent dès que le code instrumenté est exécuté.

Chaque package d'auto-instrumentation cible une bibliothèque :

Les attributs ajoutés par l'auto-instrumentation Symfony respectent les Semantic Conventions OTel : http.request.method, http.route, http.response.status_code, server.address. Ces noms standardisés rendent les dashboards Grafana interopérables entre projets.

Instrumentation manuelle — le contexte métier

spanBuilder() + setAttribute() + addEvent() + recordException() — le pattern complet en PHP.

L'auto-instrumentation donne les spans d'infrastructure. Pour ajouter du contexte métier — le montant d'une commande, l'ID utilisateur, l'étape d'un workflow — tu utilises l'API OTel directement dans ton code.

use OpenTelemetry\API\Globals;
use OpenTelemetry\API\Trace\StatusCode;

$tracer = Globals::tracerProvider()->getTracer('mon-service');

$span = $tracer->spanBuilder('processOrder')
    ->setAttribute('order.id', $orderId)
    ->setAttribute('order.amount', $amount)
    ->startSpan();

$scope = $span->activate();
try {
    // ... logique métier ...
    $span->addEvent('stock.reserved', ['quantity' => $qty]);
    $span->setStatus(StatusCode::STATUS_OK);
} catch (\Throwable $e) {
    $span->recordException($e);
    $span->setStatus(StatusCode::STATUS_ERROR, $e->getMessage());
    throw $e;
} finally {
    $scope->detach();
    $span->end();
}

Corrélation — du log d'erreur à la trace en un clic

TraceIdProcessor injecte le trace_id dans Monolog. Grafana crée le lien Loki → Tempo automatiquement.

Le trace_id est le lien entre les logs Monolog et les traces Tempo. Si chaque log contient le trace_id de la requête en cours, tu peux passer d'une ligne de log d'erreur à la trace complète en un clic dans Grafana.

use Monolog\LogRecord;
use OpenTelemetry\API\Trace\Span;

final class TraceIdProcessor
{
    public function __invoke(LogRecord $record): LogRecord
    {
        $span    = Span::getCurrent();
        $context = $span->getContext();

        if (!$context->isValid()) {
            return $record;
        }

        return $record->with(extra: array_merge(
            $record->extra,
            [
                'trace_id' => $context->getTraceId(),
                'span_id'  => $context->getSpanId(),
            ]
        ));
    }
}

Enregistre ce processor dans config/packages/monolog.yaml sous la clé processors. Chaque log émis pendant une requête instrumentée portera désormais trace_id et span_id dans son JSON.

Synthèse — stack LGTM complet en PHP

Checklist en 7 étapes, considérations de performance, pièges courants.

L'observabilité complète d'une application PHP/Symfony repose sur trois intégrations qui se renforcent mutuellement : Monolog en JSON pour les logs, le SDK OTel pour les traces, et un TraceIdProcessor pour les corréler.

Checklist d'intégration

Considérations de performance

Le SDK OTel PHP utilise un exporter synchrone par défaut : chaque span est envoyé au Collector à la fin de la requête, ce qui peut ajouter quelques millisecondes. En production, configure l'exporter batch (BatchSpanProcessor) qui accumule les spans en mémoire et les envoie périodiquement en arrière-plan.

Pour réduire le volume, configure le sampler :

# 10% des traces — adapte selon ton volume
OTEL_TRACES_SAMPLER=traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

# Mieux : head sampling côté app + tail sampling dans le Collector
# Le Collector garde 100% des traces en erreur, 5% des OK

Avec ces sept étapes en place, chaque requête de ta Symfony est observable de bout en bout : tu vois les spans dans Tempo, les logs dans Loki, et tu passes de l'un à l'autre via le trace_id dans Grafana — le mode Explore te donne la réponse en quelques secondes lors d'un incident.