Tracepoints

Note: Tracepoints are currently in beta and require beta packages for tideways-php and tideways-daemon. Installation instructions

With tracepoints you can increase the amount of traces collected from selected endpoints and even elevate them to include callgraph information. They can be activated directly from the user interface by clicking "Boost Traces" buttons. This feature is activated in two steps in your project:

  1. Out of the box, tracepoints work for filtering traces on the daemon. Elevating to callgraph profiling or increasing the PHP sample rate is not possible with this configuration.

  2. With a few additional php.ini settings, callgraph profiling and sample rate elevation can be activated for a short amount of time by using tracepoints.

Configuration for Dynamic Tracepoints

To enable dynamic tracepoints the following steps are necessary:

  1. Update your Daemon and PHP Extension*

Dynamic tracepoints are available since tideways-daemon v1.6.0 and tideways-php v5.1.0 both released in February 2020. See the upgrading documentation for more information.

  1. Change the php.ini to set the following directives

tideways.dynamic_tracepoints.enable_web=1
tideways.dynamic_tracepoints.enable_cli=1
tideways.features.phpinfo=1

These three directives are system-level INI settings and cannot be configured through environment variables, directory overrides or directly via ini_set function.*
*

Note: Its recommended that you don’t enable this on all your production servers but only one or a subset of them, to avoid the overhead to affect all your servers. *
*

  1. Restart the PHP Webserver

    • 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:

  1. Don’t synchronize if INI settings for dynamic tracepoints are disabled (See basic configuration section above)

  2. Synchronize once when the PHP process (CLI, Apache or PHP-FPM) starts and before the first PHP script is handled.

  3. 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

Matching if a trace is elevated by a tracepoint can happen in the daemon or in the PHP extension. 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.

Tracepoints and Partial Callgraphs Explained

When you trigger a callgraph with a tracepoint, the profiler will be started during the request when the transaction is detected. Depending on your code and framework this usually happens a few milliseconds into the request, not immediately at the beginning. We call this a partial callgraph and there is a notification in the user interface when you look at a partial callgraph.

image

You can see exactly when the partial callgraph is started in the timeline view of a trace, where we show a horizontal line for the "tracepoint-start" event.

Still need help? Email [email protected]