Merge pull request #487 from os2display/feature/structured-logging-semconv

feat(logging): [3–4/4] PHPStan logging gate + DB connection-error logging (re-target of #477/#478)

Author: turegjorup

.env

@@ -146,6 +146,9 @@ LOG_LEVEL_INTERACTIVE=
 LOG_LEVEL_CACHE=
 # Per-channel override (outbound HTTP client); empty or unset inherits LOG_LEVEL.
 LOG_LEVEL_OUTBOUND_HTTP=
+# Per-channel override; empty or unset inherits LOG_LEVEL. Connection errors
+# are logged at error/critical, so they emit regardless of this threshold.
+LOG_LEVEL_DATABASE=
 ###< Logging ###
 
 ###> App ###

CHANGELOG.md

@@ -24,6 +24,14 @@ All notable changes to this project will be documented in this file.
   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`).
+- Enforced the logging conventions in CI with three project-local PHPStan rules
+  (`logging.silentCatch`, `logging.interpolatedLogMessage`, `logging.exceptionContextKey`) and
+  migrated the previously silent catch sites to log the exception, surface it, or be explicitly
+  annotated as intentional.
+- Added a `database` log channel and a DBAL driver middleware that logs MariaDB
+  connection-establishment failures (classified by raw driver error code; connection
+  pressure/unreachability at `critical`, other failures at `error`) so operators without database
+  access get a failure signal. Logging-only — no reconnect/retry.
 
 ## [3.0.0-rc4] - 2026-06-04
 

README.md

@@ -579,6 +579,7 @@ LOG_LEVEL_FEED=
 LOG_LEVEL_INTERACTIVE=
 LOG_LEVEL_CACHE=
 LOG_LEVEL_OUTBOUND_HTTP=
+LOG_LEVEL_DATABASE=
 ###< Logging ###
 ```
 
@@ -593,10 +594,12 @@ LOG_LEVEL_OUTBOUND_HTTP=
 
   **Default**: `info`.
 - 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.)
+  LOG_LEVEL_OUTBOUND_HTTP, LOG_LEVEL_DATABASE: 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.) Note `database` connection errors are logged at
+  `error`/`critical`, so they emit regardless of `LOG_LEVEL_DATABASE` (which only gates lower-severity
+  database-channel records).
 
 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

composer.json

@@ -29,7 +29,6 @@
         "nelmio/cors-bundle": "^2.1",
         "pentatrion/vite-bundle": "^8.1",
         "phpdocumentor/reflection-docblock": "^5.2",
-        "phpstan/phpdoc-parser": "^1.24",
         "rlanvin/php-rrule": "^2.2",
         "symfony/asset": "~6.4.0",
         "symfony/console": "~6.4.0",
@@ -58,6 +57,7 @@
         "friendsofphp/php-cs-fixer": "^3.0",
         "hautelook/alice-bundle": "^2.9",
         "phpstan/extension-installer": "^1.4",
+        "phpstan/phpdoc-parser": "^2.0",
         "phpstan/phpstan": "^2.1",
         "phpstan/phpstan-doctrine": "^2.0",
         "phpstan/phpstan-symfony": "^2.0",

composer.lock

@@ -8,4 +8,5 @@ monolog:
             'feed',
             'interactive',
             'cache',
+            'database',
         ]

config/packages/monolog.yaml

@@ -19,6 +19,7 @@ monolog:
                     '!feed',
                     '!interactive',
                     '!cache',
+                    '!database',
                 ]
             excluded_http_codes: [404, 405]
             buffer_size: 50 # How many messages should be saved? Prevent memory leaks
@@ -78,6 +79,12 @@ monolog:
             level: '%env(default:app.log_level:LOG_LEVEL_CACHE)%'
             channels: ['cache']
             formatter: monolog.formatter.json
+        database:
+            type: stream
+            path: '%env(resolve:LOG_PATH)%'
+            level: '%env(default:app.log_level:LOG_LEVEL_DATABASE)%'
+            channels: ['database']
+            formatter: monolog.formatter.json
         console:
             type: console
             process_psr_3_messages: false

config/packages/prod/monolog.yaml

@@ -102,6 +102,36 @@ services:
         arguments:
             $authLogger: '@monolog.logger.auth'
 
+    # Channel-bound loggers for classes that log failures (ADR 011 / docs/logging.md).
+    App\Controller\Api\AuthOidcController:
+        arguments:
+            $authLogger: '@monolog.logger.auth'
+
+    App\Controller\Api\AuthScreenBindController:
+        arguments:
+            $screenLogger: '@monolog.logger.screen'
+
+    App\Feed\ColiboFeedType:
+        arguments:
+            $feedLogger: '@monolog.logger.feed'
+
+    App\Feed\NotifiedFeedType:
+        arguments:
+            $feedLogger: '@monolog.logger.feed'
+
+    App\Feed\RssFeedType:
+        arguments:
+            $feedLogger: '@monolog.logger.feed'
+
+    # Logs DB connection-establishment failures on the `database` channel.
+    # The explicit doctrine.middleware tag is required: doctrine-bundle collects
+    # tagged services in MiddlewaresPass; implementing the interface is not enough.
+    App\Doctrine\Middleware\ConnectionErrorMiddleware:
+        arguments:
+            $databaseLogger: '@monolog.logger.database'
+        tags:
+            - { name: doctrine.middleware }
+
     Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface: '@Lexik\Bundle\JWTAuthenticationBundle\Security\Http\Authentication\AuthenticationFailureHandler'
     Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface: '@Lexik\Bundle\JWTAuthenticationBundle\Security\Http\Authentication\AuthenticationSuccessHandler'
 
@@ -152,6 +182,7 @@ services:
     App\InteractiveSlide\InstantBook:
         arguments:
             $busyIntervalsSource: '%env(string:INSTANT_BOOK_BUSY_INTERVALS_SOURCE)%'
+            $interactiveLogger: '@monolog.logger.interactive'
 
     App\Service\KeyVaultService:
         arguments:
@@ -197,7 +228,8 @@ services:
 
     App\Service\FeedService:
         arguments:
-            - !tagged_iterator app.feed.feed_type
+            $feedTypes: !tagged_iterator app.feed.feed_type
+            $feedLogger: '@monolog.logger.feed'
 
     App\Service\InteractiveSlideService:
         arguments:
@@ -323,6 +355,7 @@ services:
         tags: [{ name: 'api_platform.state_provider', priority: 2 }]
         arguments:
             $itemExtensions: !tagged_iterator api_platform.doctrine.orm.query_extension.item
+            $feedLogger: '@monolog.logger.feed'
 
     # https://api-platform.com/docs/v2.7/core/state-providers/
     App\State\MediaProvider:

config/services.yaml

@@ -145,3 +145,29 @@ query string of `url.full` wholesale (`https://host/path?[redacted]`) and drops
 (`user:pass@`) before logging, so credentials in an outbound URL never reach the log.
 
 Still: do not put credentials or token strings into log context in the first place.
+
+## Database connection errors
+
+A DBAL driver middleware (`App\Doctrine\Middleware\ConnectionErrorMiddleware`) logs
+connection-**establishment** failures on the `database` channel so operators without
+database access get a failure signal (ADR 011). It reads the raw driver error code (a
+middleware sits below DBAL's exception conversion, which does not classify
+`1040`/`1203`/`2003` as `ConnectionException`), fires for every SAPI (web, CLI, Messenger),
+and rethrows the original exception unchanged — it is logging-only, with no reconnect.
+
+The record uses the static message `Database connection failed` with:
+
+| Key | Meaning |
+|---|---|
+| `event` | Always `db.connection_error`. |
+| `db.response.status_code` | MySQL/MariaDB error number as a string (e.g. `1040`, `1045`, `2003`); OTel db semconv. |
+| `error.type` | Low-cardinality OTel categorisation of the failure (e.g. `too_many_connections`, `access_denied`); falls back to the stringified code when unmapped. The verbose driver message stays in `exception.message`. |
+| `db.sqlstate` | The SQLSTATE, when available. |
+| `server.address` | Connection host only (OTel `server.*`) — never the password or full DSN. |
+| `server.port` | Connection port (OTel `server.*`); emitted only when the connection params carry one. |
+| `exception` | The structured `\Throwable` (via `ExceptionContextProcessor`). |
+
+Connection **pressure / unreachability** codes (`1040`, `1203`, `1226`, `2002`, `2003`,
+`2005`) are logged at `critical`; other connect failures (e.g. a `1045` credential error)
+at `error`. Both levels emit regardless of `LOG_LEVEL_DATABASE`, which only gates
+lower-severity `database`-channel records. Mid-query drops (`2006`/`2013`) are out of scope.

docs/logging.md

@@ -15,3 +15,7 @@ rules:
     # Forbids `$this->addSql(...)` in any file under `migrations/`.
     # Future migrations must use Doctrine's Schema tool API for portability.
     - App\PhpStan\NoAddSqlInMigrationRule
+    # Structured-logging conventions (ADR 011 / docs/logging.md).
+    - App\PhpStan\NoSilentCatchRule
+    - App\PhpStan\NoInterpolatedLogMessageRule
+    - App\PhpStan\ExceptionInContextMustUseExceptionKeyRule