Added prepend vs append opt-in

Author: jerrytfleung

src/Instrumentation/PDO/README.md

@@ -35,6 +35,7 @@ or environment variable:
 OTEL_PHP_INSTRUMENTATION_PDO_DISTRIBUTE_STATEMENT_TO_LINKED_SPANS=true
 ```
 
+### SQL Commenter feature
 The [sqlcommenter](https://google.github.io/sqlcommenter/) feature can be enabled using configuration directive:
 ```
 otel.instrumentation.pdo.sql_commenter = true
@@ -43,10 +44,18 @@ or environment variable:
 ```shell
 OTEL_PHP_INSTRUMENTATION_PDO_SQL_COMMENTER=true
 ```
-
-and its attribute can be configured using the following configuration directive:
+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
+```
+The modified query statement by default will not update `TraceAttributes::DB_QUERY_TEXT` due to high cardinality risk, but it can be configured using the following configuration directive:
 ```
-otel.instrumentation.pdo.sql_commenter_attribute = true
+otel.instrumentation.pdo.sql_commenter.attribute = true
 ```
 or environment variable:
 ```shell

src/Instrumentation/PDO/src/PDOInstrumentation.php

@@ -127,7 +127,7 @@ public static function register(): void
 
                 Context::storage()->attach($span->storeInContext($parent));
                 if (self::isSqlCommenterEnabled() && $sqlStatement !== self::UNDEFINED) {
-                    $sqlStatement = self::appendSqlComments($sqlStatement, true);
+                    $sqlStatement = self::addSqlComments($sqlStatement, true);
                     if (self::isSqlCommenterAttributeEnabled()) {
                         $span->setAttributes([
                             TraceAttributes::DB_QUERY_TEXT => $sqlStatement,
@@ -168,7 +168,7 @@ public static function register(): void
 
                 Context::storage()->attach($span->storeInContext($parent));
                 if (self::isSqlCommenterEnabled() && $sqlStatement !== self::UNDEFINED) {
-                    $sqlStatement = self::appendSqlComments($sqlStatement, true);
+                    $sqlStatement = self::addSqlComments($sqlStatement, true);
                     if (self::isSqlCommenterAttributeEnabled()) {
                         $span->setAttributes([
                             TraceAttributes::DB_QUERY_TEXT => $sqlStatement,
@@ -209,7 +209,7 @@ public static function register(): void
 
                 Context::storage()->attach($span->storeInContext($parent));
                 if (self::isSqlCommenterEnabled() && $sqlStatement !== self::UNDEFINED) {
-                    $sqlStatement = self::appendSqlComments($sqlStatement, false);
+                    $sqlStatement = self::addSqlComments($sqlStatement, false);
                     if (self::isSqlCommenterAttributeEnabled()) {
                         $span->setAttributes([
                             TraceAttributes::DB_QUERY_TEXT => $sqlStatement,
@@ -394,16 +394,25 @@ private static function isSqlCommenterEnabled(): bool
         return filter_var(get_cfg_var('otel.instrumentation.pdo.sql_commenter'), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
     }
 
+    private static function isSqlCommenterPrepend(): bool
+    {
+        if (class_exists('OpenTelemetry\SDK\Common\Configuration\Configuration')) {
+            return Configuration::getBoolean('OTEL_PHP_INSTRUMENTATION_PDO_SQL_COMMENTER_PREPEND', false);
+        }
+
+        return filter_var(get_cfg_var('otel.instrumentation.pdo.sql_commenter.prepend'), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
+    }
+
     private static function isSqlCommenterAttributeEnabled(): bool
     {
         if (class_exists('OpenTelemetry\SDK\Common\Configuration\Configuration')) {
             return Configuration::getBoolean('OTEL_PHP_INSTRUMENTATION_PDO_SQL_COMMENTER_ATTRIBUTE', false);
         }
 
-        return filter_var(get_cfg_var('otel.instrumentation.pdo.sql_commenter_attribute'), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
+        return filter_var(get_cfg_var('otel.instrumentation.pdo.sql_commenter.attribute'), FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE) ?? false;
     }
 
-    private static function appendSqlComments(string $query, bool $withTraceContext): string
+    private static function addSqlComments(string $query, bool $withTraceContext): string
     {
         $comments = [];
         if ($withTraceContext) {
@@ -413,9 +422,13 @@ private static function appendSqlComments(string $query, bool $withTraceContext)
             $comments[$key] = $value;
         }
         $query = trim($query);
+        if (self::isSqlCommenterPrepend()) {
+            return Utils::formatComments(array_filter($comments)) . $query;
+        }
         $hasSemicolon = $query !== '' && $query[strlen($query) - 1] === ';';
         $query = rtrim($query, ';');
 
         return $query . Utils::formatComments(array_filter($comments)) . ($hasSemicolon ? ';' : '');
+
     }
 }