Add SQL commenter as context propagation for databases

src/Instrumentation/PDO/README.md

@@ -33,4 +33,38 @@ otel.instrumentation.pdo.distribute_statement_to_linked_spans = true
 or environment variable:
 ```shell
 OTEL_PHP_INSTRUMENTATION_PDO_DISTRIBUTE_STATEMENT_TO_LINKED_SPANS=true
+```
+
+### SQL Commenter feature
+The [sqlcommenter](https://opentelemetry.io/docs/specs/semconv/database/database-spans/#sql-commenter) feature can be enabled using configuration directive, currently it can be used with `postgresql` and `mysql` drivers only.
+```
+otel.instrumentation.pdo.context_propagation = true
+```
+or environment variable:
+```shell
+OTEL_PHP_INSTRUMENTATION_PDO_CONTEXT_PROPAGATION=true
+```
+
+The context sources from global propagator by default, but it can be configured using the following environment variables:
+```shell
+OTEL_PHP_INSTRUMENTATION_PDO_CONTEXT_PROPAGATORS=tracecontext
+```
+
+The modified query statement by default will not update `DbAttributes::DB_QUERY_TEXT` due to high cardinality risk, but it can be configured using the following configuration directive:
+```
+otel.instrumentation.pdo.context_propagation.attribute = true
+```
+or environment variable:
+```shell
+OTEL_PHP_INSTRUMENTATION_PDO_CONTEXT_PROPAGATION_ATTRIBUTE=true
+```
+
+This feature by default will append a SQL comment to the query statement with the information about the code that executed the query.
+The SQL comment can be configured to prepend to the query statement using the following configuration directive:
+```
+otel.instrumentation.pdo.sql_commenter.prepend = true
+```
+or environment variable:
+```shell
+OTEL_PHP_INSTRUMENTATION_PDO_SQL_COMMENTER_PREPEND=true
 ```

src/Instrumentation/PDO/src/ContextPropagation.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Contrib\Instrumentation\PDO;
+
+use OpenTelemetry\SDK\Common\Configuration\Configuration;
+
+class ContextPropagation
+{
+    public static function isEnabled(): bool
+    {
+        if (class_exists('OpenTelemetry\SDK\Common\Configuration\Configuration') && Configuration::getBoolean('OTEL_PHP_INSTRUMENTATION_PDO_CONTEXT_PROPAGATION', false)) {
+            return true;
+        }
+
+        return filter_var(get_cfg_var('otel.instrumentation.pdo.context_propagation'), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
+    }
+
+    public static function isAttributeEnabled(): bool
+    {
+        if (class_exists('OpenTelemetry\SDK\Common\Configuration\Configuration') && Configuration::getBoolean('OTEL_PHP_INSTRUMENTATION_PDO_CONTEXT_PROPAGATION_ATTRIBUTE', false)) {
+            return true;
+        }
+
+        return filter_var(get_cfg_var('otel.instrumentation.pdo.context_propagation.attribute'), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
+    }
+}

src/Instrumentation/PDO/src/ContextPropagatorFactory.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Contrib\Instrumentation\PDO;
+
+use OpenTelemetry\API\Behavior\LogsMessagesTrait;
+use OpenTelemetry\Context\Propagation\MultiTextMapPropagator;
+use OpenTelemetry\Context\Propagation\NoopTextMapPropagator;
+use OpenTelemetry\Context\Propagation\TextMapPropagatorInterface;
+use OpenTelemetry\SDK\Common\Configuration\Configuration;
+use OpenTelemetry\SDK\Registry;
+
+class ContextPropagatorFactory
+{
+    use LogsMessagesTrait;
+
+    public function create(): TextMapPropagatorInterface | null
+    {
+        $propagators = [];
+        if (class_exists('OpenTelemetry\SDK\Common\Configuration\Configuration')) {
+            $propagators = Configuration::getList('OTEL_PHP_INSTRUMENTATION_PDO_CONTEXT_PROPAGATORS', []);
+        }
+
+        switch (count($propagators)) {
+            case 0:
+                return null;
+            case 1:
+                $propagator = $this->buildPropagator($propagators[0]);
+                if ($propagator !== null && is_a($propagator, NoopTextMapPropagator::class)) {
+                    return null;
+                }
+
+                return $propagator;
+            default:
+                $props = $this->buildPropagators($propagators);
+                if ($props) {
+                    return new MultiTextMapPropagator($props);
+                }
+
+                return null;
+        }
+    }
+
+    /**
+     * @return ?list<TextMapPropagatorInterface>
+     */
+    private function buildPropagators(array $names): ?array
+    {
+        $propagators = [];
+        foreach ($names as $name) {
+            $propagator = $this->buildPropagator($name);
+            if ($propagator !== null && !is_a($propagator, NoopTextMapPropagator::class)) {
+                $propagators[] = $propagator;
+            }
+        }
+        if (count($propagators) === 0) {
+            return null;
+        }
+
+        return $propagators;
+    }
+
+    private function buildPropagator(string $name): ?TextMapPropagatorInterface
+    {
+        try {
+            return Registry::textMapPropagator($name);
+        } catch (\RuntimeException $e) {
+            self::logWarning($e->getMessage());
+        }
+
+        return null;
+    }
+}

src/Instrumentation/PDO/src/PDOInstrumentation.php

@@ -4,6 +4,7 @@
 
 namespace OpenTelemetry\Contrib\Instrumentation\PDO;
 
+use OpenTelemetry\API\Globals;
 use OpenTelemetry\API\Instrumentation\CachedInstrumentation;
 use OpenTelemetry\API\Trace\Span;
 use OpenTelemetry\API\Trace\SpanBuilderInterface;
@@ -22,6 +23,7 @@
 class PDOInstrumentation
 {
     public const NAME = 'pdo';
+    private const UNDEFINED = 'undefined';
 
     public static function register(): void
     {
@@ -31,6 +33,7 @@ public static function register(): void
             Version::VERSION_1_36_0->url(),
         );
         $pdoTracker = new PDOTracker();
+        $contextPropagator = (new ContextPropagatorFactory())->create();
 
         // Hook for the new PDO::connect static method
         if (method_exists(PDO::class, 'connect')) {
@@ -108,12 +111,16 @@ public static function register(): void
         hook(
             PDO::class,
             'query',
-            pre: static function (PDO $pdo, array $params, string $class, string $function, ?string $filename, ?int $lineno) use ($pdoTracker, $instrumentation) {
+            pre: static function (PDO $pdo, array $params, string $class, string $function, ?string $filename, ?int $lineno) use ($contextPropagator, $pdoTracker, $instrumentation) {
                 /** @psalm-suppress ArgumentTypeCoercion */
                 $builder = self::makeBuilder($instrumentation, 'PDO::query', $function, $class, $filename, $lineno)
                     ->setSpanKind(SpanKind::KIND_CLIENT);
+                $sqlStatement = mb_convert_encoding($params[0] ?? self::UNDEFINED, 'UTF-8');
+                if (!is_string($sqlStatement)) {
+                    $sqlStatement = self::UNDEFINED;
+                }
                 if ($class === PDO::class) {
-                    $builder->setAttribute(DbAttributes::DB_QUERY_TEXT, mb_convert_encoding($params[0] ?? 'undefined', 'UTF-8'));
+                    $builder->setAttribute(DbAttributes::DB_QUERY_TEXT, $sqlStatement);
                 }
                 $parent = Context::getCurrent();
                 $span = $builder->startSpan();
@@ -122,6 +129,39 @@ public static function register(): void
                 $span->setAttributes($attributes);
 
                 Context::storage()->attach($span->storeInContext($parent));
+                if (ContextPropagation::isEnabled() && $sqlStatement !== self::UNDEFINED) {
+                    if (array_key_exists(DbAttributes::DB_SYSTEM_NAME, $attributes)) {
+                        /** @psalm-suppress PossiblyInvalidCast */
+                        switch ((string) $attributes[DbAttributes::DB_SYSTEM_NAME]) {
+                            case 'postgresql':
+                            case 'mysql':
+                                $comments = [];
+                                if ($contextPropagator !== null) {
+                                    // Propagator passed by user
+                                    $contextPropagator->inject($comments);
+                                } else {
+                                    // fallback to global propagator if user didn't pass one
+                                    Globals::propagator()->inject($comments);
+                                }
+                                // Inject comments into SQL statement
+                                $sqlStatement = SqlCommentInjector::inject($sqlStatement, $comments);
+                                if (ContextPropagation::isAttributeEnabled()) {
+                                    $span->setAttributes([
+                                        DbAttributes::DB_QUERY_TEXT => $sqlStatement,
+                                    ]);
+                                }
+
+                                return [
+                                    0 => $sqlStatement,
+                                ];
+                            default:
+                                // Do nothing, not a database we want to propagate
+                                break;
+                        }
+                    }
+                }
+
+                return [];
             },
             post: static function (PDO $pdo, array $params, mixed $statement, ?Throwable $exception) {
                 self::end($exception);
@@ -131,12 +171,16 @@ public static function register(): void
         hook(
             PDO::class,
             'exec',
-            pre: static function (PDO $pdo, array $params, string $class, string $function, ?string $filename, ?int $lineno) use ($pdoTracker, $instrumentation) {
+            pre: static function (PDO $pdo, array $params, string $class, string $function, ?string $filename, ?int $lineno) use ($contextPropagator, $pdoTracker, $instrumentation) {
                 /** @psalm-suppress ArgumentTypeCoercion */
                 $builder = self::makeBuilder($instrumentation, 'PDO::exec', $function, $class, $filename, $lineno)
                     ->setSpanKind(SpanKind::KIND_CLIENT);
+                $sqlStatement = mb_convert_encoding($params[0] ?? self::UNDEFINED, 'UTF-8');
+                if (!is_string($sqlStatement)) {
+                    $sqlStatement = self::UNDEFINED;
+                }
                 if ($class === PDO::class) {
-                    $builder->setAttribute(DbAttributes::DB_QUERY_TEXT, mb_convert_encoding($params[0] ?? 'undefined', 'UTF-8'));
+                    $builder->setAttribute(DbAttributes::DB_QUERY_TEXT, $sqlStatement);
                 }
                 $parent = Context::getCurrent();
                 $span = $builder->startSpan();
@@ -145,6 +189,39 @@ public static function register(): void
                 $span->setAttributes($attributes);
 
                 Context::storage()->attach($span->storeInContext($parent));
+                if (ContextPropagation::isEnabled() && $sqlStatement !== self::UNDEFINED) {
+                    if (array_key_exists(DbAttributes::DB_SYSTEM_NAME, $attributes)) {
+                        /** @psalm-suppress PossiblyInvalidCast */
+                        switch ((string) $attributes[DbAttributes::DB_SYSTEM_NAME]) {
+                            case 'postgresql':
+                            case 'mysql':
+                                $comments = [];
+                                if ($contextPropagator !== null) {
+                                    // Propagator passed by user
+                                    $contextPropagator->inject($comments);
+                                } else {
+                                    // fallback to global propagator if user didn't pass one
+                                    Globals::propagator()->inject($comments);
+                                }
+                                // Inject comments into SQL statement
+                                $sqlStatement = SqlCommentInjector::inject($sqlStatement, $comments);
+                                if (ContextPropagation::isAttributeEnabled()) {
+                                    $span->setAttributes([
+                                        DbAttributes::DB_QUERY_TEXT => $sqlStatement,
+                                    ]);
+                                }
+
+                                return [
+                                    0 => $sqlStatement,
+                                ];
+                            default:
+                                // Do nothing, not a database we want to propagate
+                                break;
+                        }
+                    }
+                }
+
+                return [];
             },
             post: static function (PDO $pdo, array $params, mixed $statement, ?Throwable $exception) {
                 self::end($exception);

src/Instrumentation/PDO/src/PDOTracker.php

@@ -5,7 +5,8 @@
 namespace OpenTelemetry\Contrib\Instrumentation\PDO;
 
 use OpenTelemetry\API\Trace\SpanContextInterface;
-use OpenTelemetry\SemConv\TraceAttributes;
+use OpenTelemetry\SemConv\Attributes\DbAttributes;
+use OpenTelemetry\SemConv\Attributes\ServerAttributes;
 use PDO;
 use PDOStatement;
 use WeakMap;
@@ -74,11 +75,11 @@ public function trackPdoAttributes(PDO $pdo, string $dsn): array
             /** @var string $dbSystem */
             $dbSystem = $pdo->getAttribute(PDO::ATTR_DRIVER_NAME);
             /** @psalm-suppress InvalidArrayAssignment */
-            $attributes[TraceAttributes::DB_SYSTEM_NAME] = self::mapDriverNameToAttribute($dbSystem);
+            $attributes[DbAttributes::DB_SYSTEM_NAME] = self::mapDriverNameToAttribute($dbSystem);
         } catch (\Error) {
             // if we caught an exception, the driver is likely not supporting the operation, default to "other"
             /** @psalm-suppress PossiblyInvalidArrayAssignment */
-            $attributes[TraceAttributes::DB_SYSTEM_NAME] = 'other_sql';
+            $attributes[DbAttributes::DB_SYSTEM_NAME] = 'other_sql';
         }
 
         $this->pdoToAttributesMap[$pdo] = $attributes;
@@ -135,18 +136,18 @@ private static function extractAttributesFromDSN(string $dsn): array
     {
         $attributes = [];
         if (str_starts_with($dsn, 'sqlite::memory:')) {
-            $attributes[TraceAttributes::DB_SYSTEM_NAME] = 'sqlite';
-            $attributes[TraceAttributes::DB_NAMESPACE] = 'memory';
+            $attributes[DbAttributes::DB_SYSTEM_NAME] = 'sqlite';
+            $attributes[DbAttributes::DB_NAMESPACE] = 'memory';
 
             return $attributes;
         } elseif (str_starts_with($dsn, 'sqlite:')) {
-            $attributes[TraceAttributes::DB_SYSTEM_NAME] = 'sqlite';
-            $attributes[TraceAttributes::DB_NAMESPACE] = substr($dsn, 7);
+            $attributes[DbAttributes::DB_SYSTEM_NAME] = 'sqlite';
+            $attributes[DbAttributes::DB_NAMESPACE] = substr($dsn, 7);
 
             return $attributes;
         } elseif (str_starts_with($dsn, 'sqlite')) {
-            $attributes[TraceAttributes::DB_SYSTEM_NAME] = 'sqlite';
-            $attributes[TraceAttributes::DB_NAMESPACE] = $dsn;
+            $attributes[DbAttributes::DB_SYSTEM_NAME] = 'sqlite';
+            $attributes[DbAttributes::DB_NAMESPACE] = $dsn;
 
             return $attributes;
         }
@@ -156,18 +157,18 @@ private static function extractAttributesFromDSN(string $dsn): array
             if (preg_match('/Server=([^,;]+)(?:,([0-9]+))?/', $dsn, $serverMatches)) {
                 $server = $serverMatches[1];
                 if ($server !== '') {
-                    $attributes[TraceAttributes::SERVER_ADDRESS] = $server;
+                    $attributes[ServerAttributes::SERVER_ADDRESS] = $server;
                 }
 
                 if (isset($serverMatches[2]) && $serverMatches[2] !== '') {
-                    $attributes[TraceAttributes::SERVER_PORT] = (int) $serverMatches[2];
+                    $attributes[ServerAttributes::SERVER_PORT] = (int) $serverMatches[2];
                 }
             }
 
             if (preg_match('/Database=([^;]*)/', $dsn, $dbMatches)) {
                 $dbname = $dbMatches[1];
                 if ($dbname !== '') {
-                    $attributes[TraceAttributes::DB_NAMESPACE] = $dbname;
+                    $attributes[DbAttributes::DB_NAMESPACE] = $dbname;
                 }
             }
 
@@ -186,33 +187,33 @@ private static function extractAttributesFromDSN(string $dsn): array
         if (preg_match('/host=([^;]*)/', $dsn, $matches)) {
             $host = $matches[1];
             if ($host !== '') {
-                $attributes[TraceAttributes::SERVER_ADDRESS] = $host;
+                $attributes[ServerAttributes::SERVER_ADDRESS] = $host;
             }
         } elseif (preg_match('/mysql:([^;:]+)/', $dsn, $hostMatches)) {
             $host = $hostMatches[1];
             if ($host !== '' && $host !== 'dbname') {
-                $attributes[TraceAttributes::SERVER_ADDRESS] = $host;
+                $attributes[ServerAttributes::SERVER_ADDRESS] = $host;
             }
         }
 
         // Extract port information
         if (preg_match('/port=([0-9]+)/', $dsn, $portMatches)) {
             $port = (int) $portMatches[1];
-            $attributes[TraceAttributes::SERVER_PORT] = $port;
+            $attributes[ServerAttributes::SERVER_PORT] = $port;
         } elseif (preg_match('/[.0-9]+:([0-9]+)/', $dsn, $portMatches)) {
             // This pattern matches IP:PORT format like 127.0.0.1:3308
             $port = (int) $portMatches[1];
-            $attributes[TraceAttributes::SERVER_PORT] = $port;
+            $attributes[ServerAttributes::SERVER_PORT] = $port;
         } elseif (preg_match('/:([0-9]+)/', $dsn, $portMatches)) {
             $port = (int) $portMatches[1];
-            $attributes[TraceAttributes::SERVER_PORT] = $port;
+            $attributes[ServerAttributes::SERVER_PORT] = $port;
         }
 
         // Extract database name
         if (preg_match('/dbname=([^;]*)/', $dsn, $matches)) {
             $dbname = $matches[1];
             if ($dbname !== '') {
-                $attributes[TraceAttributes::DB_NAMESPACE] = $dbname;
+                $attributes[DbAttributes::DB_NAMESPACE] = $dbname;
             }
         }