How to Enable CLI tracing – Instana

Installation (easy route)

The by far easiest way to install the extension for CLI is to add an FPM to this server which runs the very same PHP version as the PHP CLI SAPI. Then start the Instana agent on the host and let it do the automatic install. Once it's done with that, leave everything up and running (do not uninstall the FPM) and go to the extension folder of the CLI SAPI. Symlink the instana.so from the FPM's extension folder into it. Then go the Additional Ini Files folder of the FPM and copy the zzz-instana.ini to the Additional Ini Files folder of the CLI SAPI. Open the ini file, adjust the path to the extension to point to the symlinked instana.so and add instana.enable_cli=1 to the file. Now when you invoke any PHP CLI scripts, they should be traced.

Why you should choose this approach

While this approach requires you to add an unused FPM, it will make sure that you a) always have a PHP Daemon running in the agent accepting PHP traces and b) an up-to-date instana.so, because the PHP sensor will update the FPM's instana.so when it has a new version. You are using the static agent, so that means it will only update when you update the static agent. But it's still better than having to maintain the PHP CLI extension completely manually in my opinion.

Alternative (hard route)

If you don't want to install an FPM for this, you will need to tell me which PHP version the CLI SAPI is using, incl. if 32bit or 64bit and whether it's ZTS or not. I'll send you the appropriate extension then.
Install the extension just like you would install any other PHP extension, i.e. put it into the extension dir and create an ini file for it. We name the ini file zzz-instana.ini so it gets loaded last.
The ini file needs to contain the following:

extension=/path/to/extension_dir/instana.so
instana.enable_cli=1
instana.socket=x.x.x.x:16816

You will need to replace the x.x.x.x with the IP of an agent running the PHP sensor, e.g. pick the IP of a server running an Apache with PHP or an FPM and the Instana agent. The traces are sent via tcp.

General Caveats

Note that for PHP CLI tracing, we are unable to attach the trace to any underlying infrastructure. This is because PHP CLI processes are usually ephemeral and we ignore them in the PHP sensor. That's also why PHP CLI processes do not trigger the automatic installation of the PHP tracing extension or spawning of the PHP Trace Acceptor Daemon.

Comments