feat: sqlcommenter for PDO, MySqli, PostgreSql (pdo_mysql, pdo_pgsql) (#442)

* Initial

* Added SqlCommenter and its tests

* Added context propagator and updated PDO

* Fixed the dependencies

* Changed for MySqli

* Changed for PostgreSql

* nits

* Updated README.md

* Simplify PostgreSqlInstrumentation

* Considered the attributes in PostgreSql

* Updated

* Updated

* Typo

* Updated README.md(s)

* Added comments

* Remove the query command re-extraction

* Moved Context Propagator into SqlCommenter to make it per component

* Renamed env variable OTEL_PHP_SQLCOMMENTER_CONTEXT_PROPAGATORS

* Renamed other environment variables

* Moved logic to SqlCommenter

* nits

Author: jerrytfleung

.github/dependabot.yml

@@ -101,6 +101,7 @@ updates:
       - "/src/ResourceDetectors/DigitalOcean"
       - "/src/Sampler/RuleBased"
       - "/src/Shims/OpenTracing"
+      - "/src/SqlCommenter"
       - "/src/Symfony"
       - "/src/Symfony/src/OtelBundle"
       - "/src/Symfony/src/OtelSdkBundle"

.github/workflows/php.yml

@@ -65,6 +65,7 @@ jobs:
           'Sampler/RuleBased',
           'Sampler/Xray',
           'Shims/OpenTracing',
+          'SqlCommenter',
           'Symfony',
           'Utils/Test'
         ]

.gitsplit.yml

@@ -94,6 +94,8 @@ splits:
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-sampler-aws-xray.git"
   - prefix: "src/Shims/OpenTracing"
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-shim-opentracing.git"
+  - prefix: "src/SqlCommenter"
+    target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-sqlcommenter.git"
   - prefix: "src/Symfony"
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-sdk-bundle.git"
   - prefix: "src/Utils/Test"

composer.json

@@ -55,6 +55,7 @@
       "OpenTelemetry\\Contrib\\Resource\\Detector\\DigitalOcean\\": "src/ResourceDetectors/DigitalOcean/src",
       "OpenTelemetry\\Contrib\\Sampler\\RuleBased\\": "src/Sampler/RuleBased/src",
       "OpenTelemetry\\Contrib\\Shim\\OpenTracing\\": "src/Shims/OpenTracing/src",
+      "OpenTelemetry\\Contrib\\SqlCommenter\\": "src/SqlCommenter/src",
       "OpenTelemetry\\Contrib\\Symfony\\": "src/Symfony/src",
       "OpenTelemetry\\TestUtils\\": "src/Utils/Test/src"
     },
@@ -125,6 +126,7 @@
       "OpenTelemetry\\Tests\\Propagation\\CloudTrace\\": "src/Propagation/CloudTrace/tests",
       "OpenTelemetry\\Tests\\Resource\\Detector\\Azure\\": "src/ResourceDetectors/Azure/tests",
       "OpenTelemetry\\Contrib\\Resource\\Detector\\DigitalOcean\\": "src/ResourceDetectors/DigitalOcean/tests",
+      "OpenTelemetry\\Tests\\Contrib\\SqlCommenter\\": "src/SqlCommenter/tests",
       "OpenTelemetry\\Tests\\Contrib\\Symfony\\": "src/Symfony/tests",
       "OpenTelemetry\\TestUtils\\Tests\\": "src/Utils/Test/tests"
     }
@@ -171,6 +173,7 @@
     "open-telemetry/opentelemetry-propagation-instana": "self.version",
     "open-telemetry/opentelemetry-propagation-server-timing": "self.version",
     "open-telemetry/opentelemetry-propagation-traceresponse": "self.version",
+    "open-telemetry/opentelemetry-sqlcommenter": "self.version",
     "open-telemetry/opentracing-shim": "self.version",
     "open-telemetry/sampler-rule-based": "self.version",
     "open-telemetry/symfony-sdk-bundle": "self.version",

src/Instrumentation/MySqli/README.md

@@ -54,3 +54,9 @@ The extension can be disabled via [runtime configuration](https://opentelemetry.
 OTEL_PHP_DISABLED_INSTRUMENTATIONS=mysqli
 ```
 
+## Database Context Propagation
+
+Enable context propagation for database queries by installing the following packages:
+```shell
+composer require open-telemetry/opentelemetry-sqlcommenter
+```

src/Instrumentation/MySqli/src/MySqliInstrumentation.php

@@ -20,12 +20,14 @@
 
 /**
  * @phan-file-suppress PhanParamTooFewUnpack
+ * @phan-file-suppress PhanUndeclaredClassMethod
  */
 class MySqliInstrumentation
 {
     use LogsMessagesTrait;
 
     public const NAME = 'mysqli';
+    private const UNDEFINED = 'undefined';
 
     private const MYSQLI_CONNECT_ARG_OFFSET = 0;
     private const MYSQLI_REAL_CONNECT_ARG_OFFSET = 1; // The mysqli_real_connect function in procedural mode requires a mysqli object as its first argument. The remaining arguments are consistent with those used in other connection methods, such as connect or __construct
@@ -98,7 +100,7 @@ public static function register(): void
             null,
             'mysqli_query',
             pre: static function (...$args) use ($instrumentation, $tracker) {
-                self::queryPreHook('mysqli_query', $instrumentation, $tracker, ...$args);
+                return self::queryPreHook('mysqli_query', $instrumentation, $tracker, ...$args);
             },
             post: static function (...$args) use ($instrumentation, $tracker) {
                 self::queryPostHook($instrumentation, $tracker, ...$args);
@@ -108,7 +110,7 @@ public static function register(): void
             mysqli::class,
             'query',
             pre: static function (...$args) use ($instrumentation, $tracker) {
-                self::queryPreHook('mysqli::query', $instrumentation, $tracker, ...$args);
+                return self::queryPreHook('mysqli::query', $instrumentation, $tracker, ...$args);
             },
             post: static function (...$args) use ($instrumentation, $tracker) {
                 self::queryPostHook($instrumentation, $tracker, ...$args);
@@ -119,7 +121,7 @@ public static function register(): void
             null,
             'mysqli_real_query',
             pre: static function (...$args) use ($instrumentation, $tracker) {
-                self::queryPreHook('mysqli_real_query', $instrumentation, $tracker, ...$args);
+                return self::queryPreHook('mysqli_real_query', $instrumentation, $tracker, ...$args);
             },
             post: static function (...$args) use ($instrumentation, $tracker) {
                 self::queryPostHook($instrumentation, $tracker, ...$args);
@@ -129,7 +131,7 @@ public static function register(): void
             mysqli::class,
             'real_query',
             pre: static function (...$args) use ($instrumentation, $tracker) {
-                self::queryPreHook('mysqli::real_query', $instrumentation, $tracker, ...$args);
+                return self::queryPreHook('mysqli::real_query', $instrumentation, $tracker, ...$args);
             },
             post: static function (...$args) use ($instrumentation, $tracker) {
                 self::queryPostHook($instrumentation, $tracker, ...$args);
@@ -161,7 +163,7 @@ public static function register(): void
             null,
             'mysqli_multi_query',
             pre: static function (...$args) use ($instrumentation, $tracker) {
-                self::queryPreHook('mysqli_multi_query', $instrumentation, $tracker, ...$args);
+                self::multiQueryPreHook('mysqli_multi_query', $instrumentation, $tracker, ...$args);
             },
             post: static function (...$args) use ($instrumentation, $tracker) {
                 self::multiQueryPostHook($instrumentation, $tracker, ...$args);
@@ -171,7 +173,7 @@ public static function register(): void
             mysqli::class,
             'multi_query',
             pre: static function (...$args) use ($instrumentation, $tracker) {
-                self::queryPreHook('mysqli::multi_query', $instrumentation, $tracker, ...$args);
+                self::multiQueryPreHook('mysqli::multi_query', $instrumentation, $tracker, ...$args);
             },
             post: static function (...$args) use ($instrumentation, $tracker) {
                 self::multiQueryPostHook($instrumentation, $tracker, ...$args);
@@ -440,11 +442,46 @@ private static function constructPostHook(int $paramsOffset, CachedInstrumentati
     }
 
     /** @param non-empty-string $spanName */
-    private static function queryPreHook(string $spanName, CachedInstrumentation $instrumentation, MySqliTracker $tracker, $obj, array $params, ?string $class, string $function, ?string $filename, ?int $lineno): void
+    private static function queryPreHook(string $spanName, CachedInstrumentation $instrumentation, MySqliTracker $tracker, $obj, array $params, ?string $class, string $function, ?string $filename, ?int $lineno): array
     {
         $span = self::startSpan($spanName, $instrumentation, $class, $function, $filename, $lineno, []);
         $mysqli = $obj ? $obj : $params[0];
+        $query = $obj ? $params[0] : $params[1];
+        $query = mb_convert_encoding($query ?? self::UNDEFINED, 'UTF-8');
+        if (!is_string($query)) {
+            $query = self::UNDEFINED;
+        }
+        $span->setAttributes([
+            TraceAttributes::DB_QUERY_TEXT => $query,
+            TraceAttributes::DB_OPERATION_NAME => self::extractQueryCommand($query),
+        ]);
+
         self::addTransactionLink($tracker, $span, $mysqli);
+
+        if (class_exists('OpenTelemetry\Contrib\SqlCommenter\SqlCommenter') && $query !== self::UNDEFINED) {
+            /**
+             * @psalm-suppress UndefinedClass
+             */
+            $commenter = \OpenTelemetry\Contrib\SqlCommenter\SqlCommenter::getInstance();
+            $query = $commenter->inject($query);
+            if ($commenter->isAttributeEnabled()) {
+                $span->setAttributes([
+                    TraceAttributes::DB_QUERY_TEXT => (string) $query,
+                ]);
+            }
+            if ($obj) {
+                return [
+                    0 => $query,
+                ];
+            }
+
+            return [
+                1 => $query,
+            ];
+
+        }
+
+        return [];
     }
 
     private static function queryPostHook(CachedInstrumentation $instrumentation, MySqliTracker $tracker, $obj, array $params, mixed $retVal, ?\Throwable $exception)
@@ -454,9 +491,6 @@ private static function queryPostHook(CachedInstrumentation $instrumentation, My
 
         $attributes = $tracker->getMySqliAttributes($mysqli);
 
-        $attributes[TraceAttributes::DB_QUERY_TEXT] = mb_convert_encoding($query, 'UTF-8');
-        $attributes[TraceAttributes::DB_OPERATION_NAME] = self::extractQueryCommand($query);
-
         if ($retVal === false || $exception) {
             $attributes[TraceAttributes::DB_RESPONSE_STATUS_CODE] =  $mysqli->errno;
         }
@@ -466,6 +500,19 @@ private static function queryPostHook(CachedInstrumentation $instrumentation, My
 
     }
 
+    /**
+     * multi_query can execute multiple queries in one call. We will create a span for the multi_query call, but we will also track the individual queries and their results, creating spans for each query in the multi_query call.
+     * The individual query spans will be created in the next_result hook, which is called to fetch the results of each query in the multi_query call.
+     * As QueryPreHook has database span context propagation logic, we need to create this multiQueryPrehook function for multi_query to keep the pre-hook function unchanged.
+     */
+    /** @param non-empty-string $spanName */
+    private static function multiQueryPreHook(string $spanName, CachedInstrumentation $instrumentation, MySqliTracker $tracker, $obj, array $params, ?string $class, string $function, ?string $filename, ?int $lineno): void
+    {
+        $span = self::startSpan($spanName, $instrumentation, $class, $function, $filename, $lineno, []);
+        $mysqli = $obj ? $obj : $params[0];
+        self::addTransactionLink($tracker, $span, $mysqli);
+    }
+
     private static function multiQueryPostHook(CachedInstrumentation $instrumentation, MySqliTracker $tracker, $obj, array $params, mixed $retVal, ?\Throwable $exception)
     {
 

src/Instrumentation/PDO/README.md

@@ -33,4 +33,11 @@ otel.instrumentation.pdo.distribute_statement_to_linked_spans = true
 or environment variable:
 ```shell
 OTEL_PHP_INSTRUMENTATION_PDO_DISTRIBUTE_STATEMENT_TO_LINKED_SPANS=true
+```
+
+## Database Context Propagation
+
+Enable context propagation for database queries by installing the following packages:
+```shell
+composer require open-telemetry/opentelemetry-sqlcommenter
 ```

src/Instrumentation/PDO/src/PDOInstrumentation.php

@@ -19,9 +19,11 @@
 use PDOStatement;
 use Throwable;
 
+/** @phan-file-suppress PhanUndeclaredClassMethod */
 class PDOInstrumentation
 {
     public const NAME = 'pdo';
+    private const UNDEFINED = 'undefined';
 
     public static function register(): void
     {
@@ -112,8 +114,12 @@ public static function register(): void
                 /** @psalm-suppress ArgumentTypeCoercion */
                 $builder = self::makeBuilder($instrumentation, 'PDO::query', $function, $class, $filename, $lineno)
                     ->setSpanKind(SpanKind::KIND_CLIENT);
+                $query = mb_convert_encoding($params[0] ?? self::UNDEFINED, 'UTF-8');
+                if (!is_string($query)) {
+                    $query = 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, $query);
                 }
                 $parent = Context::getCurrent();
                 $span = $builder->startSpan();
@@ -122,6 +128,35 @@ public static function register(): void
                 $span->setAttributes($attributes);
 
                 Context::storage()->attach($span->storeInContext($parent));
+
+                if (class_exists('OpenTelemetry\Contrib\SqlCommenter\SqlCommenter') && $query !== 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':
+                                /**
+                                 * @psalm-suppress UndefinedClass
+                                 */
+                                $commenter = \OpenTelemetry\Contrib\SqlCommenter\SqlCommenter::getInstance();
+                                $query = $commenter->inject($query);
+                                if ($commenter->isAttributeEnabled()) {
+                                    $span->setAttributes([
+                                        DbAttributes::DB_QUERY_TEXT => (string) $query,
+                                    ]);
+                                }
+
+                                return [
+                                    0 => $query,
+                                ];
+                            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);
@@ -135,8 +170,12 @@ public static function register(): void
                 /** @psalm-suppress ArgumentTypeCoercion */
                 $builder = self::makeBuilder($instrumentation, 'PDO::exec', $function, $class, $filename, $lineno)
                     ->setSpanKind(SpanKind::KIND_CLIENT);
+                $query = mb_convert_encoding($params[0] ?? self::UNDEFINED, 'UTF-8');
+                if (!is_string($query)) {
+                    $query = 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, $query);
                 }
                 $parent = Context::getCurrent();
                 $span = $builder->startSpan();
@@ -145,6 +184,35 @@ public static function register(): void
                 $span->setAttributes($attributes);
 
                 Context::storage()->attach($span->storeInContext($parent));
+
+                if (class_exists('OpenTelemetry\Contrib\SqlCommenter\SqlCommenter') && $query !== 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':
+                                /**
+                                 * @psalm-suppress UndefinedClass
+                                 */
+                                $commenter = \OpenTelemetry\Contrib\SqlCommenter\SqlCommenter::getInstance();
+                                $query = $commenter->inject($query);
+                                if ($commenter->isAttributeEnabled()) {
+                                    $span->setAttributes([
+                                        DbAttributes::DB_QUERY_TEXT => (string) $query,
+                                    ]);
+                                }
+
+                                return [
+                                    0 => $query,
+                                ];
+                            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/PostgreSql/README.md

@@ -67,6 +67,13 @@ The extension can be disabled via [runtime configuration](https://opentelemetry.
 OTEL_PHP_DISABLED_INSTRUMENTATIONS=postgresql
 ```
 
+## Database Context Propagation
+
+Enable context propagation for database queries by installing the following packages:
+```shell
+composer require open-telemetry/opentelemetry-sqlcommenter
+```
+
 ## Compatibility
 
 PHP 8.2 or newer is required