Merge pull request #2346 from flow-php/psr-3-telemetry-bridge

Psr 3 telemetry bridge

Author: norberttech

.codecov.yaml

@@ -99,6 +99,10 @@ component_management:
       name: bridge-psr18-telemetry
       paths:
         - src/bridge/psr18/telemetry/**
+    - component_id: bridge-psr3-telemetry
+      name: bridge-psr3-telemetry
+      paths:
+        - src/bridge/psr3/telemetry/**
     - component_id: bridge-psr7-telemetry
       name: bridge-psr7-telemetry
       paths:

.github/workflows/monorepo-split.yml

@@ -88,6 +88,8 @@ jobs:
             split_repository: 'openapi-specification-bridge'
           - local_path: 'src/bridge/postgresql/valinor'
             split_repository: 'postgresql-valinor-bridge'
+          - local_path: 'src/bridge/psr3/telemetry'
+            split_repository: 'psr3-telemetry-bridge'
           - local_path: 'src/bridge/psr7/telemetry'
             split_repository: 'psr7-telemetry-bridge'
           - local_path: 'src/bridge/psr18/telemetry'

composer.json

@@ -106,6 +106,7 @@
         "flow-php/parquet-viewer": "self.version",
         "flow-php/postgresql": "self.version",
         "flow-php/postgresql-valinor-bridge": "self.version",
+        "flow-php/psr3-telemetry-bridge": "self.version",
         "flow-php/psr7-telemetry-bridge": "self.version",
         "flow-php/psr18-telemetry-bridge": "self.version",
         "flow-php/snappy": "self.version",
@@ -150,6 +151,7 @@
                 "src/bridge/monolog/telemetry/src/Flow",
                 "src/bridge/openapi/specification/src/Flow",
                 "src/bridge/postgresql/valinor/src/Flow",
+                "src/bridge/psr3/telemetry/src/Flow",
                 "src/bridge/psr7/telemetry/src/Flow",
                 "src/bridge/psr18/telemetry/src/Flow",
                 "src/bridge/symfony/filesystem-bundle/src/Flow",
@@ -208,6 +210,7 @@
             "src/bridge/phpunit/postgresql/src/Flow/Bridge/PHPUnit/PostgreSQL/DSL/functions.php",
             "src/bridge/openapi/specification/src/Flow/Bridge/OpenAPI/Specification/DSL/functions.php",
             "src/bridge/postgresql/valinor/src/Flow/PostgreSql/Bridge/Valinor/DSL/functions.php",
+            "src/bridge/psr3/telemetry/src/Flow/Bridge/Psr3/Telemetry/DSL/functions.php",
             "src/bridge/psr7/telemetry/src/Flow/Bridge/Psr7/Telemetry/DSL/functions.php",
             "src/bridge/psr18/telemetry/src/Flow/Bridge/Psr18/Telemetry/DSL/functions.php",
             "src/bridge/symfony/http-foundation-telemetry/src/Flow/Bridge/Symfony/HttpFoundationTelemetry/DSL/functions.php",
@@ -259,6 +262,7 @@
                 "src/bridge/monolog/telemetry/tests/Flow",
                 "src/bridge/openapi/specification/tests/Flow",
                 "src/bridge/postgresql/valinor/tests/Flow",
+                "src/bridge/psr3/telemetry/tests/Flow",
                 "src/bridge/psr7/telemetry/tests/Flow",
                 "src/bridge/psr18/telemetry/tests/Flow",
                 "src/bridge/symfony/filesystem-bundle/tests/Flow",
@@ -375,6 +379,8 @@
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.parquet.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.parquet-viewer.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.postgresql.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.postgresql-migrations.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.rdsl.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.snappy.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.telemetry.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/lib.types.xml",
@@ -394,9 +400,22 @@
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.filesystem.async-aws.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.filesystem.azure.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.monolog.http.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.monolog-telemetry.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.openapi.specification.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.phpunit.postgresql.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.phpunit.telemetry.xml",
             "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.postgresql.valinor.xml",
-            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.http-foundation.xml"
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.psr3.telemetry.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.psr7.telemetry.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.psr18.telemetry.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.filesystem.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.filesystem-cache.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.http-foundation.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.postgresql-cache.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.postgresql-messenger.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.postgresql-migrations.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.postgresql-session.xml",
+            "./tools/phpdocumentor/vendor/bin/phpdoc --config=./phpdoc/bridge.symfony.telemetry.xml"
         ],
         "build:parquet:thrift": [
             "grep -q 'namespace php Flow.Parquet.ThriftModel' src/lib/parquet/src/Flow/Parquet/Resources/Thrift/parquet.thrift || { echo \"Flow php namespace not found in thrift definition!\"; exit 1; }\n",

composer.lock

@@ -0,0 +1,194 @@
+# PSR-3 Telemetry Bridge
+
+Flow PSR-3 Telemetry Bridge exposes a [PSR-3](https://www.php-fig.org/psr/psr-3/) `LoggerInterface` implementation
+backed by Flow PHP Telemetry. Any framework or library that depends on `Psr\Log\LoggerInterface` can write through this
+adapter and have its records emitted as Telemetry log signals.
+
+- [⬅️️ Back](/documentation/introduction.md)
+- [📦Packagist](https://packagist.org/packages/flow-php/psr3-telemetry-bridge)
+- [➡️ Installation](/documentation/installation/packages/psr3-telemetry-bridge.md)
+- [🐙GitHub](https://github.com/flow-php/psr3-telemetry-bridge)
+- [📚API Reference](/documentation/api/bridge/psr3/telemetry)
+- [🗺DSL](/documentation/api/bridge/psr3/telemetry/namespaces/flow-bridge-psr3-telemetry-dsl.html)
+
+[TOC]
+
+## Installation
+
+For detailed installation instructions, see the [installation page](/documentation/installation/packages/psr3-telemetry-bridge.md).
+
+## Overview
+
+This bridge wraps `Flow\Telemetry\Logger\Logger` behind a PSR-3 `LoggerInterface`. It:
+
+- Maps PSR-3 log levels to Telemetry severities (8 → 6, customizable).
+- Performs PSR-3 `{placeholder}` interpolation against the context array (scalars and `Stringable` only).
+- Stores every context entry as a log record attribute under its raw key.
+- Routes a `Throwable` under the `exception` key through `LogRecord::setException()`, populating
+  `exception.type`, `exception.message`, and `exception.stacktrace`.
+- Throws `Psr\Log\InvalidArgumentException` when `log()` is called with an unknown level, per spec.
+
+## Basic Usage
+
+```php
+<?php
+
+use function Flow\Bridge\Psr3\Telemetry\DSL\psr3_telemetry_logger;
+use function Flow\Telemetry\DSL\telemetry;
+
+$telemetry = telemetry($resource);
+$psrLogger = psr3_telemetry_logger($telemetry->logger('my-service'));
+
+$psrLogger->info('User {user_id} logged in', ['user_id' => 123]);
+// → body:       'User 123 logged in'
+// → severity:   INFO
+// → attributes: {user_id: 123}
+```
+
+The returned `TelemetryLogger` is a drop-in `Psr\Log\LoggerInterface`, so it can be passed to anything that accepts a
+PSR-3 logger (Symfony, Laravel, third-party libraries).
+
+## Severity Mapping
+
+The default mapping collapses PSR-3's eight levels onto Telemetry's six OTEL-aligned severities:
+
+| PSR-3 Level | Telemetry Severity |
+|-------------|--------------------|
+| `debug`     | `DEBUG`            |
+| `info`      | `INFO`             |
+| `notice`    | `INFO`             |
+| `warning`   | `WARN`             |
+| `error`     | `ERROR`            |
+| `critical`  | `FATAL`            |
+| `alert`     | `FATAL`            |
+| `emergency` | `FATAL`            |
+
+Override the mapping by passing a custom `psr3_severity_mapper()` to `psr3_log_record_converter()`:
+
+```php
+<?php
+
+use Flow\Telemetry\Logger\Severity;
+use Psr\Log\LogLevel;
+use function Flow\Bridge\Psr3\Telemetry\DSL\{psr3_log_record_converter, psr3_severity_mapper, psr3_telemetry_logger};
+
+$converter = psr3_log_record_converter(
+    severityMapper: psr3_severity_mapper([
+        LogLevel::DEBUG     => Severity::TRACE,
+        LogLevel::INFO      => Severity::INFO,
+        LogLevel::NOTICE    => Severity::WARN,
+        LogLevel::WARNING   => Severity::WARN,
+        LogLevel::ERROR     => Severity::ERROR,
+        LogLevel::CRITICAL  => Severity::FATAL,
+        LogLevel::ALERT     => Severity::FATAL,
+        LogLevel::EMERGENCY => Severity::FATAL,
+    ]),
+);
+
+$psrLogger = psr3_telemetry_logger($telemetry->logger('my-service'), $converter);
+```
+
+## Context Handling
+
+### Attributes
+
+Every context entry becomes an attribute on the emitted `LogRecord`, keyed verbatim:
+
+```php
+$psrLogger->info('Request processed', [
+    'http.method' => 'GET',
+    'http.status' => 200,
+    'duration_ms' => 12.4,
+]);
+// attributes: {http.method: 'GET', http.status: 200, duration_ms: 12.4}
+```
+
+Non-scalar values are normalized via `ValueNormalizer`:
+
+- `null` → `'null'`
+- `DateTimeInterface`, `Throwable` → passed through
+- arrays → recursively normalized
+- objects with `__toString()` → string cast
+- objects without `__toString()` → class name
+- other types → `get_debug_type()` result
+
+### Exceptions
+
+A `Throwable` under the `exception` key is unpacked into the standard OTEL exception attributes via
+`LogRecord::setException()`:
+
+```php
+try {
+    // ...
+} catch (\Throwable $e) {
+    $psrLogger->error('Operation failed', ['exception' => $e]);
+}
+// attributes:
+//   exception.type:       'RuntimeException'
+//   exception.message:    '...'
+//   exception.stacktrace: '...'
+```
+
+The original `exception` key is **not** stored as a separate attribute. A non-`Throwable` value under `exception` is
+treated as a regular attribute.
+
+### Message Interpolation
+
+Per PSR-3 §1.2, `{placeholder}` tokens in the message body are substituted with matching context entries. Only scalars
+and `Stringable` objects participate; arrays, `Throwable` instances, and plain objects are left in the template. The
+context entries remain available as attributes regardless.
+
+```php
+$psrLogger->warning('Quota exceeded for {tenant} ({used}/{limit})', [
+    'tenant' => 'acme',
+    'used'   => 105,
+    'limit'  => 100,
+]);
+// body:       'Quota exceeded for acme (105/100)'
+// attributes: {tenant: 'acme', used: 105, limit: 100}
+```
+
+## DSL Functions
+
+### psr3_telemetry_logger()
+
+Wraps a Flow Telemetry `Logger` in a PSR-3 `LoggerInterface`.
+
+```php
+$psrLogger = psr3_telemetry_logger(
+    logger: $telemetry->logger('my-service'),
+    converter: $converter, // optional, defaults to LogRecordConverter()
+);
+```
+
+### psr3_log_record_converter()
+
+Builds the converter that turns each PSR-3 call into a `LogRecord`. Use it to plug in a custom severity mapper or value
+normalizer.
+
+```php
+$converter = psr3_log_record_converter(
+    severityMapper: psr3_severity_mapper([...]),
+    valueNormalizer: psr3_value_normalizer(),
+);
+```
+
+### psr3_severity_mapper()
+
+Builds a `SeverityMapper`. Pass `null` (default) to use the standard PSR-3 → OTEL mapping, or a full PSR-3 → Severity
+array to override.
+
+```php
+$mapper = psr3_severity_mapper([
+    LogLevel::DEBUG => Severity::TRACE,
+    // ... rest of PSR-3 levels
+]);
+```
+
+### psr3_value_normalizer()
+
+Builds the default `ValueNormalizer`. Provided for symmetry with the other DSL helpers; most users won't need it.
+
+```php
+$normalizer = psr3_value_normalizer();
+```

documentation/components/bridges/psr3-telemetry-bridge.md

@@ -42,7 +42,7 @@ flow_telemetry:
       static:
         cache:
           enabled: true  # Cache static attributes (default: true)
-          path: null     # Cache path (default: kernel cache dir)
+          path: null     # Cache file path (default: sys_get_temp_dir()/flow_telemetry_resource.cache)
         os:
           enabled: true  # Detect os.type, os.name, os.version, os.description
         host:
@@ -75,6 +75,12 @@ flow_telemetry:
 
 Static detectors are cached by default. Dynamic detectors run on every request/command.
 
+The cache file lives outside Symfony's cache lifecycle on purpose: building the Symfony cache
+(via `cache:warmup`) at image build time would otherwise freeze runtime-dependent attributes
+such as `host.name` or `process.pid` from the build container. Defaulting to
+`sys_get_temp_dir()` keeps the cache per-runtime and avoids that pitfall. To invalidate it,
+delete the cache file or restart the process; `cache:clear` does not touch it.
+
 Custom attributes override auto-detected values.
 
 ### Clock Configuration
@@ -660,6 +666,33 @@ flow_telemetry:
       version: '1.0.0'  # default: 'unknown'
 ```
 
+### Main Logger
+
+The bundle depends on [PSR-3 Telemetry Bridge](/documentation/components/bridges/psr3-telemetry-bridge.md) and registers a PSR-3 wrapper service for every named Telemetry logger at `flow.telemetry.<name>.logger.psr3`. This makes Flow Telemetry loggers usable as Symfony's `logger` service, removing the need for Monolog when telemetry is the only logging destination.
+
+In addition, the bundle always registers a `default` logger, meter, and tracer — `flow.telemetry.default.logger`, `flow.telemetry.default.logger.psr3`, `flow.telemetry.default.meter`, `flow.telemetry.default.tracer` — regardless of what is configured under `loggers`/`meters`/`tracers`. Defining your own `default` entry under those keys is allowed and will override the auto-default.
+
+**Options:**
+
+| Option             | Type             | Default | Description                                                                                                  |
+|--------------------|------------------|---------|--------------------------------------------------------------------------------------------------------------|
+| `framework_logger` | `string \| null` | `null`  | Name of a logger configured under `loggers` (or the always-available `default`) to alias as Symfony `logger` |
+
+**Behavior:**
+
+- When `framework_logger` is set, the bundle aliases the Symfony `logger` service to `flow.telemetry.<framework_logger>.logger.psr3`. If no logger with that name exists, container compilation fails with a clear error.
+- When `framework_logger` is `null` and Symfony's `logger` service is the default `Symfony\Component\HttpKernel\Log\Logger`, the bundle automatically aliases `logger` to `flow.telemetry.default.logger.psr3`.
+- When `framework_logger` is `null` and `logger` is provided by another bundle (Monolog, custom alias, etc.), the bundle leaves `logger` alone.
+
+```yaml
+flow_telemetry:
+  loggers:
+    app:
+      version: '1.0.0'
+
+  framework_logger: app   # Symfony "logger" service -> flow.telemetry.app.logger.psr3
+```
+
 ## Pattern Matching
 
 Several configuration options support pattern matching for exclusion lists (paths, commands, templates, etc.).
@@ -840,6 +873,22 @@ flow_telemetry:
             transport:
               endpoint: '%env(OTEL_EXPORTER_OTLP_LOGS_ENDPOINT)%'
 
+  loggers:
+    app:
+      version: '%env(APP_VERSION)%'
+    audit:
+      version: '%env(APP_VERSION)%'
+      attributes:
+        channel: audit
+  meters:
+    business:
+      version: '%env(APP_VERSION)%'
+  tracers:
+    checkout:
+      version: '%env(APP_VERSION)%'
+
+  framework_logger: app   # Symfony "logger" service -> flow.telemetry.app.logger.psr3
+
   instrumentation:
     http_kernel:
       enabled: true

documentation/components/bridges/symfony-telemetry-bundle.md

@@ -0,0 +1,24 @@
+---
+seo_title: "Installing PSR-3 Telemetry Bridge"
+seo_description: >
+  How to install flow-php/psr3-telemetry-bridge in your PHP project using Composer.
+---
+
+# PSR-3 Telemetry Bridge
+
+- [⬅️️ Back](/documentation/installation.md)
+- [📜 Documentation](/documentation/components/bridges/psr3-telemetry-bridge.md)
+- [📦 Packagist](https://packagist.org/packages/flow-php/psr3-telemetry-bridge)
+
+[TOC]
+
+## Composer
+
+```bash
+composer require flow-php/psr3-telemetry-bridge:~--FLOW_PHP_VERSION--
+```
+
+## Core Dependencies
+
+- [psr/log](https://packagist.org/packages/psr/log)
+- [flow-php/telemetry](https://packagist.org/packages/flow-php/telemetry)