Tracepoint Configuration

To trigger callgraph profiling or increasing the PHP sample rate by using a tracepoint a few additional php.ini settings are necessary.

Configuration for Dynamic Tracepoints

Dynamic tracepoints are enabled by default since Tideways PHP Extension 5.7 (March 2024).

To enable dynamic tracepoints in previous versions the following INI settings need to be activated:

tideways.dynamic_tracepoints.enable_web=1
tideways.dynamic_tracepoints.enable_cli=1

You can use these settings to disable tracepoints as well by setting them to 0.

These directives are system-level INI settings and cannot be configured through environment variables, directory overrides or directly via ini_set function. For php.ini changes to go into effect, you need to restart the webserver which is either Apache or PHP-FPM.

Advanced Settings for Dynamic Tracepoints

Changing the Update Interval

Each PHP process synchronizes the currently active tracepoints with the tideways-daemon by sending a message to the socket or TCP/IP port following these steps:

Don’t synchronize if INI settings for dynamic tracepoints are disabled (See basic configuration section above)
Synchronize once when the PHP process (CLI, Apache or PHP-FPM) starts and before the first PHP script is handled.
Synchronize every 60 seconds afterwards

The synchronization interval between PHP extension and daemon prevents increased TCP/socket traffic between both components and keeps the overhead small, at the cost of the information about active tracepoints being transmitted only irregularly to the PHP process.

You can configure the update interval with the following PHP setting.

tideways.dynamic_tracepoints.update_interval_seconds=120

This is a system level ini setting and the unit is denoted in seconds. In this example the update interval is increased to 120 seconds from the default 60 seconds. Remember to restart PHP web servers for changes to take effect.

Changing the Elevated Sample Rate

When a tracepoint matches in the PHP extension, the sample rate gets elevated to 100% and tracing and callgraph profilers get activated. In most cases this doesn’t matter, but sometimes this means the profiling overhead on your servers and for your customers increases too much. You can decrease the elevated sample rate with the following PHP.ini directive:

tideways.dynamic_tracepoints.elevated_sample_rate=50

This is a system level ini setting and the unit is denoted in full percentage points between 0 and 100.

Tracepoints and Sampling Explained

Both the daemon or the PHP extension sampling have an effect on which traces are collected for a tracepoint. This means tracepoints functionality is affected by PHP extension sampling.

Without activating dynamic tracepoints functionality in the PHP extension, and using the default sample rate of 25% it means only 1 in 4 requests will randomly be tested for matching an active tracepoint. This way there is a chance of 3 in 4 to loose out on an interesting trace that matches the tracepoint.
When dynamic tracepoints are enabled, the sample rate for the boosted transactions is elevated to 100% in the PHP extension. This increases the pool of potential traces to select from for the daemon. The sample rate increase only happens for requests for an endpoint/transaction with an active tracepoint. Other requests stay at the configured default sample rate.
The PHP extension can be configured to have a lower elevated sample rate, if you want to keep the overhead smaller.