Monitoring PHP

Instana offers comprehensive monitoring of your PHP application environment, providing end-to-end visibility into your system. After you install the Instana host agent, the agent automatically deploys the PHP sensor and tracer in your PHP environment. You can view infrastructure metrics and end-to-end traces of all requests in your PHP environment in the Instana UI.

Supported versions

Supported operating system

The PHP sensor is supported only on Linux operating systems. For more information about this support, refer to the table at Supported PHP versions.

Supported PHP versions

PHP version CPU architecture C standard library Zend Thread Safety (ZTS) Support type
PHP 7.2 - PHP 8.3 aarch64 glibc 2.17+, musl NTS, ZTS General availability
PHP 5.3 - PHP 8.3 x86-64 glibc 2.12+, musl NTS, ZTS General availability

Supported PHP SAPIs

Instana supports the following PHP Server Application Programming Interface (SAPIs) for configuration data, metrics, and tracing:

SAPI Support type
Apache2 with mod_php General availability
CLI Experimental
PHP-CGI General availability
PHP-FPM General availability

Instana can provide tracing for CLI if you configure the tracing extension with the flag instana.enable_cli = 1. However, because CLI requests are usually of short duration, Instana cannot connect them to the Dynamic Graph. Therefore, you can see the trace, but you cannot obtain any information about the connected services or infrastructure. Also, you must install the tracing extension. For support with setting up CLI tracing, contact IBM support.

Limitations

Instana doesn't support the following PHP configurations:

  • Using PHP on Windows systems
  • Using Apache HTTP Server that is configured to serve PHP content with threaded MPM "worker" or "event" and PHP ZTS
  • Using multiple tracing tools like Instana and a third-party tracer, for example, New Relic, Otel, Dynatrace, or Datadog, simultaneously with PHP

Configuring PHP sensors

After you install the Instana agent, the PHP sensor is automatically installed and configured with reasonable defaults. Usually, you don't need to modify these settings in the Instana agent's configuration.yaml file: <agent_install_dir>/etc/instana/configuration.yaml.

The following YAML snippet shows the available settings:

# PHP Tracing
#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
#    # as follows 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

Enabling automatic restarts

You can change how the PHP sensor attempts to restart your PHP environment through the notificationScript configuration setting. For more information about how to use the notificationScript setting, see the Automatic restarts section.

Enabling PHP-FPM status page

To thoroughly monitor PHP-FPM metrics, you need to enable the status page. To enable the page, open the worker pool configuration file and add the entry pm.status_path = /status. The Instana PHP-FPM sensor directly accesses the endpoint for accessing the PHP-FPM status page through FastCGI.

Enabling Apache

The Apache configuration must contain the following line:

SetHandler application/x-httpd-php

Without the line, the sensor fails to load and the following error message is logged:

> "PHP Sensor is failing because of "NO Version found"

Viewing metrics

To view metrics for PHP, complete the following steps:

  1. In the sidebar of the Instana UI, select Infrastructure.
  2. Click a specific monitored host.

You can see a host dashboard with all the collected metrics and monitored processes.

Like any other Instana sensor, the PHP sensor does not need any configuration. It automatically detects your PHP installation and collects the following data from the installation:

For PHP, the configuration data, performance metrics, and the health signatures depend on the SAPI used. For more information, see Supported PHP SAPIs.

Configuration data and metrics

The following table lists the generally tracked configuration data:

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

The generally tracked configuration for Apache with mod_php is included in the Apache dashboard. For PHP-CGI, this configuration data is included in the used webserver's dashboard (if applicable).

In addition to the generally tracked configuration, the PHP-FPM dashboard includes the following configuration data:

  • Master Process ID
  • Master Configuration
  • Worker Pools

PHP-FPM dashboard also includes the following metrics:

  • Connections
  • Processes
  • Resources

Health signatures

Each sensor has a curated knowledge base of health signatures that are evaluated continuously against the incoming metrics. These health signatures are used to raise issues or incidents that depend 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 specific entity.

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

Tracing

Instana provides both automatic and manual instrumentation for PHP.

Automatic instrumentation

Instana automatically instruments your PHP applications. To instruments your PHP applications, the Instana agent requires the PHP tracing extension.

PHP tracing extension

The PHP tracing extension is automatically downloaded when the PHP sensor is enabled. The configuration is at <agent_install_dir>/etc/instana/configuration.yaml and the current version of the Instana agent contains an example of the required configuration settings.

PHP tracing is active by default. For more information about disabling tracing, see Disabling the PHP tracing sensor. The PHP sensor is linked to a PHP SAPI sensor. So tracing starts only when the Instana agent detects a supported SAPI sensor (currently PHP-FPM, mod_php, and php-cgi). For more information, see Supported PHP SAPI sensors.

The PHP sensor gathers information about the SAPI's configuration and downloads an appropriate Instana extension based on your version of PHP and your host's architecture. The PHP sensor always downloads the most recent version of the Instana extension. However, you can also pin (force) a specific version by setting pinExtensionVersion: x.y.z in the configuration.yaml file.

For more information about PHP tracing extension and the following settings, see PHP tracing extension:

  • Required PHP extensions
  • Customizing PHP extension settings
  • Available flags
  • Uninstalling the Instana PHP tracing extension
  • Automatic restarts

Traces

Instana instruments your PHP application at the PHP engine level and provides the following traces for selected function calls:

  • HTTP

    • cURL
    • fastcgi_finish_request
    • HTTP Streams
    • Sessions

  • Frameworks

    • Wordpress
    • Laravel
    • Symfony
    • Zend Framework

  • Databases

    • AMQP (pecl-amqp) -AMQP (php-amqp-lib)
    • Cassandra
    • Couchbase
    • Elasticsearch
    • Google Cloud Pub/Sub
    • IBM Db2
    • LDAP
    • Memcache
    • Memcached
    • MongoDB
    • Mysql
    • Mysqli
    • OCI8
    • CUBRID (PDO)
    • MS SQL Server (PDO)
    • Firebird (PDO)
    • IBM (PDO)
    • Informix (PDO)
    • MySQL (PDO)
    • MS SQL Server (PDO)
    • Oracle (PDO)
    • ODBC and Db2 (PDO)
    • PostgreSQL (PDO)
    • SQLite (PDO)
    • PostgreSQL (PDO, not ext-pgsql)
    • Redis (via predis or PECL redis)

  • Logging

    • Drupal logger
    • Kohana logger
    • Magento logger
    • Monolog
    • Yii logger
    • Zend_Log

  • Templating

    • Twig
    • Blade

  • Other

    • Shell calls
    • Compile time
    • OpCache metrics

Stack traces in span details are only supported by PHP 5.4 and later versions.

Manual instrumentation

You can also manually instrument your PHP code through tracing SDKs. By using tracing SDKs, you can add tracing data to the traces automatically collected by Instana.

PHP-SDK

The PHP tracing extension comes with a minimal SDK. By using this SDK, you can manually instrument your code. For more information, see PHP-SDK.

Integrating with OpenTracing

Instana provides a separate PHP SDK for tracing with OpenTracing. Unlike Instana's own PHP instrumentation, the OpenTracing SDK requires you to manually instrument your code. Traces that are generated through the PHP OpenTracing SDK are separate from traces that are generated by Instana's own tracing.

Profiling (technology preview)

PHP profiler supports CPU usage profile type.

Profiling is available only for applications that run on Linux-based operating systems and supports only non-ZTS variations of PHP. For more information about enabling it, see Configuring profiling.