PHP tracing extension

Required PHP extensions

To run PHP Tracer, you must have the JSON extension.

After the Instana tracing extension is downloaded, the extension places a zzz-instana.ini file either into your Additional ini directory, or adds the file to the ini file used by the PHP SAPI.

Then, the sensor attempts to restart your PHP environment to load the tracing extension into memory. For more information, see Automatic restarts.

In addition, if you are using Plesk, you need to run plesk bin php_handler --reread.

Customizing PHP extension settings

The PHP tracing extension comes with same defaults for most tracing scenarios in zzz-instana.ini. However, you can adjust settings to accommodate specific needs, such as sampling, batching, or chunking.

The PHP sensor does not overwrite the zzz-instana.ini if the tracing extension is loaded into the PHP environment. So while you can safely add extra settings in the extension, adding extra settings can be inconvenient in containerized setups. A good practice in such scenarios is to add an extra file zzz-instana-extras.ini and make that part of the container deployment.

The following settings are available:

• instana.socket: The address of the Instana PHP Sensor's TCP socket. The socket address is determined during installation and defaults to tcp://127.0.0.1:16816.
• instana.log_level: The level to log: 0 = off, 1 = ERROR, 2 = WARN, 3 = INFO, and 4 = DEBUG. The default value is 0 (off).
• instana.enable_cli: This setting enables or disables tracing for the CLI SAPI. 1 = on. 0 = off. The default value is 0 (off).
• instana.batch_threshold_us: The length and distance threshold in which batching of spans happens. The default value is 10000.
• instana.backtrace_limit: This setting controls the depth of recorded call stacks. The default or capped value is 25 entries.
• instana.span_chunk_size: The number of spans to keep in PHP's memory before they are sent to the agent. This number directly affects batching. For example, chunks of one effectively disable batching.
• instana.disable_userland_tracing: This setting disables all tracing for nonnative extensions, for example, frameworks and other PHP userland code. The default value is 0 (off).
• instana.segfault_error_log: This setting captures or avoids a backtrace to PHP's error log-on segfaults. The default value is 0 (off).
• instana.disabled_instrumentation: This setting displays the bitmask of instrumentations to disable. The default value is 0 (none).

Available flags

The following flags are available:

• STREAMS 1
• PHP 2
• PDO 4
• CURL 8
• REDIS 16
• MONGODB 32
• MYSQL 64
• MEMCACHE 128
• Db2 256
• OCI 512
• SHELL 1024
• PECL_HTTP 2048
• REQUEST_HEADERS 4096
• RESPONSE_HEADERS 8192
• SOAP 16384
• WORDPRESS 32768
• AMQP 65536 (applies to both pecl-amqp and php-amqp-lib)
• ELASTICSEARCH 131072
• EXCEPTIONS 262144
• LOGGERS 524288
• COUCHBASE 1048576
• TWIG 2097152
• SYMFONY 4194304
• KOHANA 134217728
• GOOGLE_PUBSUB 268435456

The flags are not displayed by name. You must use their numeric values to disable an instrumentation.

If you need help with these settings, contact IBM support.

Disabling the PHP tracing sensor

To disable the PHP tracing sensor, complete the following steps:

1. Open <agent_install_dir>/etc/instana/configuration.yml with a text editor. The following entry is displayed:

com.instana.plugin.php:
  tracing:
    enabled: true

2. Change enabled: true to enabled: false. Because tracing is enabled by default, so commenting false does not disable tracing.

Alternatively, you can also set installExtension: false to disable the installation of the PHP tracing extension but keep the sensor receptive for traces.

You need to restart the agent to apply the changes.

Note: Disabling the sensor does not disable the tracing extension.

Disabling the PHP tracing extension

When the PHP sensor installed the extension, it also enabled the extension for your PHP installation. Enabling the extension means that the PHP sensor either placed the zzz-instana.ini file into your Additional Ini files folder, or enabled it directly in your php.ini.

To find out where it was enabled, run the PHP binary for which you enabled tracing. The following example shows the PHP binary for a PHP-FPM:

    $> php-fpm7.0 -i | egrep "^(Scan|Loaded)"
    Loaded Configuration File => /etc/php/7.0/fpm/php.ini
    Scan this dir for additional .ini files => /etc/php/7.0/fpm/conf.d

In this example, the zzz-instana.ini file is located in /etc/php/7.0/fpm/conf.d. If no Additional Ini file folder is available, or the zzz-instana.ini file does not exist at that location, check your php.ini instead. In this example, the file is in /etc/php/7.0/fpm/php.ini.

Note: For Apache with mod_php, put a PHP file with the content <?php phpinfo(); into a web accessible location on Apache and open it in a browser for the same information.

To disable the PHP tracing extension, complete the following steps:

1. Open the appropriate ini file in an editor and prefix the semicolon (;) in the line extension=/path/to/instana.so as follows. Adding semicolon comments out the line.

   ;extension=/path/to/instana.so

   Alternatively, remove the line extension=/path/to/instana.so altogether.
   Note: If you intend to enable the extension at a later point, do not remove it.

2. If you have the zzz-instana.ini file, you can also remove the file completely as follows:

   $> sudo rm /etc/php/7.0/fpm/conf.d/zzz-instana.ini
   

   Important: Do not remove your entire php.ini file.

3. If you are using pre-forked workers, you need to restart the PHP master process now. Otherwise, the extension remains active in memory.

Note: Disabling the extension does not remove it from your system.

Removing the PHP tracing extension

PHP logs startup errors when it cannot find an extension, so before you remove the extension, you must also disable it. For more information, see Disabling the PHP tracing extension.

The PHP sensor places the Instana PHP tracing extension into the directory that is given in the extension_dir setting in your php.ini. To find out the setting, run the PHP binary for which you enabled tracing. The following example shows the PHP binary for a PHP-FPM:

$> php-fpm7.0 -i | egrep ^extension_dir
extension_dir => /usr/lib/php/20151012 => /usr/lib/php/ext

Note: For Apache with mod_php, put a PHP file with the content <?php phpinfo(); into a web accessible location on Apache and open it in a browser for the same information.

The PHP sensor uses only the first value, so in the example, you can find the extension at/usr/lib/php/20151012. The path to the extension is also given in your php.ini or the instana.ini.

To remove the extension, run the following command:

$> sudo rm /usr/lib/php/20151012/instana.so

If you are using pre-forked workers and did not already restart your PHP master process when you disabled the extension, you need to restart now for the changes to take effect.

Customizing restarts by using notification script

You can change how the PHP sensor attempts to restart your PHP environment through the notificationScript configuration setting. The setting takes an absolute path to an executable shell script. This script gets triggered whenever the currently installed tracing extension is a different version than the agent installed.

When this script is configured and run successfully, it overrides the default mechanism for automatic restarts. Unlike the default mechanism, the script gets executed for any SAPI, so it can be used to automate restarts for PHP-CGI environments. If you want to disable automatic restarts completely, configure an empty script.

The PHP sensor sets the following environment variables for the script execution:

INSTANA_EXT_VERSION_OLD = the version of the tracing extension currently in memory
INSTANA_EXT_VERSION_NEW = the version of the tracing extension after a restart
INSTANA_PID_HOST = the PID of the process on the host, e.g. your Apache, PHP-FPM or PHP-CGI
INSTANA_PID_CONTAINER = the PID the host process has in a container (if applicable)
INSTANA_CONTAINER = the ID/name of the container the process is running in (if applicable)

The following example shows a script that logs extension changes to a file and restarts Apache:

    #!/bin/bash
    echo "Found new tracing extension." >> php_update.log;
    echo "INSTANA_EXT_VERSION_OLD=$INSTANA_EXT_VERSION_OLD" >> php_update.log;
    echo "INSTANA_EXT_VERSION_NEW=$INSTANA_EXT_VERSION_NEW" >> php_update.log;
    echo "INSTANA_PID_HOST=$INSTANA_PID_HOST" >> php_update.log;
    echo "INSTANA_PID_CONTAINER=$INSTANA_PID_CONTAINER" >> php_update.log;
    echo "INSTANA_CONTAINER=$INSTANA_CONTAINER" >> php_update.log;
    echo "restarting apache" >> php_update.log;
    apachectl -k graceful >> php_update.log;

If your Apache runs inside a container, replace the last line in the sample script with the following line:

docker exec $INSTANA_CONTAINER apachectl -k graceful;

For PHP-FPM, you can send a SIGUSR2 to gracefully restart it as shown in the following example:

docker exec $INSTANA_CONTAINER kill -USR2 $INSTANA_PID_CONTAINER;

A graceful restart loads the PHP extension into memory without restarting the master process. So this loading works even when the process runs as PID 1 inside the container.

Alternative approach

If you cannot or do not want to use the restart approach, you can also snapshot the running container instance, stop it, and open a new instance easily:

    #!/bin/bash
    IMAGE_HASH=$(docker inspect --format='{{.Config.Image}}' $INSTANA_CONTAINER)
    IMAGE_NAME=$(docker images | grep $IMAGE_HASH | awk '{print $1}')
    IMAGE_TAG="instana-php-$INSTANA_EXT_VERSION_NEW"
    docker commit $INSTANA_CONTAINER $IMAGE_NAME:$IMAGE_TAG &&
    docker stop $INSTANA_CONTAINER &&
    docker run -d --rm $IMAGE_NAME:$IMAGE_TAG

This action uses the container ID passed to the script to find the name of the container image. It then commits the currently running container into a new image that is tagged with the new PHP extension version number. It then stops the original container and starts a container from the newly tagged image. While this action triggers the installation routine in the PHP sensor again, it does not trigger the notification script again because the extension is already installed.

These examples assume you are using Docker as your container engine. But since the triggered shell script is completely under your control, you can put any logic that you need to make automatic restarts work for your setup.