Joomla Integration

The Perfbase Joomla system plugin provides automatic profiling for HTTP requests and CLI commands. Supports Joomla 4.4+ and 5.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 Joomla plugin:

composer require perfbase/joomla

Enable the plugin in Extensions > Plugins, then search for System - Perfbase and enable it.

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 requests to profile (0.0–1.0). `0.1` = 10%.
Timeout	`5`	HTTP timeout in seconds for trace submission.
Proxy	-	Optional proxy URL.
Feature Flags	`DefaultFlags`	SDK feature flags bitmask. See Feature flags.

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 gets a span named using Joomla’s routing info when available (e.g., http.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 gets a span named console.{command} (e.g., console.cache.clean). The command name 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 requests are profiled:

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

When a request isn’t sampled, no profiling overhead is incurred.

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.

← Slim Integration CodeIgniter 4 Integration →