Enabling and configuring PHP tracing

Use one of the following methods to provide the configuration to disable tracing:

• Custom configuration file
• Instana agent configuration.yaml file

For details about configuration precedence, see Configuration precedence for disabling spans.

For information about span disabling configuration syntax, see Disabling tracing.

Disabling tracing for a category disables the span generation for all the libraries under that category. See the following list of categories supported by PHP Tracer:

• databases
• frameworks
• messaging
• protocols
• logging
• templating
• Others (No category key is available for others)

You can use all instrumentation identifiers listed in the auto-instrumented libraries and frameworks table to configure span disable rules for specific span types.

Span disabling rules are applied in the following order of precedence, listed from highest to lowest:

1. Span disabling rules from the custom configuration file that is passed through the INSTANA_CONFIG_PATH environment variable.
2. Span disabling configured in the instana.disabled_instrumentation INI setting.
3. Span disabling rules from the agent configuration.yaml file.

If a PHP runtime detects multiple configurations, it applies only the span disabling rules from the configuration with the highest precedence.

For example, if a PHP runtime has the following span disabling rules set through INSTANA_CONFIG_PATH environment variable:

com.instana.tracing:
  disable:
    - logging: true
    - databases: true
    - redis: false
 

And the same runtime has the following INI setting:

instana.disabled_instrumentation=24 ; disables redis (16) and curl (8) instrumentations
 

With this example configuration, the PHP Tracer works as follows:

• Tracing for all logging libraries is disabled.
• Tracing for all databases is disabled except for Redis.

The instana.disabled_instrumentation INI setting is ignored as the INSTANA_CONFIG_PATH environment variable takes precedence. Therefore, all instrumentations that are not disabled through the configuration file specified by the INSTANA_CONFIG_PATH environment variable are enabled.

If span disabling rules are set through both the INSTANA_CONFIG_PATH environment variable and the agent configuration.yaml file, then the rules from the configuration.yaml file are ignored.

Configure stack traces using custom configuration files, environment variables, or Instana agent configuration.

Use one of the following methods to configure stack traces:

• Custom configuration file
• Environment variables
• Instana agent configuration.yaml file

For details about configuration precedence between different configuration methods, see Configuration precedence for stack traces.

Use YAML syntax to configure stack trace level and depth settings.

Use the following YAML syntax to provide the stack trace configuration:

# Use 'tracing' section if using custom configuration file
# Use 'com.instana.tracing' section if using agent configuration.yaml file
tracing:
  global:
    stack-trace: <string>
    stack-trace-length: <int>

Stack trace configuration is applied in order of precedence from custom configuration files to agent configuration.

Stack trace configuration is applied in the following order of precedence, listed from highest to lowest:

1. Stack trace configuration from the custom configuration file that is passed through the INSTANA_CONFIG_PATH environment variable.
2. Stack trace configuration set through the environment variables INSTANA_STACK_TRACE and INSTANA_STACK_TRACE_LENGTH.
3. Stack trace length set through instana.backtrace_limit INI setting.
4. Stack trace configuration from the agent configuration.yaml file.

The precedence is evaluated and applied separately for stack trace mode and stack trace length settings across the different configuration methods listed in the preceding section.

Configure systemd services with PrivateTmp directive to allow PHP Tracer access to YAML configuration.

If your PHP runtime is a systemd service configured with the PrivateTmp directive, then the PHP processes get their own temp directory that is isolated from the host's system temp directory. The PHP sensor cannot write to the process's temp directory, so the PHP Tracer cannot read the YAML configuration in such PHP runtimes.

If disabling the PrivateTmp setting in the PHP systemd service is not ideal to your requirements, you can use a custom configuration file instead for configuring span disabling rules, span filtering rules and stack traces without disabling PrivateTmp in the PHP systemd service.

Alternatively, if your PHP runtime does not need the temp file system isolation offered by the PrivateTmp setting, then you can disable PrivateTmp for the PHP systemd service by following these steps and continue to use the agent configuration.yaml file for configuring span disabling rules, span filtering rules and stack traces:

1. Edit the PHP systemd service unit file by running the following command:

   sudo systemctl edit <systemd-service-unit-name>
   # systemd service names are usually named like apache2.service, php8.3-fpm.service, etc.,

2. Set the PrivateTmp directive to false in the [Service] section:

   [Service]
   PrivateTmp=false

3. Reload systemd configuration

   systemctl daemon-reload

4. Restart the systemd service to apply the changes.

IIS worker processes sometimes lack access to the Windows temp folder. This insufficient access to the temp folder is due to the application pool identity that is used to run the worker processes lacking sufficient read or write permissions to the temp folder. To resolve this access issue, perform the following steps:

1. Confirm the identity of your application pool by running the following command in your PowerShell terminal:

   & $env:windir\system32\inetsrv\appcmd.exe list apppool <your AppPool> /text:processModel.identityType
    

2. If the identity is not ApplicationPoolIdentity, run the following command to update the identity:

   & $env:windir\system32\inetsrv\appcmd.exe set AppPool <your AppPool> -processModel.identityType:ApplicationPoolIdentity
    

3. Restart your application pool to apply the changes:

   & $env:windir\system32\inetsrv\appcmd.exe recycle apppool <your AppPool>
    

   IIS server detects the application pool running with the identity ApplicationPoolIdentity, and creates a virtual user with the name of your application pool.

4. To give the PHP runtime, that is, IIS worker processes read access to the <SYSTEM_TEMP> directory, use the following command:

   
   icacls "<SYSTEM_TEMP>" /grant "IIS APPPOOL\<your AppPool>:(OI)(CI)R" /T /C
    

The notification script runs once per PHP runtime, which means that the script might not be triggered for all processes that run the same PHP executable file. To load the PHP Tracing extension into memory, you must make sure that your script restarts all the processes that run from that PHP executable file.

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 that 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.

To disable the automatic installation of the PHP Tracing extension in newly detected PHP runtimes, set tracing.installExtension to false in the com.instana.plugin.php section in the agent configuration.yaml file:

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

If you use Plesk, you need to run plesk bin php_handler --reread.

If you don't see any traces appearing in the Instana UI for PHP applications, complete the following steps:

1. Verify the following prerequisites:

   • The PHP sensor is enabled. For more information, see Disabling PHP Tracing.
   • The PHP Tracing extension binary is available. For more information, see Disabling the PHP Tracing extension.
   • The PHP Tracing extension is enabled in the agent configuration file. For more information, see Removing the PHP Tracing extension file.

2. Reload the PHP Tracing extension by running the following reload command on the service that runs PHP applications:

   • For Apache:

     systemctl reload apache2
      

   • For PHP-FPM:

     systemctl reload php<version>-fpm
      

     Replace <version> in the reload command with the actual version that is installed in the system.

If you still don't see any traces in the Instana UI and your operating system includes SELinux by default or adds it to the environment for security purposes, SELinux might be responsible for the issue.

The PHP Tracer extension communicates with the PHP daemon over the Unix TCP socket <socket path> and with the Instana agent over TCP/IP port 42699. When SELinux is set to enforcing mode, it prevents the PHP extension and daemon from communicating with each other unless SELinux is configured to allow it.

To verify whether SELinux is responsible for the issue, check /var/log/audit/audit.log for any silent denials that are recorded for the PHP daemon. Alternatively, you can do a smoke test by completing the following steps:

1. Disable SELinux temporarily.
2. Restart PHP daemon.

If SELinux is identified as the cause for the issue, you can resolve it by using any one of the following options:

• Configure SELinux to allow PHP Tracer to communicate: With SELinux, you can follow your own security policies to configure a custom policy to allow for communication. For more information about creating and modifying SELinux policy, see the following links:

  • CentOS SELinux documentation
  • RHEL SELinux documentation

• Set SELinux to permissive mode: In this mode, your services can operate without restrictions. You can restore the default setting by restarting the server. To set SELinux to permissive mode, see SELinux permissive mode.

• Disable SELinux: Instana does not actively encourage you to disable security software. A right and safe approach is to create a SELinux policy. However, if you decide to disable SELinux, see Disable SELinux.

By default, logging is turned off. To enable it, refer to the following steps.

• Enable logging by using environment variables.
  1. To set the log level to debug, set INSTANA_DEBUG to TRUE or INSTANA_LOG_LEVEL=4

• Enable logging by using INI file.

  1. Locate a file named zzz-instana.ini in the scan directory of your PHP installation. For example, running php --ini | grep zzz-instana.ini or php-fpm<version> -i | grep zzz-instana.ini reveals its location.

  2. Add the line instana.log_level=4 to zzz-instana.ini.

  3. When you run the PHP runtime of your choice, make sure that some logging is present in the output and that the extension is enabled. For example, you can run php --ri instana or php-fpm<version> -i | grep instana to verify.

     Example:

     [instana.INFO] Initializing, logging at level 4
      

  4. Reload the PHP tracing extension as described here. Skipping this step will ultimately result in no logging.

To manually install the PHP Tracing extension, complete the following steps:

1. Download the Instana PHP Tracing extension as follows:

   1. Download the shell script from the following repository:

      https://artifact-public.instana.io/artifactory/shared/com/instana/php/instana-ext-download-script/php-instana-ext-download-script.sh
       

   2. Run the shell script to download the extension suitable for your environment. The following command shows the available options:

      ./php-instana-ext-download-script.sh -a <aarch64/x86_64> -l <musl/glibc> -p <PHP version> -t <NTS/ZTS> -d <serverless/native> -s <OpenSSL version> -v <Instana extension version>
       

      • For the PHP version, provide major and minor version numbers. For example, to download the Instana extension for PHP 8.4.12, run the shell script with flag -p 8.4.

      • For the OpenSSL version, use the option -s ssl1 to download the extension that supports OpenSSL 1.1 or use -s ssl3 to download the extension that supports OpenSSL 3.x.

      • For the Instana extension version, the default value is release, which downloads the latest version available. Use -v flag to download the artifact for any specific version. For example, run the script with -v 4.7.0 to download the extension with the release version 4.7.0.

      • To see all the options available for the script, run the following command:

        ./php-instana-ext-download-script.sh
         

2. Install the extension as follows:

   1. Move the downloaded .so file to the PHP CLI extension directory.

   2. Create an INI file, zzz-instana.ini, as shown in the following example, and save it to the PHP CLI additional INI directory. Replace <hostIP> with the IP address of the Instana agent host so that the agent is reachable from the PHP environment.

      ; this file was automatically generated by Instana
      ;
      ; any changes made to this file are expected to be overwritten when
      ; a new version of the Instana PHP Tracer extension is installed
      [instana]
      extension=<php cli extension dir path where extension.so file is placed>
      instana.socket=<hostIP>:16816
      instana.agent_endpoint=http://<hostIP>:42699
      instana.use_agent_endpoint=1
      instana.auto_profile_socket=tcp://<hostIP>:42699
      instana.enable_auto_profile=0
      instana.secrets_matcher=contains-ignore-case
      instana.secrets_list="key,pass,secret"
      instana.extra_http_headers=
      instana.pid_in_root_namespace=<pid of PHP process in hostnamespace>
      instana.enable_cli=1
       

Following the steps outlined in Disabling PHP tracing disables PHP tracing completely, including removal of the PHP Tracing extension from your PHP runtime.

If you encounter errors during this procedure and you want to manually disable PHP tracing and uninstall the PHP Tracing extension, complete the following steps:

1. Make sure that PHP tracing is disabled in the agent configuration.yaml file as follows:

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

   This configuration prevents the PHP sensor from reinstalling the PHP Tracing extension again.

2. Disable the PHP Tracing extension in your PHP INI configuration. See Disabling the PHP Tracing extension.

3. Remove the PHP Tracing extension file from your system. See Removing the PHP Tracing extension file.