PHP tracing extension

Requirements

After the Instana PHP tracing extension is downloaded, the PHP sensor 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.

Do not modify zzz-instana.ini because the PHP sensor overwrites it during every installation based on the preferences in the Instana agent configuration.yaml file.

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

The PHP sensor generates reasonable defaults for most scenarios in zzz-instana.ini. However, you can adjust these settings to accommodate for highly specific needs. For more information, see Advanced customization.

Uninstalling the Instana PHP tracing extension

To uninstall the Instana PHP tracing extension, you need to first disable PHP sensor startup. Otherwise, it installs the extension again. Unlike installation, deinstallation is not automatic and requires further manual steps.

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

$> 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

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

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

Advanced customization

The PHP sensor frequently overwrites zzz-instana.ini, so do not make make changes to it. However, you can add an extra file (for example, zzz-instana-extras.ini). In containerized scenarios, this file can be mounted dynamically or made part of the image.

The following settings are available for all versions of PHP:

• instana.batch_threshold_us: The length and distance threshold in which batching of spans happens. The default value is 10000.
• instana.backtrace_limit: Controls the depth of recorded call stacks. The default or capped value is 25 entries.
• instana.disabled_instrumentation: Bitmask of instrumentations to disable. The default value is 0 (none).
• instana.disable_userland_tracing: Disables all tracing for nonnative extensions, for example, frameworks and other PHP userland code. The default value is 0 (off).
• instana.enable_cli: Enable or disable tracing for the CLI SAPI. 1 = on. 0 = off. The default value is 0 (off).
• 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.segfault_error_log: Capture or avoid a backtrace to PHP's error log-on segfaults. The default value is 0 (off).
• 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.

The following settings are exclusive to PHP 5:

• instana.socket: The address of the TCP socket of the Instana PHP sensor. The socket address is determined during installation and defaults to tcp://127.0.0.1:16816.

The following settings are exclusive to PHP 7.0 and later:

• instana.buffer_hard_limit: The maximum number of spans to be kept in the buffer if the agent becomes unresponsive. Spans starting from the oldest are dropped until the buffer is contained within this limit. The default value is 1000.
• instana.buffer_maximum_delay_ms: The maximum interval between subsequent clearance of a span buffer. The default value is 1000 ms.
• instana.buffer_soft_limit: The maximum number of spans to be buffered before a span buffer is cleared. The default value is 500.

PHP Tracer offers various environment variables that take precedence over zzz-instana.ini.

The following bit flags are available for instana.disabled_instrumentation:

• 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 configurable by name. You must use their numeric values to disable an instrumentation.

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

Automatic restarts

The PHP sensor automatically downloads and installs the appropriate PHP tracing extension for your PHP setup. In addition, the sensor attempts a restart of your PHP environment to load the extension into memory. Automatic restarts are currently supported for Apache and PHP-FPM. PHP-CGI environments need manual or scripted handling.

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. If you cannot or do not want to use the restart approach, you can also create a snapshot of 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.

Troubleshooting