Instrument CLI Scripts

This doc page explains how to enable instrumentation of PHP CLI scripts, for example, cronjobs, daemons, or worker scripts.

Instrumenting Scripts Running Individual Tasks (Queue Workers, Message Handlers)

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 RabbitMQ, Redis, SQS or other queue workers that execute a single task at a time.

  • A PHP-based webserver that executes a single request at a time, for example FrankenPHP, RoadRunner or Laravel Octane.

If you have such a worker, instrumentation requires you to call Profiler::start() and Profiler::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.

Automatic instrumentation

Tideways automatically splits scripts using supported background queue and worker implementations.

So if you’re using one of the following queues or workers, no further action is needed.

  • Symfony Messenger

  • Laravel Jobs

  • Shopware Background Queue

  • Magento Task Queue

You can turn this behavior off using tideways.features.worker_mode=0 in your PHP.ini.

Also see Supported Frameworks and Databases page for a complete list of our automatic instrumentation.

Manual instrumentation

If no supported framework is used you can work off of this simple example for manual instrumentation:

<?php

while ($task = next_queue_item()) {
    // $task is an instance of a specific Task object here.
    if (class_exists('Tideways\Profiler')) {
        \Tideways\Profiler::start([
            '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();
        }
    }
}

Instrumenting Other Long-Running Scripts (Cronjobs, etc.)

When scripts run longer for a tideways.traces_max_seconds (default 60 seconds), then Tideways disables the collection of additional spans for the Timeline Profiler.

This is done to allow the Timeline view to stay usable, 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.

Still need help? Email [email protected]