Add Custom Timespans to Timeline

There are three APIs to collect additional timespans from your application to feed into the Timeline Profiler.

Explicitly create, start and stop timespans

Tideways collects a single root timespan for every request by default. These time spans are used to calculate the response time charts. You can add more spans to a trace that represent SQL, HTTP or any other kind of operation and see a full trace timeline inside the Tideways UI.

This is the code to create spans during PHP requests which you want to trace:


$span = \Tideways\Profiler::createSpan('sql');
$span->annotate(['title' => 'insert users']);

$pdo->query('INSERT INTO users (id, name) values (1, "foo")');


To avoid cluttering your codebase with Tideways Span code you should integrate this deep into your libraries and abstractions for database and HTTP clients.

Annotations are key/value pairs of additional information that we can display in the Tideways UI for each span.

Watching Function Calls

Sometimes you can’t or want to deeply integrate into a library. The Tideways extension offers a simple method to wrap spans around function calls by calling the method watch():


Watches are only triggered in Tracing mode of Tideways and not in monitoring mode.

Watching function calls with callback

If you have more special needs there is a more powerful function that allows creating spans using a PHP callback:


    function($context) {
        $span = \Tideways\Profiler::createSpan('view');

        $templateName = $context['object']->getTemplateName();
        $span->annotate(['title' => $templateName]);

        return $span;

The $context variable has the following keys:

  • $context['fn'] contains the string of the function being called, in the above example MyTemplateEngine::render.

  • $context['object'] is set to the current instance where the method is being called on.

  • $context['args'] contains a list of arguments passed to the called function.

Watches are only triggered in Tracing mode of Tideways and not in monitoring mode. Using a watch callback to set the transaction or service name is therefore not reliable.
Still need help? Email [email protected]