Drupal Integration

The Perfbase Drupal module provides automatic profiling for HTTP requests, Drush commands, cron runs, and queue workers. Supports Drupal 10.3+ and 11.x.

Installation

Install the Perfbase PHP extension first. This is what does the actual profiling:

bash -c "$(curl -fsSL https://cdn.perfbase.com/install.sh)"

Then install the Drupal module:

composer require perfbase/drupal

Enable the module:

drush en perfbase

Configuration

Configure via the admin UI at Configuration > Development > Perfbase, or override in settings.php for environment-specific values:

// settings.php
$settings['perfbase'] = [
    'enabled' => TRUE,
    'api_key' => 'your-api-key',
];

Configuration is resolved in three layers (later wins): module defaults → admin UI settings → settings.php overrides. The settings.php layer takes priority over the admin form, which is useful for keeping API keys out of config exports.

All options

Context toggles

Include and exclude filters

Control what gets profiled per context with include/exclude patterns, configured in the admin UI (one pattern per line):

// settings.php example
$settings['perfbase'] = [
    'include' => [
        'http' => ['*'],                    // All routes (default)
        'console' => ['*'],
        'cron' => ['*'],
        'queue' => ['*'],
    ],
    'exclude' => [
        'http' => ['/admin/reports/*'],
        'console' => ['cache:*'],
    ],
];

Pattern types

• Glob patterns: /admin/*, /node/* (uses fnmatch()-style matching)
• Regex patterns: /^GET \/api\// (wrapped in forward slashes)
• Catch-all: * or .* matches everything

HTTP patterns are tested against multiple representations of the request: {METHOD} {path}, the raw path, normalized path (with {id} and {uuid} placeholders), route name, and {METHOD} {route_name}.

HTTP profiling

HTTP requests are profiled automatically via a kernel event subscriber. The subscriber hooks into four Symfony kernel events:

1. kernel.request (priority 1000): creates a profiling lifecycle and starts the trace span.
2. kernel.response (priority -1000): records the HTTP status code.
3. kernel.exception (priority -1000): records the exception message.
4. kernel.terminate (priority -1000): stops the span and submits the trace. Runs after the response is sent.

Sub-requests are automatically skipped. Only the main request is profiled.

Each request gets a span named http.{METHOD}.{path} using the route path template when available (e.g., http.GET./node/{node} rather than http.GET./node/42). Numeric path segments are normalized to {id} and UUIDs to {uuid} for low-cardinality grouping.

Automatic attributes

Drush and console command profiling

Console commands are profiled via Symfony console event listeners when profile_console is enabled (off by default).

Each command gets a span named console.{command} (e.g., console.cache:rebuild). The exit code and any exceptions are recorded as attributes.

Enable in the admin UI or via settings.php:

$settings['perfbase'] = [
    'profile_console' => TRUE,
];

Cron profiling

Drupal cron runs are profiled automatically via a service decorator that wraps the core cron service. Each cron execution gets a span named cron.cron.run. Enabled by default.

Queue worker profiling

Queue item processing is profiled by wrapping every queue worker via a custom QueueWorkerManager. Each item processed gets its own span named queue.{plugin_id} (e.g., queue.my_module_worker). Enabled by default.

The module decorates the core plugin.manager.queue_worker service, so all queue workers, including contrib module workers, are automatically profiled without any code changes.

Sample rate

The sample rate controls what fraction of requests are profiled:

$settings['perfbase'] = [
    'sample_rate' => 1.0,    // Profile everything (development)
    'sample_rate' => 0.1,    // 10% of requests (production)
    'sample_rate' => 0.01,   // 1% of requests (high-traffic)
];

The sample rate is checked per request, per command, per cron run, and per queue item independently. When a request isn’t sampled, no profiling overhead is incurred.

Error handling

Profiling never crashes your site. In production (debug: false), all profiling errors are caught and optionally logged via error_log(). In development (debug: true), errors are thrown so you can catch configuration issues early.

If the Perfbase PHP extension is not installed, the module detects this gracefully and silently disables profiling.

Using the SDK directly

Access the SDK via the perfbase.factory service for manual profiling:

/** @var \Perfbase\SDK\Perfbase|null $perfbase */
$perfbase = \Drupal::service('perfbase.factory')->getClient();
if ($perfbase) {
    $perfbase->setAttribute('entity_type', $entity->getEntityTypeId());
}

See the PHP SDK docs for the full API reference.

Admin settings page

The settings form at Configuration > Development > Perfbase provides:

• API key and profiling toggle
• Sample rate, timeout, and proxy configuration
• Feature flags bitmask
• Context toggles (HTTP, console, cron, queue)
• Include/exclude filter textareas per context
• Environment and app version labels

Requires the administer site configuration permission.