Type to search.

Migrate to EDOT PHP from the Elastic APM PHP agent

Serverless Observability

Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Stack

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

EDOT PHP

The Elastic Distribution of OpenTelemetry (EDOT) PHP SDK collects performance metrics, traces, and logs in OpenTelemetry format, and sends them to Elastic Observability.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

Compared to the Elastic APM PHP agent, the Elastic Distribution of OpenTelemetry PHP presents a number of advantages:

  • Fully automatic instrumentation with zero code changes. No need to modify application code, add Composer packages, or wrap bootstrap files.
  • EDOT PHP is built on top of OpenTelemetry SDK and conventions, ensuring compatibility with community tools, vendor-neutral backends, and so on.
  • Modular, extensible architecture based on the OpenTelemetry SDK. You can add custom exporters, processors, and samplers.
  • You can use EDOT PHP in environments where both tracing and metrics are collected using OpenTelemetry.

Follow these steps to migrate from the legacy Elastic APM PHP agent (apm-agent-php) to the Elastic Distribution of OpenTelemetry PHP (elastic-otel-php).

  1. Uninstall the Elastic APM PHP agent

    Remove the previously installed apm-agent-php package:

    Shell 
    sudo dpkg -r apm-agent-php
    Shell 
    sudo rpm -e apm-agent-php
    Shell 
    sudo apk del apm-agent-php

    To verify the removal, restart your PHP processes and confirm that the elastic_apm extension is no longer loaded:

    Shell 
    php -m | grep elastic_apm

    The command should return no output.

  2. Install EDOT PHP

    Download the appropriate package for your system from the GitHub releases page.

    Shell 
    sudo dpkg -i elastic-otel-php_<version>_amd64.deb
    Shell 
    sudo rpm -ivh elastic-otel-php-<version>-1.x86_64.rpm
    Shell 
    sudo apk add --allow-untrusted elastic-otel-php-<version>.apk

  3. Update configuration

    Switch from php.ini-based configuration to environment variables. The following is a common mapping between old and new settings:

    Elastic APM (php.ini) EDOT PHP (environment variable) Description
    elastic_apm.enabled = 1 OTEL_PHP_ENABLED=true Turns on EDOT PHP features - enabled by default
    elastic_apm.service_name = my-app OTEL_SERVICE_NAME=my-app Defines the logical service name
    elastic_apm.server_url = http://... OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 Sets OTLP exporter endpoint
    elastic_apm.secret_token = token123 OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token123" Sets auth header for OTLP exporter
    elastic_apm.environment = prod OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=prod Adds environment context to exported data
    Tip

    EDOT PHP does not require changes to your code or Composer configuration — instrumentation works automatically after package installation.

  4. Restart your PHP environment

    Restart the relevant PHP processes for changes to take effect. This might include:

    Shell 
    sudo systemctl restart php8.x-fpm
    Shell 
    sudo systemctl restart apache2
    Shell 
    php script.php

The following are Elastic APM PHP agent settings that you can migrate to EDOT PHP.

Elastic APM PHP Option EDOT PHP Environment variable equivalent Option Description
api_key OTEL_EXPORTER_OTLP_HEADERS Set API key using OTLP headers. Example: Authorization=Bearer <token>.
breakdown_metrics Not available No span compression or breakdown-type metric generation (yet).
capture_errors Not available No direct equivalent. Handled using standard error handling and inferred spans.
disable_instrumentations OTEL_PHP_DISABLED_INSTRUMENTATIONS Comma-separated list of instrumentations to deactivate.
disable_send Not available No direct option. Could potentially be simulated with custom exporters or filtering processors.
enabled OTEL_PHP_ENABLED Activates or deactivates EDOT PHP instrumentation entirely.
environment OTEL_RESOURCE_ATTRIBUTES Add deployment metadata (for example, deployment.environment.name=prod).
global_labels OTEL_RESOURCE_ATTRIBUTES Set global key-value pairs for all spans/metrics.
log_level OTEL_LOG_LEVEL, OTEL_PHP_LOG_LEVEL_FILE Controls log verbosity globally (OTEL_LOG_LEVEL) or per sink (for example, file, stderr, syslog using OTEL_PHP_LOG_LEVEL_*).
server_url OTEL_EXPORTER_OTLP_ENDPOINT Sets OTLP exporter endpoint. Defaults to http://localhost:4318.
service_name OTEL_SERVICE_NAME Defines service name for traces/metrics.
transaction_sample_rate OTEL_TRACES_SAMPLER_ARG Sampling rate for traces (for example, 0.25).
transaction_max_spans Not available No direct support in PHP SDK for limiting spans per transaction.
span_frames_min_duration OTEL_PHP_INFERRED_SPANS_MIN_DURATION Duration threshold for inferred spans.
sanitize_field_names Not available Not yet supported in EDOT PHP.
verify_server_cert OTEL_EXPORTER_OTLP_INSECURE Turn on or turn off SSL verification when exporting telemetry.
transaction_ignore_urls OTEL_PHP_EXCLUDED_URLS A comma-separated list of regex patterns for excluding incoming HTTP URLs from tracing (for example, client/.*/info,healthcheck).
transaction_name_callback Not available No equivalent for callback-based naming; use grouping or manual setAttribute().
log_level_syslog OTEL_PHP_LOG_LEVEL_SYSLOG Sets syslog sink verbosity.
log_level_file OTEL_PHP_LOG_LEVEL_FILE Controls log level for file-based output.
log_level_stderr OTEL_PHP_LOG_LEVEL_STDERR Controls log level for stderr (recommended in containers).
log_file OTEL_PHP_LOG_FILE Path for log output; supports %p (PID) and %t (timestamp) placeholders.
log_feature OTEL_PHP_LOG_FEATURES Fine-grained feature-based logging configuration.
transaction_url_groups OTEL_PHP_TRANSACTION_URL_GROUPS Group similar URL paths (for example, /user/*).
inferred_spans_enabled OTEL_PHP_INFERRED_SPANS_ENABLED Activates inferred spans (preview).
inferred_spans_sampling_interval OTEL_PHP_INFERRED_SPANS_SAMPLING_INTERVAL Sampling frequency for stack traces during inferred spans.
inferred_spans_min_duration OTEL_PHP_INFERRED_SPANS_MIN_DURATION Minimum duration of inferred span (used to limit noise).

You can manage EDOT PHP configurations through the central configuration feature in the Applications UI.

Refer to Central configuration for more information.

The following limitations apply to EDOT PHP:

  • Lack of span compression: The classic Elastic APM agent includes span compression, which merges multiple similar spans. EDOT PHP doesn't currently support span compression. As a result, traces may be more verbose and produce higher cardinality, especially in loop-heavy code.
Note

For a broader overview of known limitations — including technical constraints related to PHP runtime and extensions, refer to Limitations.

If you're encountering issues during migration, refer to the EDOT PHP troubleshooting guide.