Monitoring PHP

The PHP sensor is installed with reasonable defaults for PHP tracing to work automatically when the Instana agent is installed. However, you can configure the sensor through the com.instana.plugin.php section in the agent configuration.yaml file to customize it to work with your PHP runtime.

The following YAML snippet from the agent configuration.yaml file shows the available settings for configuring the PHP sensor:

# PHP Tracing
#com.instana.plugin.php:
#  # Lightweight PHP Tracing. Enabled (true) by default.
#  # PHP tracing is performed by the Instana PHP Tracing extension.
#  tracing:
#    # Enabling tracing (true) will automatically download the Instana PHP Tracing extension
#    # and enable it in the PHP INI configuration.
#    # The PHP runtime will be gracefully restarted if managed by PHP-FPM or Apache
#    # and the extension will be loaded into the PHP runtime. The following PHP runtimes
#    # require a manual restart for the PHP Tracing extension to be loaded into memory:
#    #  - long-running PHP-CGI processes i.e., CGI SAPI
#    #  - pre-forked PHP worker processes
#    #
#    # Disabling tracing (false) will automatically disable the Instana Tracing extension
#    # in the PHP INI configuration. The PHP runtime will be gracefully restarted to
#    # unload the extension from the PHP runtime memory if applicable (see above).
#    # Otherwise, you need to manually restart your PHP runtime to unload the extension.
#    # Disabling tracing implicitly disables profiling.
#    # You can automate the restarts by configuring a custom script. See 'notificationScript'.
#    enabled: true
#    # Whether to install the Instana PHP Tracing extension. Default is true.
#    # When set to false, the Instana PHP Tracing extension will not be enabled in newly
#    # detected PHP runtimes. This setting does not affect the PHP runtimes where
#    # the Instana PHP Tracing extension is already enabled.
#    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
#    # Pin the Instana PHP Tracing extension 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). The version should be provided
#    # in the format major.minory.patch, e.g. 5.1.0
#    # The pinned extension version is automatically installed in the PHP runtime.
#    # See the desciption of 'enabled' flag to know if you need to manually restart
#    # your PHP runtime after pinning the extension version.
#    pinExtensionVersion: x.y.z
#    # The absolute path to an executable shell script (Linux) or powershell script (Windows)
#    # that is to be automatically executed when enabling tracing, pinning extension version
#    # or disabling tracing. You must design this script to restart your PHP runtime so that
#    # the changes made to your PHP INI configuration by the agent are loaded.
#    # Default value is empty.
#    notificationScript: <absolute_path_to_script>
#    # 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
 

After you install the Instana agent, the PHP-FPM sensor is automatically installed and configured with defaults.

The following YAML snippet shows the available settings:

#PHP-FPM monitoring
 #com.instana.plugin.phpfpm:
 #  # Enabled (true) by default. Update it to 'false' to disable PHP-FPM discovery and sensor.
 #  enabled: true
 #  monitoring:
 #    # Enabling PHP-FPM worker pool monitoring collects worker pool process metrics like CPU and memory
 #    # usage every second. Enabled (true) by default.
 #    workerPoolMonitoring: true 
 

The PHP-FPM sensor monitors FPM worker pools by default. This monitoring might prevent worker processes from terminating due to the sensor sending automatic status check CGI requests in the background. To avoid this behavior, you can disable worker pool monitoring by setting the workerPoolMonitoring option in the PHP-FPM sensor plugin configuration to false.

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:

• Configuration data
• Performance metrics
• Health signatures

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

Instana provides both automatic and manual instrumentation for PHP.

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.

Instana supports OpenTelemetry instrumentation for PHP applications. The OpenTelemetry PHP extension has automatic instrumentation capability (also called zero-code instrumentation) that generates traces and exports them to configured endpoints, such as the OpenTelemetry Collector and the backend.

To bring these spans into Instana, you can use one of the following exporters:

• The default OpenTelemetry Protocol (OTLP) exporter: It allows the Instana agent to receive traces through an OTLP endpoint.
• Instana OpenTelemetry PHP exporter: It converts the OpenTelemetry spans into Instana spans before they are exported directly to the Instana agent.

The OpenTelemetry traces are visualized in the Instana UI, similar to Instana PHP traces. For more information, see OpenTelemetry Integration for PHP Applications.

Instana supports serverless tracing for the AWS Fargate environment. Similar to the Instana native extension, the serverless extension also enables the PHP tracing by default. For more information on configuration details, see Monitoring AWS Fargate.

To enable the serverless tracing, make sure that the following requirements are met:

• OpenSSL3 or OpenSSL1.1 is installed in the PHP container.
• INSTANA_ENDPOINT_URL and INSTANA_AGENT_KEY environment variables are available to the PHP. For more information on how to configure these variables, see Configuring task definition.

The PHP profiler supports CPU usage profile type and it is available only when the native PHP Tracer is used with the Instana agent. The PHP profiler is not supported in serverless monitoring.

For more information about enabling it, see Configuring profiling.