Documentation menu

Integrations

WordPress Integration

The Perfbase WordPress plugin provides automatic performance monitoring for WordPress sites, including WooCommerce. Requires WordPress 5.3+ and PHP 7.4 through 8.4.

Installation

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

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

Install the plugin from WordPress.org: Perfbase.

From wp-admin, go to Plugins > Add New and search for Perfbase. You can also download the ZIP from WordPress.org and upload it through the WordPress admin plugin installer.

For source/manual installs, copy the plugin to wp-content/plugins/perfbase and run composer install --no-dev --optimize-autoloader inside the plugin directory.

Activate the plugin in Plugins in the WordPress admin.

Configuration

Configure via Settings > Perfbase in the admin panel. The settings page is the normal setup path for the API key, enabled state, sample rate, advanced transport options, context toggles, feature flags, status-code filtering, and exclusions.

Runtime settings are loaded as defaults, then saved WordPress options, then supported wp-config.php constants. Those constants remain available as hard overrides for managed deployments and take priority over the admin UI for the core keys they map to.

Constants

Constant	Default	Description
`PERFBASE_ENABLED`	`false`	Master on/off switch.
`PERFBASE_API_KEY`	`''`	Your project API key. Required.
`PERFBASE_SAMPLE_RATE`	`0.1`	Fraction of eligible HTTP, AJAX, cron, and WP-CLI executions to profile (0.0–1.0). `0.1` = 10%.
`PERFBASE_API_URL`	`https://ingress.perfbase.cloud`	Ingestion endpoint.
`PERFBASE_TIMEOUT`	`10`	HTTP timeout in seconds for trace submission.
`PERFBASE_PROXY`	-	Optional proxy URL.
`PERFBASE_FLAGS`	`DefaultFlags`	SDK feature flags bitmask. See Feature flags.
`PERFBASE_PROFILE_HTTP_STATUS_CODES`	`200-299,500-599`	HTTP response status codes that should be submitted. Leave empty to drop all HTTP trace submissions.
`PERFBASE_DEBUG`	`false`	Throw profiling errors instead of silently logging them.
`PERFBASE_LOG_ERRORS`	`true`	Log profiling errors via `error_log()`.
`PERFBASE_ENVIRONMENT`	`wp_get_environment_type()`	Metadata fallback used when the WordPress environment helper is unavailable; then `WP_DEBUG` maps to `development`, otherwise `production`.
`PERFBASE_APP_VERSION`	WordPress version	Metadata override for the application version recorded on traces.

Context toggles

Control which types of requests are profiled. These are configured in the admin UI:

Setting	Default	Description
Profile Admin Area	Off	Profile `wp-admin` requests.
Profile AJAX Requests	On	Profile WordPress AJAX requests (`admin-ajax.php`).
Profile Cron Jobs	On	Profile WordPress cron executions.
Profile WP-CLI Commands	Off	Profile WP-CLI commands.

Include and exclude filters

Control which paths are profiled with include/exclude patterns, configured in the admin UI under Exclusions (one pattern per line):

Default includes: * for http, ajax, cron, and cli

Default excludes: /wp-content/uploads/*, /favicon.ico

Default user agent excludes: bot, crawler, spider (case-insensitive substring match)

Pattern types

Glob patterns: /api/*, /wp-admin/edit.php (matched via fnmatch())
Regex patterns: /^POST \/wp-json\// (wrapped in forward slashes)
Catch-all: * or .* matches everything

Patterns are tested against both the request path and {METHOD} {path} (e.g., GET /my-page).

Span and action naming

The plugin keeps span names low-cardinality and stores the request-specific name in the action attribute:

Context	Span name	`action` attribute
Standard HTTP and enabled admin requests	`http`	`{METHOD} {path}` with no query string
AJAX requests	`ajax`	`ajax.{sanitizedAction}` plus `ajax.action`
WordPress cron	`cron`	`cron.execution`
WP-CLI commands	`cli`	Command name plus `cli.command`

What gets profiled

The plugin hooks into WordPress lifecycle events automatically after it is activated, enabled, and configured with an API key.

Profiling starts from the init hook at priority -999 and stops on shutdown at priority 999. HTTP template context is added on template_redirect, and outbound WordPress HTTP URLs are recorded from pre_http_request.

WordPress lifecycle

Theme setup and plugin load phases
wp_head and wp_footer milestones
Database query count, slow queries (>100ms), and total query time (requires SAVEQUERIES)
Memory usage (peak and current)
Active plugin count

Content events

Post creation and updates (with post type)
Comment insertion
User login and logout

REST API

Route and HTTP method recorded when a REST API request is detected

Outbound HTTP

External HTTP request URLs are tracked (scheme + host + path only, no query parameters)

WooCommerce

If WooCommerce is active, the plugin additionally tracks:

WooCommerce version
Current page type (shop, product, cart, checkout, account)
Product ID and type on product pages
Cart additions with quantity
New order creation

Automatic attributes

Every trace includes these attributes automatically:

Attribute	Source
`action`	HTTP uses `{METHOD} {path}` with no query string; AJAX, cron, and CLI use the context-specific actions above.
`hostname`	`gethostname()`
`environment`	`wp_get_environment_type()` or `PERFBASE_ENVIRONMENT`
`app_version`	`PERFBASE_APP_VERSION` or WordPress version
`php_version`	PHP version
`wordpress.version`	WordPress version
`http_method`	Request method
`http_url`	Full URL without query string
`http_status_code`	Response status code
`user_ip`	Client IP (checks CF-Connecting-IP, X-Forwarded-For, etc.)
`user_agent`	User agent string
`user_id`	WordPress user ID (if logged in)

WordPress-specific attributes use dot notation (wordpress.version, woocommerce.page). Core trace fields use underscores (http_method, http_status_code).

Sample rate

The sample rate controls what fraction of eligible executions are profiled:

define('PERFBASE_SAMPLE_RATE', 1.0);   // Profile everything (development)
define('PERFBASE_SAMPLE_RATE', 0.1);   // 10% of requests (production)
define('PERFBASE_SAMPLE_RATE', 0.01);  // 1% of requests (high-traffic)

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

Error handling

Profiling never crashes your site. In production, all profiling errors are caught and optionally logged via error_log(). With PERFBASE_DEBUG 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 simply does not profile. A warning is shown on the settings page.

Admin settings page

The settings page at Settings > Perfbase provides:

API key and profiling toggle
Sample rate configuration
Advanced options (API URL, timeout, proxy)
Context toggles (admin, AJAX, cron, CLI)
Feature flag checkboxes
HTTP status-code allowlist
Include/exclude path patterns
User agent exclusions
System information: shows plugin version, PHP version, extension availability, and current profiling status

Uninstalling

Deactivating the plugin stops all profiling immediately. Uninstalling (deleting) the plugin removes all saved settings from the database.

← Symfony Integration CakePHP Integration →