Loading

Troubleshooting the EDOT PHP agent

Elastic Stack Serverless Observability

Use the information on this page to troubleshoot issues using EDOT PHP.

If you need help and you're an existing Elastic customer with a support contract, create a ticket in the Elastic Support portal. Other users can post in the APM discuss forum or open a GitHub issue.

As a first step, review the supported technologies to ensure your application is supported by the agent. Are you using a PHP version that EDOT PHP supports? Are the versions of your dependencies in the supported version range to be instrumented?

When diagnosing issues with the agent's operation, logs play a key role. You can find a detailed explanation of the logging configuration options in Configuration.

In most cases, setting the logging level to debug is sufficient. You can also use trace can be used, but keep in mind that the amount of generated data might be significant.

Additionally, turn on logging for OpenTelemetry components, for example as shown in the following example . Logs from OpenTelemetry components are directed to the same output configured for EDOT logs.

export OTEL_LOG_LEVEL=DEBUG
Note

Upload your complete debug logs to a service like GitHub Gist so that Elastic support can analyze the problem. Logs should include everything from when the application starts up until the first request executes. Logs might contain sensitive data: make sure to review and sanitize them before sharing.

If you suspect that the agent might be causing disruptions to a production application, you can deactivate the agent while you troubleshoot.

To deactivate the agent, set the elastic_otel.enabled setting to false.

Note

You need to restart your application for the changes to apply.

If the agent doesn't seem to be instrumenting code from your application, try the following actions.

If you're experiencing issues where no spans, logs, or metrics are being sent, or if you encounter log messages like the following:

Failed to serialize spans/logs/metrics batch...

This might be due to a failure in the native OTLP Protobuf serializer. The native serializer is activated by default for maximum performance, but in rare cases it might encounter incompatibilities with certain environments or data. To confirm whether this is the cause, try turning off the native serializer using the following environment variable:

export ELASTIC_OTEL_NATIVE_OTLP_SERIALIZER_ENABLED=false

Restart your application and check if spans, logs, or metrics start appearing correctly.

Note

When turned off, the agent falls back to a PHP-based serializer, which has lower performance.

If you see a similar entry in the agent log, this indicates an incorrect open_basedir configuration. For more details, refer to Limitations.

EDOT PHP bootstrap file (...php/bootstrap_php_part.php) is located outside of paths allowed by open_basedir ini setting.

For a more detailed analysis of issues, you might need to collect diagnostic information. The agent allows for the automatic collection of such information: all data is saved to the file specified in the configuration.

There are two possible ways to turn on diagnostic information:

  • By editing the php.ini file: Modify the php.ini file, or 99-elastic.ini, to provide the path to the file where the data will be saved, For example:

    elastic_otel.debug_diagnostic_file=/tmp/php_diags_%p_%t.txt

  • By setting an environment variable. The ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE environment variable must be exported or directly specified when running PHP process. For example:

    ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE=/tmp/php_diags_%p_%t.txt php test.php

    The provided file path must be writable by the PHP process. If there are multiple PHP processes in your system, you can specify directives in the diagnostic file name. This way, the files remain unique and won't be overwritten.

    • %p - In this place, the agent substitutes the process identifier.
    • %t - In this place, the agent substitutes the UNIX timestamp.
Warning

After setting the path, remember to fully restart the process for which you are collecting diagnostic information. This might vary depending on the context, such as PHP, PHP-FPM, Apache, or PHP-CGI. Diagnostic information will be recorded after the first HTTP request is made or at the beginning of script execution for PHP-CLI. Also be aware that the information contained in the output file may include sensitive data, such as passwords, security tokens or environment variables from your system. After collecting diagnostic information, remember to disable this feature and restore the previous configuration in php.ini or the environment variable.

The following information is collected:

  • Process identifier and parent process identifier
  • User identifier of the worker process
  • List of loaded PHP extensions
  • Result from the phpinfo() function
  • Process memory information and memory maps (/proc/{id}/maps and /proc/{id}/smaps_rollup)
  • Process status information (/proc/{id}/status)

EDOT can collect detailed diagnostics of arguments passed to instrumented functions. Use them to verify whether the data used by the instrumented application is correctly analyzed by the instrumentation code.

To turn on debugging for instrumented function, set the following environment variable:

ELASTIC_OTEL_DEBUG_PHP_HOOKS_ENABLED=true

For diagnostic purposes outside of production environments, EDOT allows instrumenting the entire code of your application. This allows tracking function calls throughout the processing of an entire request or script and provides better insight into the application's behavior.

To turn on debugging for instrumented function, set the following environment variable:

ELASTIC_OTEL_DEBUG_INSTRUMENT_ALL=true