Perfbase for Drupal

Drupal integration for Perfbase.

This module is a thin adapter over perfbase/php-sdk. It connects Drupal runtime lifecycles to the Perfbase profiler and ingestion API without implementing its own transport, trace format, or profiler runtime.

What It Supports

This module currently profiles:

• HTTP requests
• Drush and Symfony console commands
• Drupal cron runs
• Core Queue API worker execution

This module does not currently add dedicated support for:

• Messenger workers
• Batch API execution
• Install/update hook specific instrumentation
• Drupal-specific render/entity/cache enrichment beyond what the Perfbase extension already captures

Requirements

• PHP >=8.1 <8.6
• Drupal ^10.3 || ^11.0
• Composer
• Perfbase PHP extension installed and enabled
• A valid Perfbase API key

Installation

Install the module with Composer:

composer require perfbase/drupal

Enable the module:

drush en perfbase

Or enable it through the Drupal admin UI.

Configuration

The module stores runtime configuration in Drupal config as perfbase.settings.

Configuration is resolved in this order:

1. module defaults
2. saved Drupal config
3. settings.php overrides

That resolution logic is implemented in src/Config/ConfigResolver.php.

Admin UI

The settings form is available at:

/admin/config/development/perfbase

The form is implemented in src/Form/PerfbaseSettingsForm.php.

Minimum Required Settings

At minimum, production installs should set:

• enabled: true
• api_key: <your Perfbase API key>

Recommended starting values:

• sample_rate: 0.1
• profile_http: true
• exclude_admin_routes: true
• profile_console: false
• profile_cron: true
• profile_queue: true
• debug: false
• log_errors: true

settings.php Overrides

Use settings.php for deployment-time overrides that should win over saved config:

$settings['perfbase'] = [
'enabled' => TRUE,
'api_key' => 'pb_live_xxxxx',
'api_url' => 'https://ingress.perfbase.cloud',
'sample_rate' => 0.10,
'exclude_admin_routes' => TRUE,
'profile_http_status_codes' => [...range(200, 299), ...range(500, 599)],
'profile_http' => TRUE,
'profile_console' => FALSE,
'profile_cron' => TRUE,
'profile_queue' => TRUE,
'environment' => 'production',
'app_version' => '2026.04.08',
];

Configuration Reference

Key	Type	Default	Notes
enabled	bool	false	Module is effectively disabled until this is true and api_key is non-empty
debug	bool	false	Re-throws profiler exceptions instead of failing open
log_errors	bool	true	Logs profiler/runtime failures when not in debug mode
api_key	string	''	Required for submission
api_url	string	https://ingress.perfbase.cloud	Override for self-hosted or non-default receiver endpoints
timeout	int	10	Submission timeout in seconds
proxy	string	''	Optional outbound proxy URL
flags	int	8145	Passed through to the shared SDK as Perfbase feature flags
sample_rate	float	0.1	Value from 0.0 to 1.0
exclude_admin_routes	bool	true	Skip profiling routes marked with Drupal admin-route metadata
profile_http_status_codes	int[]	200-299, 500-599	Only HTTP responses with these status codes are submitted; add 404 if you want to keep not-found traces
profile_http	bool	true	Enables HTTP request profiling
profile_console	bool	false	Enables console / Drush profiling
profile_cron	bool	true	Enables cron profiling
profile_queue	bool	true	Enables core Queue API profiling
environment	string	''	Optional environment label
app_version	string	''	Optional application version label
include	map	* per context	Include filters for http, console, cron, and queue
exclude	map	empty per context	Exclude filters for http, console, cron, and queue

Persisted defaults are defined in config/install/perfbase.settings.yml, and runtime fallbacks are resolved in src/Config/ConfigResolver.php.

Filtering

Each supported context has include and exclude filters:

• http
• console
• cron
• queue

Supported filter forms:

• * or .* for match-all
• /regex/ expressions
• shell-style glob patterns

Example:

include:
http:
- 'GET /admin/*'console:
- 'cache:*'cron:
- 'cron.run'queue:
- 'my_worker'exclude:
http:
- 'GET /healthz'console:
- 'list'

Matching is implemented in src/Support/FilterMatcher.php.

Lifecycle Wiring

HTTP

HTTP profiling is wired through Symfony kernel events:

• kernel.request
• kernel.response
• kernel.exception
• kernel.terminate

Implementation:

• src/EventSubscriber/HttpLifecycleSubscriber.php
• src/Lifecycle/HttpRequestLifecycle.php

Console

Console and Drush command profiling is wired through Symfony console events:

• console.command
• console.error
• console.terminate

Implementation:

• src/EventSubscriber/ConsoleLifecycleSubscriber.php
• src/Lifecycle/ConsoleCommandLifecycle.php

Cron

Cron profiling is implemented by decorating Drupal’s cron service and wrapping run().

Implementation:

• src/Runtime/PerfbaseCronDecorator.php
• src/Lifecycle/CronLifecycle.php

Queue

Queue profiling is implemented by replacing plugin.manager.queue_worker with a Perfbase-aware queue worker manager and wrapping worker instances returned by createInstance().

Implementation:

• src/Queue/PerfbaseQueueWorkerManager.php
• src/Queue/ProfiledQueueWorker.php
• src/Lifecycle/QueueItemLifecycle.php

Naming and Attributes

The module keeps span names and action values low-cardinality:

• HTTP uses route-based or normalized request naming
• console uses the command name
• cron uses stable cron action naming
• queue uses the queue worker plugin ID

http_url is recorded without query strings.

Common attributes include:

• source
• action
• environment
• app_version
• hostname
• php_version

HTTP requests also attach:

• http_method
• http_url
• http_status_code
• user_ip
• user_agent
• user_id when available
• drupal.route_name when available

By default, HTTP profiling also skips routes marked as Drupal admin routes. You can disable that with exclude_admin_routes: false if you want admin traffic included.

By default, only responses in the configured profile_http_status_codes allowlist are submitted. The runtime default is 200-299 plus 500-599, so 404s are dropped unless you add them explicitly.

Naming logic is implemented in src/Support/SpanNaming.php.

Runtime Behavior

• The module is fail-open in production mode.
• Profiling errors are logged when log_errors is enabled.
• Debug mode rethrows exceptions so integration issues are visible during development.
• Submission occurs through the shared SDK and uses the installed Perfbase PHP extension.

Shared runtime services:

• src/Runtime/PerfbaseFactory.php
• src/Runtime/ActiveLifecycleRegistry.php
• src/Support/ErrorHandler.php

Production Notes

• Use settings.php for API keys and deployment-controlled overrides.
• Keep debug disabled in production.
• Start with a conservative sample_rate and increase as needed.
• Exclude health checks, noisy admin paths, or high-volume commands if they are not useful to retain.
• If you use a custom receiver, set api_url explicitly.

Validation

Current package validation includes:

• PHPUnit
• PHPStan level 9 with Drupal-aware analysis
• PHPCS with Drupal coding standards
• GitHub Actions coverage for one representative PHP version per supported Drupal line:
  • Drupal 10.3 on PHP 8.1
  • Drupal 11.x on PHP 8.3

Recent local coverage:

• Lines: 89.04%
• Methods: 73.74%

The current suite focuses on unit coverage plus fixture-backed wiring checks. It is not yet a full booted-Drupal kernel test suite.

Development

Install dependencies:

composer install

Run the full validation stack:

composer run lint

Run individual checks:

composer run test
composer run phpstan
composer run phpcs
XDEBUG_MODE=coverage vendor/bin/phpunit -c phpunit.xml --coverage-text

This package keeps Drupal scaffold output for fixture-based validation under tests/fixtures/drupal/web.

Documentation

Full documentation is available at perfbase.com/docs.

• Docs: perfbase.com/docs
• Issues: github.com/perfbaseorg/drupal/issues
• Support: support@perfbase.com

License

Apache-2.0. See LICENSE.txt.