feat(logging): OTel semconv field names, redaction and exception processor

Build on the logging foundation (ADR 011):

- Rename RequestContextProcessor fields to OpenTelemetry semantic
  conventions (http.request.method, http.route, url.path, client.address,
  enduser.id, screen.id, tenant.key); request_id/trace_id/span_id stay.
- SensitiveDataProcessor (lowest priority, runs last) truncates
  client.address to a GDPR-safe form (IPv4 drops last octet, IPv6 keeps
  the /48) and redacts secret-bearing keys anywhere in context/extra.
- ExceptionContextProcessor serialises a Throwable under the `exception`
  context key into a structured array with a depth-bounded previous chain,
  so no raw stack-trace string is emitted at info level.
- Document the contract in docs/logging.md (channels, levels, message and
  context rules, field names, redaction guarantees).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: turegjorup

.env

@@ -120,8 +120,6 @@ SESSION_HANDLER_DSN=${REDIS_CACHE_DSN}
 HTTP_CLIENT_TIMEOUT=5
 # Maximum total duration in seconds for an HTTP request including transfer.
 HTTP_CLIENT_MAX_DURATION=30
-# Log level for outgoing HTTP requests (debug, info, notice, warning, error).
-HTTP_CLIENT_LOG_LEVEL=error
 ###< Http Client ###
 
 ###> Logging ###
@@ -146,6 +144,8 @@ LOG_LEVEL_INTERACTIVE=
 # Threshold for Symfony's built-in cache channel (cache-adapter/Redis failures);
 # not an application channel. Empty or unset inherits LOG_LEVEL.
 LOG_LEVEL_CACHE=
+# Per-channel override (outbound HTTP client); empty or unset inherits LOG_LEVEL.
+LOG_LEVEL_OUTBOUND_HTTP=
 ###< Logging ###
 
 ###> App ###

CHANGELOG.md

@@ -21,6 +21,14 @@ All notable changes to this project will be documented in this file.
 - Renamed the outbound-HTTP-client log channel `app_http` → `outbound_http` and silenced
   Symfony's redundant native `http_client` channel logging (a `NullLogger` decorates it), so
   `LoggingHttpClient` is the single source of outbound-HTTP logs (no duplicate request logging).
+- Adopted OpenTelemetry semantic-convention field names for log records (including the HTTP
+  client's `http.request.method` / `url.full` / `http.response.status_code` /
+  `http.client.request.duration`), added GDPR-safe client-address truncation and secret-key
+  redaction (`SensitiveDataProcessor`), and structured exception serialization under the
+  `exception` context key (`ExceptionContextProcessor`). See `docs/logging.md`.
+  The HTTP client now logs completed requests at `info` and failures at `error` on the
+  `outbound_http` channel, thresholded by the new `LOG_LEVEL_OUTBOUND_HTTP` like every
+  other channel; the `HTTP_CLIENT_LOG_LEVEL` env var is removed (use `LOG_LEVEL_OUTBOUND_HTTP`).
 - Removed the deprecated feed types `SparkleIOFeedType`, `EventDatabaseApiFeedType` and `KobaFeedType`.
   Made the unknown-feed-type handling consistent: **reads degrade, writes are rejected.** Feed sources
   (and feeds) that reference a removed type keep loading — item and collection reads return them with no

README.md

@@ -578,6 +578,7 @@ LOG_LEVEL_MEDIA=
 LOG_LEVEL_FEED=
 LOG_LEVEL_INTERACTIVE=
 LOG_LEVEL_CACHE=
+LOG_LEVEL_OUTBOUND_HTTP=
 ###< Logging ###
 ```
 
@@ -591,9 +592,16 @@ LOG_LEVEL_CACHE=
   `critical`). `info` reproduces the previous output.
 
   **Default**: `info`.
-- LOG_LEVEL_AUTH, LOG_LEVEL_SCREEN, LOG_LEVEL_MEDIA, LOG_LEVEL_FEED, LOG_LEVEL_INTERACTIVE, LOG_LEVEL_CACHE:
-  Per-channel threshold overrides. Empty or unset inherits `LOG_LEVEL`. Set one to raise or lower a single channel
-  (e.g. `LOG_LEVEL_FEED=warning`) without affecting the others. An invalid level fails fast at boot.
+- LOG_LEVEL_AUTH, LOG_LEVEL_SCREEN, LOG_LEVEL_MEDIA, LOG_LEVEL_FEED, LOG_LEVEL_INTERACTIVE, LOG_LEVEL_CACHE,
+  LOG_LEVEL_OUTBOUND_HTTP: Per-channel threshold overrides. Empty or unset inherits `LOG_LEVEL`. Set one to raise
+  or lower a single channel (e.g. `LOG_LEVEL_FEED=warning`) without affecting the others. An invalid level fails
+  fast at boot. (`LOG_LEVEL_CACHE` gates Symfony's built-in cache-adapter channel — Redis backend failures — not an
+  application channel.)
+
+The `outbound_http` channel carries outbound HTTP client logs (`LoggingHttpClient`): completed requests at
+`info`, failures at `error` — controlled by `LOG_LEVEL_OUTBOUND_HTTP` like every other channel. Symfony's
+built-in `http_client` channel (native, request-only logging) is silenced with a `NullLogger`, so
+`LoggingHttpClient` is the single source.
 
 ### Admin configuration
 

UPGRADE.md

@@ -98,7 +98,7 @@ APP_REDIS_CACHE_DSN                              → REDIS_CACHE_DSN
 
 APP_HTTP_CLIENT_TIMEOUT                          → HTTP_CLIENT_TIMEOUT
 APP_HTTP_CLIENT_MAX_DURATION                     → HTTP_CLIENT_MAX_DURATION
-APP_HTTP_CLIENT_LOG_LEVEL                        → HTTP_CLIENT_LOG_LEVEL
+APP_HTTP_CLIENT_LOG_LEVEL                        → LOG_LEVEL_OUTBOUND_HTTP
 
 APP_INTERNAL_OIDC_METADATA_URL                   → INTERNAL_OIDC_METADATA_URL
 APP_INTERNAL_OIDC_CLIENT_ID                      → INTERNAL_OIDC_CLIENT_ID

config/packages/prod/monolog.yaml

@@ -14,7 +14,7 @@ monolog:
         outbound_http:
             type: stream
             path: '%env(resolve:LOG_PATH)%'
-            level: info
+            level: '%env(default:app.log_level:LOG_LEVEL_OUTBOUND_HTTP)%'
             channels: ['outbound_http']
             formatter: monolog.formatter.json
         # One always-on handler per domain channel. A Monolog handler carries a

config/services.yaml

@@ -56,7 +56,6 @@ services:
         arguments:
             $client: '@.inner'
             $logger: '@monolog.logger.outbound_http'
-            $logLevel: '%env(string:HTTP_CLIENT_LOG_LEVEL)%'
 
     # Silence Symfony's native http_client logging at the source: it is
     # request-only and redundant with LoggingHttpClient (outbound_http channel),
@@ -75,6 +74,14 @@ services:
     App\Logger\Processor\TraceContextProcessor:
         tags: [{ name: monolog.processor }]
 
+    App\Logger\Processor\ExceptionContextProcessor:
+        tags: [{ name: monolog.processor, priority: -90 }]
+
+    # Lowest priority: runs last so it scrubs everything the other processors
+    # added (e.g. the raw client.address set by RequestContextProcessor).
+    App\Logger\Processor\SensitiveDataProcessor:
+        tags: [{ name: monolog.processor, priority: -100 }]
+
     # Logs security outcomes on the `auth` channel (logging only).
     App\Logger\EventSubscriber\AuthLoggingSubscriber:
         arguments:

docs/logging.md

@@ -0,0 +1,133 @@
+# Logging
+
+This service emits **structured JSON logs** to `php://stderr`. Every record is enriched
+with request, identity and trace context, and serialised so it can be ingested by a log
+aggregator later without changes here. The decisions behind this are recorded in
+[ADR 011](adr/011-structured-logging.md).
+
+The conventions below are **enforced in CI** by project-local PHPStan rules
+(`logging.silentCatch`, `logging.interpolatedLogMessage`, `logging.exceptionContextKey`).
+A build fails if you break them.
+
+## Channels
+
+Inject a channel-specific logger instead of the generic one, so records can be routed and
+filtered per domain. Bind the channel in `config/services.yaml`:
+
+```yaml
+App\Service\FeedService:
+    arguments:
+        $logger: '@monolog.logger.feed'
+```
+
+| Channel | Use for |
+|---|---|
+| `outbound_http` | Outbound HTTP client calls (`LoggingHttpClient`). Named to stay clear of Symfony's built-in `http_client` channel, whose native (request-only) logging is silenced with a `NullLogger`. |
+| `auth` | Authentication and authorization outcomes (login, logout, JWT/OIDC). |
+| `screen` | Screen-client binding, screen authentication, screen status. |
+| `media` | Media upload, thumbnailing, storage. |
+| `feed` | Feed fetching/parsing (`FeedService`, feed types). |
+| `interactive` | Interactive slides (booking, instant book). |
+| `cache` | **Not an application channel** — Symfony's built-in cache-adapter channel. Given a dedicated handler so cache-adapter (Redis) backend failures surface instead of being dropped by the `fingers_crossed` gate. No application code writes to it. |
+| `database` | Database connection failures (see below). |
+
+## Level guidance
+
+| Level | When |
+|---|---|
+| `debug` | Developer detail; verbose, off in production action buffering. |
+| `info` | Normal, noteworthy events (auth success, batch completed). |
+| `notice` | Normal but significant (config fallback applied). |
+| `warning` | Something recoverable went wrong (auth failure, flapping feed, malformed payload). |
+| `error` | An operation failed and a user/screen is affected. |
+| `critical` | A subsystem is down (database connection pressure/unreachable). |
+
+## Message and context rules
+
+1. **The message is a static string.** Never interpolate variables into it.
+
+   ```php
+   // ❌ flagged by logging.interpolatedLogMessage
+   $logger->warning("Feed {$source->getId()} failed");
+
+   // ✅ static message, data in context
+   $logger->warning('Feed fetch failed', ['feed_source_id' => (string) $source->getId()]);
+   ```
+
+   PSR-3 `{placeholder}` braces resolved from the context array are fine.
+
+2. **Exceptions go under the `exception` context key — never any other key, never
+   interpolated.**
+
+   ```php
+   // ❌ flagged by logging.exceptionContextKey
+   $logger->error('Booking failed', ['error' => $e]);
+
+   // ✅
+   $logger->error('Booking failed', ['exception' => $e]);
+   ```
+
+   `ExceptionContextProcessor` turns the `\Throwable` into a structured array
+   (`class`, `message`, `code`, `file`, `line`, bounded `previous` chain). No raw
+   multi-line stack-trace string is emitted at info level.
+
+3. **Never swallow an exception silently.** A `catch` must log it (under `exception`),
+   rethrow it (optionally wrapped), or be explicitly annotated when the silence is
+   intentional:
+
+   ```php
+   try {
+       $optional = $this->parse($payload);
+   } catch (\JsonException $e) {
+       // @phpstan-ignore logging.silentCatch (optional metadata; absence is expected)
+   }
+   ```
+
+   This is enforced by `logging.silentCatch`.
+
+## Field names (OpenTelemetry semantic conventions)
+
+Field names follow [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/)
+as strictly as the framework allows, so the logs stay forward-compatible with an OTel
+collector should one be introduced:
+
+| Field | Meaning |
+|---|---|
+| `request_id` | Per-request id (inbound `X-Request-Id` or minted). |
+| `http.request.method` | HTTP method. |
+| `http.route` | Matched route's **path template**, e.g. `/v2/screens/{id}` — id-free and low-cardinality, with the API Platform `.{_format}` suffix stripped. **Set only when a route matched** (per OTel guidance), and **never** the concrete id-bearing URL. |
+| `url.path` | The concrete request path, **including** ids (e.g. `/v2/screens/01HXYZ…`). This is the field that carries the real path; `http.route` is its templated, id-free counterpart. |
+| `client.address` | **Truncated** client address (see redaction). |
+| `enduser.id` | Back-office user identifier. |
+| `screen.id` | Screen id (for screen-token requests). |
+| `tenant.key` | Active tenant key. |
+| `trace_id` / `span_id` | W3C trace context, when a `traceparent` header is present. |
+
+Strict OTel notes: `http.route` is the **path template** the server matched, not the
+Symfony route *name* and not the concrete path; it is omitted entirely (rather than set to
+an empty/placeholder value) when no route matched. `enduser.id` and `screen.id` are mutually
+exclusive. Fields that don't apply to a record are absent, never `null`.
+
+### `extra` (ambient request) vs `context` (the event)
+
+The processors above add the **inbound** request's attributes to every record's `extra`
+(`http.request.method`, `http.route`, `url.path`, `client.address`, …). A log *call* may
+put its own subject's attributes in `context` using the same OTel names — for example the
+outbound HTTP client (`outbound_http` channel) logs `http.request.method` / `url.full` /
+`http.response.status_code` for the call it just made. So a record for an outbound call can
+carry `extra.http.request.method` (the inbound API request) **and** `context.http.request.method`
+(the outbound call). This is intentional and mirrors OTel's server-span vs client-span split:
+`extra` is the ambient request the worker is serving; `context` is the event being logged.
+The two stay in separate bags, so there is no key collision.
+
+## Redaction guarantees
+
+`SensitiveDataProcessor` runs last and is a backstop, not a license to log secrets:
+
+- `client.address` is **truncated** — IPv4 drops the last octet (`203.0.113.5` →
+  `203.0.113.0`); IPv6 keeps the `/48` and zeroes the rest. No full client IP is emitted.
+- Any key whose name contains `password`, `passwd`, `secret`, `authorization`, `api_key`,
+  `apikey`, `token`, `credential` or `bearer` is replaced with `[redacted]`, at any depth
+  in `context`/`extra`.
+
+Still: do not put credentials or token strings into log context in the first place.

src/HttpClient/LoggingHttpClient.php

@@ -14,7 +14,6 @@ class LoggingHttpClient implements HttpClientInterface
     public function __construct(
         private HttpClientInterface $client,
         private readonly LoggerInterface $logger,
-        private readonly string $logLevel = 'error',
     ) {}
 
     public function request(string $method, string $url, array $options = []): ResponseInterface
@@ -26,30 +25,41 @@ public function request(string $method, string $url, array $options = []): Respo
         try {
             $statusCode = $response->getStatusCode();
         } catch (\Throwable $throwable) {
-            $duration = round((microtime(true) - $startTime) * 1000);
-
-            $this->logger->error('{method} {url} failed after {duration}ms: {error}', [
-                'method' => $method,
-                'url' => $url,
-                'duration' => $duration,
-                'error' => $throwable->getMessage(),
+            // OTel semantic conventions for an HTTP client call; the exception
+            // goes under the `exception` key so ExceptionContextProcessor
+            // serialises it (see docs/logging.md).
+            $this->logger->error('{http.request.method} {url.full} failed', [
+                'http.request.method' => $method,
+                'url.full' => $url,
+                'http.client.request.duration' => $this->durationSeconds($startTime),
+                'exception' => $throwable,
             ]);
 
             throw $throwable;
         }
 
-        $duration = round((microtime(true) - $startTime) * 1000);
-
-        $this->logger->log($this->logLevel, '{method} {url} {status_code} {duration}ms', [
-            'method' => $method,
-            'url' => $url,
-            'status_code' => $statusCode,
-            'duration' => $duration,
+        // Natural severity: a completed request is info; failures log at error
+        // (above). Visibility is controlled by the outbound_http handler
+        // threshold (LOG_LEVEL_OUTBOUND_HTTP), consistent with every channel.
+        $this->logger->info('{http.request.method} {url.full} {http.response.status_code} ({http.client.request.duration}s)', [
+            'http.request.method' => $method,
+            'url.full' => $url,
+            'http.response.status_code' => $statusCode,
+            'http.client.request.duration' => $this->durationSeconds($startTime),
         ]);
 
         return $response;
     }
 
+    /**
+     * Elapsed time since $startTime in seconds (OTel
+     * `http.client.request.duration` unit), rounded to 0.1 ms.
+     */
+    private function durationSeconds(float $startTime): float
+    {
+        return round(microtime(true) - $startTime, 4);
+    }
+
     public function stream(ResponseInterface|iterable $responses, ?float $timeout = null): ResponseStreamInterface
     {
         return $this->client->stream($responses, $timeout);

src/Logger/Processor/ExceptionContextProcessor.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logger\Processor;
+
+use Monolog\LogRecord;
+use Monolog\Processor\ProcessorInterface;
+
+/**
+ * Replaces a `\Throwable` under the `exception` context key with a structured
+ * array (class, message, code, file, line and a bounded `previous` chain) so a
+ * raw multi-line stack-trace string is never emitted at info level in
+ * production. Non-exception context is left untouched.
+ */
+final class ExceptionContextProcessor implements ProcessorInterface
+{
+    private const MAX_DEPTH = 5;
+
+    public function __invoke(LogRecord $record): LogRecord
+    {
+        $context = $record->context;
+        if (isset($context['exception']) && $context['exception'] instanceof \Throwable) {
+            $context['exception'] = $this->normalize($context['exception'], self::MAX_DEPTH);
+
+            return $record->with(context: $context);
+        }
+
+        return $record;
+    }
+
+    /** @return array<string, mixed> */
+    private function normalize(\Throwable $e, int $depth): array
+    {
+        $data = [
+            'class' => $e::class,
+            'message' => $e->getMessage(),
+            'code' => $e->getCode(),
+            'file' => $e->getFile(),
+            'line' => $e->getLine(),
+        ];
+
+        $previous = $e->getPrevious();
+        if (null !== $previous && $depth > 1) {
+            $data['previous'] = $this->normalize($previous, $depth - 1);
+        }
+
+        return $data;
+    }
+}