Update From PHP Extension V4 to V5

The new PHP extension v5 is mostly free of BC breaks, but there have been some changes that the new extension now ignores and where you need to make small adjustments:

If you don’t use the Tideways\Profiler API in your application and rely completely on auto-instrumentation, then the BC breaks will not affect you.

  1. Callbacks passed to \Tideways\Profiler::watchCallback() must now return the \Tideways\Profiler\Span object and not the ID anymore. Returning the ID will trigger a notice

Before:

<?php

\Tideways\Profiler::watchCallback('My\Class::run', function ($context) {
    $span = \Tideways\Profiler::createSpan('php');
    return $span->getId();
});

After:

<?php

\Tideways\Profiler::watchCallback('My\Class::run', function ($context) {
     $span = \Tideways\Profiler::createSpan('php');
     return $span;
});

  1. Registration of callbacks with watch() and watchCallback() only works when profiler is started

Previously you could register callbacks with watch() and watchCallback() before the Tideways Profiler was started. This doesn’t work anymore, callbacks must be registered after Tideways is started. In a web request with auto starting Profiler this has no effect, but if you are registering instrumentation in CLI or worker scripts that call Tideways\Profiler::start() then this is important.

In addition both watch() and watchCallback() only work for userland functions for now.

  1. The tideways.framework INI setting does not allow setting function names anymore, only the framework names from the pre-defined list.

Previously you could set arbitrary function or class+function pairs as frameworks, which the old extension would use for instrumentation by looking at the first argument when this function is called and use it as transaction name. This functionality doesn’t work anymore. It was mainly used for customized frameworks, such as Symfony with JMS DIExtraBundle, which the new extension now supports automatically. If you are using this functionality for a currently unsupported framework, then transaction naming will stop working on v5. Instead please use \Tideways\Profiler::detectTransactionFunction($function) when the Profiler is started to register arbitrary functions as transaction name decider.

  1. Deprecated functions

The following functions are deprecated and were turned into no-ops:

  • \Tideways\Profiler::useRequestAsTransactionName();

  • \Tideways\Profiler::guessOperationName();

  • \Tideways\Profiler::log();

  • \Tideways\Profiler::detectFramework();

  • \Tideways\Profiler::detectFrameworkTransaction();

    1. Ignore second argument to \Tideways\Profiler::start and startDevelopment

Previously with very old versions of Tideways\Profiler::start() it was possible to pass the api key as string for the first and then options as second argument. This doesn’t work anymore, you must pass options as a first argument to set them, or only the API key. The second argument is ignored in both functions.

  1. Enabled CLI monitoring by default

With the old extension, CLI monitoring and exception tracking was only enabled when you configured the INI setting tideways.monitor_cli=1. We have now changed this to automatically start CLI monitoring and exception tracking with Tideways. Triggering Timeline and Callgraph traces works by using the tideways CLI command. The only thing that is not enabled by default is tracing based on the configured sample rate. This can be achieved by configuring tideways.enable_cli=1. To prevent Tideways to consume a lot of memory for instrumentation when executing long running scripts we have added a feature that disables tracing with Tideways when 90% of the available memory of the script is reached. This should make it possible to always get data even from the longest running and most memory intensive CLI scripts.

To disable monitoring on the CLI, make sure that the CLI scripts are executed with a tideways.api_key by only setting it for web based SAPIs.

Still need help? Email [email protected]