PHP

Supported Versions

Supported PHP versions

The Tracing extension will work with all PHP versions starting from PHP 5.3 and up PHP 7.2 (32bit and 64bit), including ZTS (Zend Thread Safety) and non-ZTS builds of PHP. Capturing call stacks between spans is not supported on PHP 5.3.

The Tracing extension will work with 32bit and 64bit, as well as with ZTS (Zend Thread Safety) and non-ZTS builds of PHP. Capturing call stacks between spans is not supported on PHP 5.3. PHP must have been compiled with GCC or compatible compilers.

PHP on Windows systems or PHP compiled with muslc is currently not supported.

Supported SAPIs

  • PHP-FPM
  • PHP-CGI
  • Apache with mod_php
  • limited support for CLI

Sensor Data Collection

Tracked Configurations, Metrics, and Health Signatures for PHP depend on the utilized SAPI.

Like any other Instana sensors, PHP does not require any configuration, but will detect your installation automatically.

Tracked Configuration
PHP version
Server API
Zend Thread Safety
Loaded Modules
Main Ini file
Ini directory
Additional Ini files parsed
PHP extensions directory

PHP-FPM

In addition to the generally tracked configuration above, PHP-FPM will also include

Tracked Configuration Metrics
Master Process ID Connections
Master Configuration Processes
Worker Pools Resources

Health Signatures

  • Frequent Restarts
  • Connection Resets
  • Listen Backlog Config Mismatches
  • Too Many Pending Reads
  • Slow Requests
  • Latencies
  • Calls
  • Errors

Apache with mod_php

Supports tracing. The generally tracked configuration will be included in the Apache dashboard.


PHP-CGI

Support tracing. The generally tracked configuration will be included in the used webserver’s dashboard (if applicable).


CLI

Instana can provide tracing for CLI when the tracing extension is configured with the flag instana.enable_cli = 1. However, since CLI requests are usually ephemeral, Instana cannot connect them to the Dynamic Graph. This means, you will see the trace, but you won’t have any information about connected services or infrastructure.

Configuration

The PHP sensor is configured with sane defaults. It’s usually not necessary to modify these settings in the configuration.yml file of the Instana agent. The currently available settings are listed below:

#com.instana.plugin.php:
#  # Lightweight PHP Tracing. Requires the Instana Tracing extension. Enabled by default.
#  tracing:
#    # Enabling tracing will automatically download the Instana Tracing
#    # extension and enable it in your php.ini. If you are using preforked
#    # PHP workers, like PHP-FPM, you will need to restart them. Disabling
#    # tracing again will not remove the extension. It will only disable the
#    # tracing sensor.
#    enabled: true
#    # Whether to install the PHP Tracing extension. Default is true. Disabling 
#    # the installation will still create the TraceAcceptor daemon though.
#    installExtension: true
#    # The filename to use when querying Apache or PHP-CGI installations for
#    # environment data such as version, architecture, etc. By default, this
#    # is "instana." + Math.random(). + ".php". Uncommenting the setting
#    # below will force a static filename instead.
#    phpInfoFilename: instana.php
#    # Pins the PHP Tracing extension to download and install to a specific
#    # version. This can be used to rollback to previous versions of the
#    # extension or to test beta versions (when asked to do so). Expects
#    # the version to be given as major.minory.patch, e.g. 0.3.7
#    pinExtensionVersion: x.y.z
#    # The absolute path to the script to trigger whenever the sensor installed
#    # a different version of the PHP tracing extension than is currently
#    # installed. Works for upgrades and downgrades. Default is empty.
#    notificationScript: /path/to/restart_php.sh
#    # The number of executor threads to use for processing traces. This setting
#    # can be used to fine tune the PHP sensor for specific load environments.
#    # Defaults to the number of available logical processors or 8 (whichever is less).
#    # In general, you don't need to touch this setting unless advised to do so.
#    executorThreads: n
#    # The maximum number of traces the sensor is allowed to keep in the backlog
#    # for processing. Can be used in conjunction with executorThreads to fine tune
#    # the sensor for specific load environments. In general, you don't need to touch 
#    # this setting unless advised to do so. Defaults to 1000.
#    executorQueueLimit: 1000
#    # Port on which the sensor is listening for traces. Changing this setting will
#    # not automatically update any .ini files created for the PHP Tracing extension.
#    # In general, you don't need to touch this setting unless advised to do so. 
#    # Defaults to port 16816.
#    port: 16816
#    # Whether to remove values in SQL queries to prevent sensitive data from
#    # reaching our backend. This can help to improve agent performance in certain
#    # setups. In general, you don't need to touch this setting unless advised to do so.
#    sanitizeSql: true

See the section titled Automatic Restarts below for additional details on how to use notificationScript.

Enable PHP-FPM status page

In order to thoroughly monitor PHP-FPM metrics, you need to enable the status page. There are various instructions available to do so, for example: https://easyengine.io/tutorials/php/fpm-status-page/



Tracing

Instana instruments your PHP application at the PHP engine level, providing traces for selected function calls, in particular:

HTTP
cURL
fastcgi_finish_request
HTTP Streams
Sessions
Databases
AMQP
IBM DB2
Memcache
Memcached
MongoDB
Mysql
Mysqli
OCI8
PDO
Redis (via predis or PECL redis)
Other
Shell calls

The Instana Agent requires the PHP Tracing extension, which is automatically downloaded when the PHP sensor is enabled. The configuration is located at <agent_install_dir>/etc/instana/configuration.yml and the current version of the Instana Agent contains an example of the required configuration settings.

PHP tracing is active by default: Instructions to disable tracing

The PHP sensor is linked to a PHP SAPI sensor. This means tracing will only start when the Instana Agent detects a supported SAPI sensor (currently PHP-FPM, mod_php, and php-cgi).

The PHP sensor will gather information about the SAPI’s configuration and download an appropriate Instana extension based on your version of PHP and your host’s architecture. The PHP sensor will always download the latest version of the Instana extension. However, you can also pin/force a specific version via the configuration.yml


Required PHP extensions

  • JSON

Once the Instana Tracing extension is downloaded, it will place a zzz_instana.ini file either into your “Additional ini” directory, or add it to the ini file used by the PHP SAPI.

The sensor will attempt to do a graceful restart of your PHP environment to load the tracing extension into memory. See the section titled Automatic Restarts below for additional details.

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

Fine tuning the extension

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

  • instana.socket: 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.sample_rate: how often the sensor should collect trace information. Defaults to 100 (percent).
  • instana.log_level: what to log. 0 = off, 1 = ERROR, 2 = WARN, 3 = INFO, 4 = DEBUG. Defaults to 0 (off).
  • instana.enable_cli: whether to enable tracing for the CLI SAPI. 1 = on. 0 = off. Defaults to 0 (off).
  • instana.batch_threshold_us: the length and distance threshold in which batching of spans happens. Defaults to 10000.
  • instana.backtrace_limit: controls the depth of recorded call stacks. Defaults to 35 entries.
  • instana.span_chunk_size: the number of spans to keep in PHP’s memory before sending to the agent. Note that this directly affects batching, e.g. chunks of one effectively disable batching. Batching is disabled by default.
  • instana.enabled_frameworks: bitmask of userland framework you want to trace. Userland code tracing comes with a performance impact. Currently only Wordpress is supported. Set to 1 to enable. Disabled by default.
  • instana.disabled_instrumentation: bitmask of different instrumentations you want to disable. Note that there is no need to disable instrumentations for performance if your code does not make use of them.

Available flags:

  • 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

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

Please contact support if you need help with these settings.


Uninstalling the Instana PHP Tracing extension

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

Disabling the PHP Tracing sensor

Open <agent_install_dir>/etc/instana/configuration.yml with a text editor. There should be an entry like the following:

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

Change enabled: true to enabled: false. Note that tracing is enabled by default, so commenting this will not disable tracing.

As an alternative, you can also set installExtension: false to disable the installation of the PHP Tracing extension but keep the sensor listening for traces.

You need to restart the agent to apply the changes.

Note that disabling the sensor does not disable the tracing extension. Continue below if you also want to disable or fully remove the extension.

Disabling the PHP Tracing extension

When the PHP sensor installed the extension, it also enabled it for your PHP installation. This means it either placed a zzz_instana.ini 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. So for a php-fpm (note that your binary name may differ):

    $> 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 the example above, a file called zzz_instana.ini will be located in /etc/php/7.0/fpm/conf.d. If there is no “Additional Ini” files folder, or the zzz_instana.ini file does not exist at that location, check your php.iniinstead. In the example above, this would be /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.

Open the appropriate ini file in an editor and change the line: extension=/path/to/instana.so

to be prefixed with ”;” (this will comment out the line). ;extension=/path/to/instana.so

Alternatively, remove the line altogether (not recommended if you intend to enable the extension at a later point). If you have a zzz_instana.ini, you can also remove it completely:

$> sudo rm /etc/php/7.0/fpm/conf.d/zzz_instana.ini

Do not remove your entire php.ini file.

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

Note that disabling the extension does not remove it from your system. If you also want to remove the extension, continue below.

Removing the PHP Tracing extension

PHP will log startup errors when it cannot find an extension, so if you remove the extension you must also disable it (see above).

The PHP sensor will place the Instana PHP Tracing extension into the directory given in the extension_dir setting in your php.ini. To find out the setting, run the php binary for which you enabled tracing. So for a php-fpm (note that your binary name may differ):

$> 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 will only use the first value, so in the example above, 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.

$> 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 disabling the extension, you need to do so now for the changes to take effect.

Automatic Restarts

The PHP sensor will automatically download and install the appropriate PHP tracing extension for your PHP setup. In addition, the sensor will attempt a graceful 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 (read on).

You can change how the PHP sensor attempts to restart your PHP environment via 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 executed successfully, it will override the default mechanism for automatic restarts. Unlike the default mechanism, the script will get executed for any SAPI, so it can be used to automate restarts for PHP-CGI environments. If you want to disable automatic restarts completely, just configure an empty script.

The PHP sensor will set 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 is an example script that will log extension changes to a file and restart 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 above with:

docker exec $INSTANA_CONTAINER apachectl -k graceful;

For PHP-FPM, you can send a SIGUSR2 to gracefully restart it, e.g.

docker exec $INSTANA_CONTAINER kill -USR2 $INSTANA_PID_CONTAINER;

A graceful restart will load the PHP extension into memory without restarting the master process. So this will work even when the process runs as PID 1 inside the container. If you cannot or want not use the restart approach, you can also snapshot the running container instance, stop it and bring up 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 will use the container ID passed to the script to find the name of the container image. It will then commit the currently running container into a new image tagged with the new PHP extension version number. It will then stop the original container and start a container from the newly tagged image. While this will trigger the installation routine in the PHP sensor again, it will not trigger the notification script again, because the extension is already installed.

The above 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 you need to make automatic restarts work for your setup.

PHP SDK

The PHP Tracing extension comes with a minimal SDK that allows manual instrumentation of code. Spans created via this SDK will be injected into the automatically generated traces. The SDK also allows to record exceptions manually to complement Instana’s automatic recording of uncatched exceptions.

A typical usage example would be

$tracer = new Instana\Tracer(); 
$span = $tracer->createSpan('foo'); 
$span->annotate('function', 'doSomething');  
try {         
    doSomething(); 
} catch (\Exception $e) {      
    $tracer->logException($e);      
    $span->markError(); 
} finally {      
    $span->stop(); 
}

Note that removing the PHP Tracing extension will also require to remove any manually added SDK code. Otherwise, PHP will fail script execution due to missing functions.

OpenTracing

Instana provides a separate PHP SDK for tracing with OpenTracing. Unlike Instana’s own PHP instrumentation, using the OpenTracing SDK requires you to manually instrument your code. Traces generated via the PHP OpenTracing SDK will be separate from traces generated by Instana’s own tracing.