Joomla Integration

The Perfbase Joomla system plugin provides automatic profiling for HTTP requests and CLI commands. Supports Joomla 4.4 and 5.x on PHP 8.1 through 8.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)"

Download the self-contained perfbase-joomla-<version>.zip artifact from the matching GitHub Release, then upload it through System > Install > Extensions in Joomla administrator. The ZIP includes production Composer dependencies under the plugin’s own vendor/ directory.

Enable the plugin in Extensions > Plugins, then search for System - Perfbase and enable it. Composer installs are useful for source development, but the release ZIP is the normal Joomla installation path.

Configuration

Configure the plugin via its settings panel in Extensions > Plugins > System - Perfbase. The settings are organized into three tabs:

Basic settings

Setting	Default	Description
Enable Perfbase	No	Master on/off switch. Requires API key to be set.
API Key	-	Your project API key. Required.
API URL	`https://ingress.perfbase.cloud`	Ingestion endpoint.
Sample Rate	`0.1`	Fraction of eligible requests and commands to profile (0.0–1.0). `0.1` = 10%.
Timeout	`5`	HTTP timeout in seconds for trace submission.
Proxy	-	Optional proxy URL.
Feature Flags	`8145`	SDK feature flags bitmask. See Feature flags.
HTTP status codes	`200-299,500-599`	HTTP response status codes that should be submitted.

Contexts

Setting	Default	Description
Profile Administrator	No	Whether to profile admin-area requests.
Environment	-	Environment label recorded on traces (defaults to `production`).
App Version	-	Application version, recorded on traces.
Include HTTP	`*`	Patterns for HTTP routes to profile (one per line).
Exclude HTTP	-	Patterns for HTTP routes to skip (one per line).
Include Console	`*`	Patterns for CLI commands to profile (one per line).
Exclude Console	-	Patterns for CLI commands to skip (one per line).

Debug

Setting	Default	Description
Debug Mode	No	When enabled, profiling errors are thrown instead of silently logged.
Log Errors	Yes	Log profiling errors via `error_log()`.

All configuration is managed through the standard Joomla plugin parameter system, with no configuration.php changes required.

Include and exclude filters

Control which routes and commands are profiled with include/exclude patterns (one per line in the plugin settings):

Pattern types

Glob patterns: /content/*, com_content (matched via fnmatch())
Regex patterns: /com_content/ (wrapped in forward slashes)
Catch-all: * or .* matches everything

What HTTP filters match against

Patterns are tested against multiple representations of the request:

The Joomla client name (site, administrator, api)
The action string (e.g., GET com_content:article:display)
The sanitized request path (e.g., /articles/{id})
The option value (e.g., com_content)
The view value (e.g., article)
The task value (e.g., display)
The combined route key (option:view:task)

For CLI, the filter candidate is the command name (e.g., cache:clean).

HTTP profiling

HTTP requests are profiled automatically via Joomla’s system event hooks:

onAfterInitialise: creates a profiling lifecycle, starts the trace span, and registers a shutdown fallback.
onAfterRoute: updates attributes with resolved routing context (option, view, task).
onAfterDispatch: records the response format (html, json, etc.).
onAfterRespond: records the HTTP status code, stops the span, and submits the trace.

A register_shutdown_function fallback ensures traces are submitted even if onAfterRespond never fires (e.g., fatal errors or early exits).

Each request uses the stable span name http. Joomla routing info is recorded in the action attribute when available (e.g., GET com_content:article:display). For SEF URLs without route info, the sanitized path is used with numeric segments replaced by {id} and UUIDs replaced by {id}.

Automatic attributes

Attribute	Source
`hostname`	`gethostname()`
`php_version`	PHP version
`environment`	Config value or `production`
`app_version`	Config value
`source`	`http`
`action`	e.g., `GET com_content:article:display`
`http_method`	Request method
`http_url`	Sanitized URL (no query string)
`http_status_code`	Response status code
`user_ip`	Client IP address
`user_agent`	User agent string
`user_id`	Joomla user ID (empty for guests)
`joomla.client`	`site`, `administrator`, `api`, or `cli`
`joomla.option`	e.g., `com_content`
`joomla.view`	e.g., `article`
`joomla.task`	e.g., `display`
`joomla.format`	e.g., `html`, `json` (if present)

CLI profiling

Joomla console commands are profiled automatically. When the application is running in CLI mode, the plugin creates a CLI lifecycle instead of an HTTP one.

Each command uses the stable span name artisan. The command name is recorded in the action attribute and cli.command, and is extracted from argv, falling back to the application name if no positional argument is found.

CLI profiling uses the console include/exclude filter context.

Sample rate

The sample rate controls what fraction of eligible requests and commands are profiled:

1.0: profile everything (development)
0.1: 10% of eligible requests and commands (production, default)
0.01: 1% of eligible requests and commands (high-traffic)

When a request or command isn’t sampled, no extension trace span is started.

Error handling

Profiling never crashes your site. In production (Debug Mode off), all profiling errors are caught and optionally logged via error_log(). With Debug Mode enabled, errors are thrown so you can catch configuration issues during development.

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

Current scope

The Joomla plugin v1 scope excludes:

Dedicated Joomla scheduler or task lifecycles.
Deep component or template execution timelines beyond the main trace span.

Administrator traffic is opt-in through the profile administrator setting.

← Slim Integration CodeIgniter 4 Integration →