Drupal instrumentation - Mega pack

README.md

@@ -41,5 +41,11 @@ The extension can be disabled via runtime configuration:
 OTEL_PHP_DISABLED_INSTRUMENTATIONS=drupal
 ```
 
+### Query Explain Threshold Configuration
 
+The EXPLAIN threshold feature allows you to set a minimum duration threshold for capturing EXPLAIN results in your traces. When `OTEL_PHP_DRUPAL_EXPLAIN_QUERIES` is enabled, you can use `OTEL_PHP_DRUPAL_EXPLAIN_THRESHOLD` to specify the minimum query duration (in milliseconds) that should trigger EXPLAIN capture.
 
+For example:
+```
+OTEL_PHP_DRUPAL_EXPLAIN_THRESHOLD=100  # Capture EXPLAIN for queries taking longer than 100ms
+```

_register.php

@@ -2,10 +2,17 @@
 
 declare(strict_types=1);
 
+use OpenTelemetry\Contrib\Instrumentation\Drupal\CacheBackendInstrumentation;
 use OpenTelemetry\Contrib\Instrumentation\Drupal\DatabaseInstrumentation;
+use OpenTelemetry\Contrib\Instrumentation\Drupal\DrupalAutoRootSpan;
 use OpenTelemetry\Contrib\Instrumentation\Drupal\DrupalKernelInstrumentation;
+use OpenTelemetry\Contrib\Instrumentation\Drupal\EntityInstrumentation;
+use OpenTelemetry\Contrib\Instrumentation\Drupal\InstrumentModules;
 use OpenTelemetry\Contrib\Instrumentation\Drupal\HttpClientCallInstrumentation;
 use OpenTelemetry\Contrib\Instrumentation\Drupal\HttpClientRequestInstrumentation;
+use OpenTelemetry\Contrib\Instrumentation\Drupal\ViewsInstrumentation;
+use OpenTelemetry\Context\Context;
+use OpenTelemetry\Context\ContextStorage;
 use OpenTelemetry\SDK\Sdk;
 
 if (class_exists(Sdk::class) && Sdk::isInstrumentationDisabled(DrupalKernelInstrumentation::NAME) === TRUE) {
@@ -18,14 +25,25 @@
   return;
 }
 
+// Force disable the FiberBoundContextStorage because of the conflict
+// with Drupal Renderer service.
+// @see https://www.drupal.org/project/opentelemetry/issues/3488173
+// @todo Make a proper fix to work well with the FiberBoundContextStorage.
+$contextStorage = new ContextStorage();
+Context::setStorage($contextStorage);
+
 try {
+  CacheBackendInstrumentation::register();
+  DrupalAutoRootSpan::register();
   DrupalKernelInstrumentation::register();
   DatabaseInstrumentation::register();
+  EntityInstrumentation::register();
   HttpClientRequestInstrumentation::register();
   HttpClientCallInstrumentation::register();
+  InstrumentModules::registerModule(ViewsInstrumentation::class);
 }
 catch (Throwable $exception) {
-  \Drupal::logger("drupalInstrumentation")->error($exception->getMessage());
-
-  return;
+  throw $exception;
+  //\Drupal::logger("drupalInstrumentation")->error($exception->getMessage());
+  //return;
 }

composer.json

@@ -8,7 +8,8 @@
         "open-telemetry/sdk": "^1",
         "open-telemetry/sem-conv": "^1.23",
         "symfony/http-client": "6.4.x-dev",
-        "nyholm/psr7": "^1.8@dev"
+        "nyholm/psr7": "^1.8@dev",
+        "performance-x/opentelemetry-php-instrumentation-trait": "^1.1.1"
     },
     "license": "Apache-2.0",
     "minimum-stability": "dev",

phpcs.xml.dist

@@ -0,0 +1,57 @@
+<?xml version="1.0"?>
+<ruleset name="OpenTelemetry Instrumentation">
+    <description>Coding standards for OpenTelemetry Instrumentation Trait</description>
+
+    <!-- Use Drupal coding standards -->
+    <rule ref="Drupal">
+        <!-- Disable overly strict documentation rules -->
+        <exclude name="Drupal.Commenting.DocComment.MissingShort"/>
+        <exclude name="Drupal.Commenting.DocComment.Empty"/>
+        <exclude name="Drupal.Commenting.VariableComment.Missing"/>
+        <exclude name="Drupal.Commenting.FunctionComment.MissingParamComment"/>
+        <exclude name="Drupal.Commenting.FunctionComment.MissingReturnComment"/>
+        <exclude name="Drupal.Commenting.FunctionComment.ParamMissingDefinition"/>
+        <exclude name="Drupal.Classes.ClassFileName.NoMatch"/>
+    </rule>
+    <rule ref="DrupalPractice"/>
+
+    <!-- Scan these files -->
+    <file>./src/</file>
+    <file>./tests/</file>
+
+    <!-- PHP extensions to check -->
+    <arg name="extensions" value="php"/>
+
+    <!-- Drupal version -->
+    <config name="drupal_core_version" value="11"/>
+
+    <!-- Use 's' to print the full error message -->
+    <arg value="s"/>
+    <arg name="colors"/>
+
+    <!-- Two spaces for indentation -->
+    <rule ref="Generic.WhiteSpace.ScopeIndent">
+        <properties>
+            <property name="indent" value="2"/>
+            <property name="tabIndent" value="false"/>
+        </properties>
+    </rule>
+
+    <!-- Line length -->
+    <rule ref="Drupal.Files.LineLength">
+        <properties>
+            <property name="lineLimit" value="100"/>
+            <property name="absoluteLineLimit" value="120"/>
+        </properties>
+    </rule>
+
+    <!-- Class/file naming -->
+    <rule ref="Drupal.NamingConventions.ValidClassName"/>
+
+    <!-- Ensure proper file doc blocks -->
+    <rule ref="Drupal.Commenting.FileComment"/>
+    <rule ref="Drupal.Commenting.DocComment"/>
+
+    <!-- PHP version compatibility -->
+    <config name="php_version" value="80000"/>
+</ruleset>

src/CacheBackendInstrumentation.php

@@ -0,0 +1,116 @@
+<?php
+
+namespace OpenTelemetry\Contrib\Instrumentation\Drupal;
+
+use Drupal\Core\Cache\CacheBackendInterface;
+
+/**
+ *
+ */
+class CacheBackendInstrumentation extends InstrumentationBase {
+  protected const CLASSNAME = CacheBackendInterface::class;
+  protected static array $cacheBins = [];
+
+  /**
+   *
+   */
+  public static function register(): void {
+    static::create(
+      name: 'io.opentelemetry.contrib.php.drupal',
+      prefix: 'drupal.cache',
+      className: static::CLASSNAME
+    );
+  }
+
+  /**
+   *
+   */
+  protected function registerInstrumentation(): void {
+    // Capture bin name in constructor.
+    $this->helperHook(
+      methodName: '__construct',
+      preHandler: function ($spanBuilder, $object, array $params, string $class) {
+        // Get actual constructor parameters at runtime.
+        $reflection = new \ReflectionClass($class);
+        $constructor = $reflection->getConstructor();
+        if (!$constructor) {
+          return;
+        }
+
+        foreach ($constructor->getParameters() as $position => $parameter) {
+          if ($parameter->getName() === 'bin' && isset($params[$position])) {
+            $bin = $params[$position];
+            $spanBuilder->setAttribute($this->getAttributeName('bin'), $bin);
+            static::$cacheBins[spl_object_id($object)] = $bin;
+            break;
+          }
+        }
+      }
+    );
+
+    // Define operations.
+    $operations = [
+      'get' => [
+        'params' => ['cid' => 'cache_key'],
+        'postHandler' => function ($span, $object, array $namedParams, $returnValue) {
+          $span->setAttribute($this->getAttributeName('hit'), $returnValue !== FALSE);
+          $span->setAttribute($this->getAttributeName('valid'), !empty($returnValue->valid));
+        },
+      ],
+      'getMultiple' => [
+        'params' => ['cids' => 'cache_keys'],
+        'postHandler' => function ($span, $object, array $namedParams, $returnValue) {
+          $missCount = count($namedParams['cids']);
+          $hitCount = count($returnValue);
+          $total = $missCount + $hitCount;
+
+          $span->setAttribute($this->getAttributeName('hit_count'), $hitCount);
+          $span->setAttribute($this->getAttributeName('miss_count'), $missCount);
+          $span->setAttribute($this->getAttributeName('hit_ratio'), $total > 0 ? $hitCount / $total : 0);
+        },
+      ],
+      'set' => [
+        'params' => ['cid' => 'cache_key', 'tags'],
+        'preHandler' => function ($spanBuilder, $object, array $namedParams) {
+          $spanBuilder->setAttribute($this->getAttributeName('ttl'), isset($namedParams['expire']) ? $namedParams['expire'] : -1);
+          $spanBuilder->setAttribute($this->getAttributeName('tag_count'), count($namedParams['tags'] ?? []));
+        },
+      ],
+      'deleteMultiple' => [
+        'params' => ['cids' => 'cache_keys'],
+        'preHandler' => function ($spanBuilder, $object, array $namedParams) {
+          $spanBuilder->setAttribute($this->getAttributeName('delete_count'), count($namedParams['cids']));
+        },
+      ],
+      'invalidateMultiple' => [
+        'params' => ['cids' => 'cache_keys'],
+        'preHandler' => function ($spanBuilder, $object, array $namedParams) {
+          $spanBuilder->setAttribute($this->getAttributeName('invalidate_count'), count($namedParams['cids']));
+        },
+      ],
+      'delete' => [
+        'params' => ['cid' => 'cache_key'],
+      ],
+      'invalidate' => [
+        'params' => ['cid' => 'cache_key'],
+      ],
+      'deleteAll' => [],
+      'invalidateAll' => [],
+      'removeBin' => [],
+    ];
+
+    // Common handler for adding bin information.
+    $binHandler = function ($spanBuilder, $object) {
+      $objectId = spl_object_id($object);
+      $bin = static::$cacheBins[$objectId] ?? 'unknown';
+      $spanBuilder->setAttribute($this->getAttributeName('bin'), $bin);
+    };
+
+    // Register all operations with common bin handling.
+    $this->registerOperations(
+      operations: $operations,
+      commonPreHandler: $binHandler
+    );
+  }
+
+}

src/DatabaseInstrumentation.php

@@ -3,57 +3,113 @@
 namespace OpenTelemetry\Contrib\Instrumentation\Drupal;
 
 use Drupal\Core\Database\Connection;
-use OpenTelemetry\API\Instrumentation\CachedInstrumentation;
 use OpenTelemetry\API\Trace\SpanKind;
-use OpenTelemetry\Context\Context;
 use OpenTelemetry\SemConv\TraceAttributes;
-use function \OpenTelemetry\Instrumentation\hook;
 
+/**
+ * Provides OpenTelemetry instrumentation for Drupal database operations.
+ */
 class DatabaseInstrumentation extends InstrumentationBase {
-
+  protected const CLASSNAME = Connection::class;
   public const DB_VARIABLES = 'db.variables';
 
+  /**
+   *
+   */
   public static function register(): void {
+    static::create(
+      name: 'io.opentelemetry.contrib.php.drupal',
+      prefix: 'drupal.database',
+      className: static::CLASSNAME
+    );
+  }
 
-    $instrumentation = new CachedInstrumentation('io.opentelemetry.contrib.php.drupal');
+  protected bool $inQuery = FALSE;
 
-    hook(
-      Connection::class,
-      'query',
-      static::preClosure($instrumentation),
-      static::postClosure()
-    );
+  protected bool $explainQueries = FALSE;
+  /**
+   * Minimum duration threshold (in seconds) for capturing EXPLAIN results.
+   *
+   * When explainQueries is enabled, only queries that take longer than this
+   * threshold will have their EXPLAIN results captured in the span. This helps
+   * prevent unnecessary overhead for fast queries.
+   *
+   * Configure via OTEL_PHP_DRUPAL_EXPLAIN_THRESHOLD environment variable.
+   * Value should be in milliseconds, e.g.:
+   * OTEL_PHP_DRUPAL_EXPLAIN_THRESHOLD=100 // For 100ms threshold
+   *
+   * @var float Time in seconds (e.g., 0.1 for 100ms)
+   */
+  protected float $explainQueriesThreshold = 0.0;
 
+  /**
+   *
+   */
+  protected function registerInstrumentation(): void {
+
+    $this->explainQueries = getenv('OTEL_PHP_DRUPAL_EXPLAIN_QUERIES') ? TRUE : FALSE;
+    $this->explainQueriesThreshold = (float) (getenv('OTEL_PHP_DRUPAL_EXPLAIN_THRESHOLD') ?? 0) / 1000;
+
+    $operations = [
+      'query' => [
+        'preHandler' => function ($spanBuilder, Connection $connection, array $namedParams) {
+          if ($this->inQuery) {
+              return;
+          }
+
+          $spanBuilder
+            ->setSpanKind(SpanKind::KIND_CLIENT)
+            ->setAttribute(TraceAttributes::DB_SYSTEM, 'mariadb')
+            ->setAttribute(TraceAttributes::DB_STATEMENT, $namedParams['query']);
+
+          if (isset($namedParams['args']) === TRUE) {
+            $cleanVariables = array_map(
+              static fn ($value) => is_array($value) ? json_encode($value) : (string) $value,
+              $namedParams['args']
+            );
+            $spanBuilder->setAttribute(self::DB_VARIABLES, $cleanVariables);
+          }
+
+          if ($this->explainQueries) {
+            $this->captureQueryExplain(
+              $spanBuilder,
+              $connection,
+              $namedParams['query'],
+              $namedParams['args'] ?? []
+            );
+          }
+        },
+      ],
+    ];
+
+    $this->registerOperations($operations);
   }
 
   /**
-   * @param \OpenTelemetry\API\Instrumentation\CachedInstrumentation $instrumentation
+   * Captures and adds EXPLAIN query results as attributes to the span builder.
    *
-   * @return \Closure
+   * This function executes an EXPLAIN query and adds the results as attributes
+   * to the span builder if the query execution time exceeds the configured threshold.
+   *
+   * @param mixed $spanBuilder The span builder instance
+   * @param \Drupal\Core\Database\Connection $connection Database connection
+   * @param string $query The SQL query to explain
+   * @param array $args Query arguments
    */
-  public static function preClosure(CachedInstrumentation $instrumentation): \Closure {
-    return static function (Connection $connection, array $params, string $class, string $function, ?string $filename, ?int $lineno) use ($instrumentation) {
-      $parent = Context::getCurrent();
-
-      /** @var \OpenTelemetry\API\Trace\SpanBuilderInterface $span */
-      $span = $instrumentation->tracer()->spanBuilder('database::query')
-        ->setParent($parent)
-        ->setSpanKind(SpanKind::KIND_CLIENT)
-        ->setAttribute(TraceAttributes::CODE_FUNCTION, $function)
-        ->setAttribute(TraceAttributes::CODE_NAMESPACE, $class)
-        ->setAttribute(TraceAttributes::CODE_FILEPATH, $filename)
-        ->setAttribute(TraceAttributes::CODE_LINENO, $lineno)
-        ->setAttribute(TraceAttributes::DB_SYSTEM, 'mariadb')
-        ->setAttribute(TraceAttributes::DB_STATEMENT, $params[0]);
-      if (isset($params[1]) === TRUE) {
-        $cleanVariables = array_map(static fn ($value) => is_array($value) ? json_encode($value) : (string) $value, $params[1]);
-        $span->setAttribute(self::DB_VARIABLES, $cleanVariables);
-      }
-      $span = $span->startSpan();
+  protected function captureQueryExplain($spanBuilder, Connection $connection, string $query, array $args): void {
+    $this->inQuery = TRUE;
+    try {
+      $start = microtime(true);
+      $explain_results = $connection->query('EXPLAIN ' . $query, $args)->fetchAll();
+      $duration = microtime(true) - $start;
 
-      Context::storage()
-        ->attach($span->storeInContext($parent));
-    };
+      if ($duration >= $this->explainQueriesThreshold) {
+        $spanBuilder->setAttribute($this->getAttributeName('explain'), json_encode($explain_results));
+      }
+    }
+    catch (\Exception $e) {
+    }
+    $this->inQuery = FALSE;
   }
 
 }