Instrument CLI Scripts
This docs page explains how to enable instrumentation of PHP CLI scripts, for example Cron jobs, daemons or worker scripts.
Until Tideways PHP Extension 5.7.0 you had to set the INI setting tideways.enable_cli=1 to enable the Profiler to collect data on the CLI. This setting is enabled by default now.
|
Instrumenting Long-Running Cronjobs
When cronjobs run longer for a tideways.traces_max_seconds (default 60
seconds) then Tideways disables the collection of addtional spans for the
Timeline Profiler.
This is done to allow the Timeline view to stay useable, as for very long scripts it becomes very hard to navigate and use it.
You can increase the INI setting if you need to collect information for longer than the default 60 seconds.
With INI-setting tideways.enable_cli=0 you can disable collection of traces
on the CLI if you do not want traces from the CLI to be collected.
Instrumenting Long-Running Scripts (Daemons, Worker)
You should only instrument long running scripts with Tideways, when they perform subtasks similar to requests in a sequence, one at a time.
| Tideways will not work as expected if you have multiple tasks/requests running at the same time, for example when using React-PHP or Fibers. |
Long running use-cases that work with Tideways:
-
A Gearman/Beanstalk/RabbitMQ/Redis worker that executes a single task at a time.
-
A PHP based webserver that executes a single request at a time, for example RoadRunner or Octane.
If you have such a worker, instrumentation requires you to call start() and stop() around the execution of each individual task or job.
This requires extending your PHP code that is responsible for the infinite loop, fetching the next task from the queue and executing it.
A simple example:
<?php
while ($task = next_queue_item()) {
// $task is an instance of a specific Task object here.
if (class_exists('Tideways\Profiler')) {
\Tideways\Profiler::start(array(
'api_key' => 'key here',
'sample_rate' => 20,
'service' => 'worker',
));
\Tideways\Profiler::setTransactionName(get_class($task));
}
try {
$task->execute();
} catch (\Throwable $e) {
if (class_exists('Tideways\Profiler')) {
\Tideways\Profiler::logException($e);
}
} finally {
if (class_exists('Tideways\Profiler')) {
\Tideways\Profiler::stop();
}
}
}