Monitoring PHP

Caveats

PHP on Windows systems is currently not supported.

Currently, Apache HTTP server that is configured to serve PHP content with threaded MPM "worker" or "event" and PHP ZTS are not supported.

PHP-FPM

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

Health Signatures

For each sensor, there is a curated knowledgebase of health signatures that are evaluated continuously against the incoming metrics and are used to raise issues or incidents depending on user impact.

Built-in events trigger issues or incidents based on failing health signatures on entities, and custom events trigger issues or incidents based on the thresholds of an individual metric of any given entity.

For information about built-events for PHP-FPM, see the Built-in events reference.

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. Also, the tracing extension needs to installed manually. Please contact support if you need support with setting up CLI tracing.

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 as follows 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.ini instead. 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 as follows.

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.

Installing the SDK

The stubs of the PHP SDK can be installed via Composer with the follwing command:

composer require instana/instana-php-sdk

The stubs ensure that, when the PHP process is not monitored with Instana, all calls to the SDK APIs result in a no-op, rather than errors.

Stubs of the PHP SDK to be used with your IDE are available on Packagist.

Example of SDK Usage

A typical usage example would be

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

Create custom ENTRY and EXIT spans

Using PHP Tracing extension you are allowed to create custom spans of ENTRY or EXIT type.

// get the tracer
$tracer = new \Instana\Tracer();

$entry_span = $tracer->createSpan('entry', \Instana\SPAN_ENTRY);

$exit_span = $tracer->createSpan('exit', \Instana\SPAN_EXIT);

Setting parent span

When creating new span with PHP SDK it's possible to set the ID of parent span which can be useful in case of continuation traces created by other system. The relevant code snippet should look like:

// get the tracer
$tracer = new \Instana\Tracer();

$span = $tracer->createSpan('entry', \Instana\SPAN_INTERMEDIATE, $parentId);

Trace Continuation

The PHP Tracing extension allows continuing traces through messaging systems. To do so, you need to inject the trace context of the publisher into the message and extract it on the consumer side.

// get the tracer
$tracer = new \Instana\Tracer();

// GENERIC: an artificial message you want to send to your queue
$message = ['task' => 'convert-image'];

// retrieve the current trace context
$context = $tracer->getActiveContext();

// GENERIC: inject the current active context into your message, so you can retrieve it in the worker later
$attributes = $message['X-INSTANA-S'] = $context->getSpanId();
$attributes = $message['X-INSTANA-T'] = $context->getTraceId();

// send your message to the queue
$queue->publish($message);

// get the tracer
$tracer = new \Instana\Tracer();

// GENERIC: pull your message from the queue
$message = $queue->pull();

// GENERIC: extract trace context so we can continue the trace, assumes it's always present
$messageContext = new \Instana\TraceContext($message['X-INSTANA-T'], $message['X-INSTANA-S']);

// continue the trace that published the message
$tracer->continueTrace($messageContext);

// OPTIONAL: Create a span to wrap the unit of work
$span = $tracer->createSpan('work');
$span->annotate('job', 'my-important-job');

// do the actual work

// stop the optional span started above
$span->stop();

Google Cloud Pub/Sub

The PHP Tracing extension will automatically create EXIT spans for outgoing interactions with Google Cloud Pub/Sub.

For trace continuation, you will need to manually wrap the code that consumes the Pub/Sub messages.

use Google\Cloud\PubSub\PubSubClient;

$tracer = new \Instana\Tracer();

$pubSub = new PubSubClient([
    'projectId' => $myProjectname
]);

$topic = $pubSub->topic($myTopicName);
$subscription = $pubSub->subscription($mySubscriptionName, $myTopicName);

$messages = $subscription->pull();
foreach ($messages as $message) {
    $attributes = $message->attributes();

    // extract the trace continouation headers from your message, assumes it's always present
    $messageContext = new \Instana\TraceContext($attributes['x-instana-t'], $attributes['x-instana-s']);

    // continue the trace that published the message
    $tracer->continueTrace($messageContext);

    // convert the current span
    $span = $tracer->getEntrySpan();
    $span->asGCPubSubReceive($project, 'php-consumer');

    // OPTIONAL: Create a span to wrap the unit of work
    $span = $tracer->createSpan('work');
    $span->annotate('job', 'my-important-job');

    // do the actual work

    // stop the optional span started above
    $span->stop();

    $subscription->acknowledge($message);
}

Removing the SDK

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.