Psr 3 telemetry bridge

.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",

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

@@ -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();
+```