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

CHANGELOG.md

@@ -18,6 +18,10 @@ All notable changes to this project will be documented in this file.
   thresholded by `LOG_LEVEL_<CHANNEL>` (falling back to a global `LOG_LEVEL`), a configurable
   `LOG_PATH` output destination (default `php://stderr`), request/identity/trace-context
   processors, request-id propagation via `X-Request-Id`, and an auth-event logging subscriber.
+- Adopted OpenTelemetry semantic-convention field names for log records, 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`.
 - 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

config/services.yaml

@@ -67,6 +67,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,115 @@
+# 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 |
+|---|---|
+| `app_http` | Outbound HTTP client calls (`LoggingHttpClient`). |
+| `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` | Cache/checksum recalculation and related batch work. |
+| `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)
+
+Context/extra fields follow OTel SemConv so logs line up with the OTLP traces the kiosk
+emits:
+
+| Field | Meaning |
+|---|---|
+| `request_id` | Per-request id (inbound `X-Request-Id` or minted). |
+| `http.request.method` | HTTP method. |
+| `http.route` | Matched Symfony route name. |
+| `url.path` | Request path. |
+| `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. |
+
+## 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/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;
+    }
+}

src/Logger/Processor/RequestContextProcessor.php

@@ -14,9 +14,11 @@
 /**
  * Enriches every log record with request and identity context.
  *
- * Field names here are the interim PR 1 names (request_id, route, method,
- * user_id, screen_id, tenant_id); they are renamed to OpenTelemetry semantic
- * conventions in a later change.
+ * Field names follow OpenTelemetry semantic conventions (http.request.method,
+ * http.route, url.path, client.address, enduser.id, screen.id, tenant.key).
+ * `request_id` is kept as-is. `client.address` is set to the raw client IP here
+ * and truncated to a GDPR-safe form by {@see SensitiveDataProcessor}, which runs
+ * after this processor.
  */
 final readonly class RequestContextProcessor implements ProcessorInterface
 {
@@ -32,25 +34,28 @@ public function __invoke(LogRecord $record): LogRecord
             // No format validation — accept whatever nginx/Traefik passed through.
             $record->extra['request_id'] = $request->attributes->get('_request_id')
                 ?? $request->headers->get('X-Request-Id');
-            $record->extra['route'] = $request->attributes->get('_route');
-            $record->extra['method'] = $request->getMethod();
+            $record->extra['http.route'] = $request->attributes->get('_route');
+            $record->extra['http.request.method'] = $request->getMethod();
+            $record->extra['url.path'] = $request->getPathInfo();
+            // Raw IP; SensitiveDataProcessor truncates it to a GDPR-safe form.
+            $record->extra['client.address'] = $request->getClientIp();
         }
 
         $user = $this->security->getUser();
         if (null !== $user) {
             // Screen tokens authenticate as ScreenUser; everything else is a
             // back-office User. Populate screen_id XOR user_id accordingly.
             if ($user instanceof ScreenUser) {
-                $record->extra['screen_id'] = (string) $user->getScreen()->getId();
+                $record->extra['screen.id'] = (string) $user->getScreen()->getId();
             } else {
-                $record->extra['user_id'] = $user->getUserIdentifier();
+                $record->extra['enduser.id'] = $user->getUserIdentifier();
             }
 
             if ($user instanceof TenantScopedUserInterface) {
                 // getActiveTenant() can throw when no tenant is resolved yet;
                 // enrichment must never break the request it is annotating.
                 try {
-                    $record->extra['tenant_id'] = $user->getActiveTenant()->getTenantKey();
+                    $record->extra['tenant.key'] = $user->getActiveTenant()->getTenantKey();
                 } catch (\Throwable) {
                     // No active tenant on this request — leave tenant_id unset.
                 }

src/Logger/Processor/SensitiveDataProcessor.php

@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Logger\Processor;
+
+use Monolog\LogRecord;
+use Monolog\Processor\ProcessorInterface;
+
+/**
+ * GDPR/secret backstop. Runs after the context processors (lower priority) so it
+ * can scrub what they add:
+ *
+ *  - `client.address` is truncated (IPv4: drop the last octet; IPv6: keep the
+ *    /48, i.e. the first three hextets) so no full client IP is ever emitted.
+ *  - Any key whose name looks secret-bearing (password, token, secret,
+ *    authorization, api_key, …) is replaced with a redaction marker, anywhere
+ *    in `context` or `extra`, at any nesting depth.
+ *
+ * This is a safety net, not a license: code must still avoid putting secrets in
+ * log context in the first place.
+ */
+final class SensitiveDataProcessor implements ProcessorInterface
+{
+    private const REDACTED = '[redacted]';
+    private const ADDRESS_KEY = 'client.address';
+
+    /**
+     * Case-insensitive substrings that mark a key as secret-bearing. Kept narrow
+     * enough not to match legitimate keys such as `tenant.key`.
+     *
+     * @var list<string>
+     */
+    private const SECRET_KEY_FRAGMENTS = [
+        'password', 'passwd', 'secret', 'authorization',
+        'api_key', 'apikey', 'token', 'credential', 'bearer',
+    ];
+
+    public function __invoke(LogRecord $record): LogRecord
+    {
+        $extra = $this->scrub($record->extra);
+        $context = $this->scrub($record->context);
+
+        if (isset($extra[self::ADDRESS_KEY]) && is_string($extra[self::ADDRESS_KEY])) {
+            $extra[self::ADDRESS_KEY] = $this->truncateAddress($extra[self::ADDRESS_KEY]);
+        }
+
+        return $record->with(context: $context, extra: $extra);
+    }
+
+    /**
+     * @param array<array-key, mixed> $data
+     *
+     * @return array<array-key, mixed>
+     */
+    private function scrub(array $data): array
+    {
+        foreach ($data as $key => $value) {
+            if (is_string($key) && $this->isSecretKey($key)) {
+                $data[$key] = self::REDACTED;
+                continue;
+            }
+            if (is_array($value)) {
+                $data[$key] = $this->scrub($value);
+            }
+        }
+
+        return $data;
+    }
+
+    private function isSecretKey(string $key): bool
+    {
+        $key = strtolower($key);
+        foreach (self::SECRET_KEY_FRAGMENTS as $fragment) {
+            if (str_contains($key, $fragment)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    private function truncateAddress(string $address): string
+    {
+        if (false !== filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
+            $octets = explode('.', $address);
+            $octets[3] = '0';
+
+            return implode('.', $octets);
+        }
+
+        if (false !== filter_var($address, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
+            // Keep the /48 (first three hextets), zero the rest.
+            $expanded = $this->expandIpv6($address);
+            $hextets = explode(':', $expanded);
+            for ($i = 3; $i < 8; ++$i) {
+                $hextets[$i] = '0';
+            }
+
+            return implode(':', $hextets);
+        }
+
+        // Not a recognised IP — drop it rather than risk leaking an identifier.
+        return self::REDACTED;
+    }
+
+    private function expandIpv6(string $address): string
+    {
+        $binary = inet_pton($address);
+        if (false === $binary) {
+            return $address;
+        }
+
+        $hextets = unpack('n8', $binary);
+
+        return implode(':', array_map(dechex(...), $hextets ?: []));
+    }
+}