Migrate to EDOT PHP from the Elastic APM PHP agent
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 (elastic-apm-php) to the Elastic Distribution of OpenTelemetry PHP (elastic-otel-php).
Uninstall the Elastic APM PHP agent
Remove the previously installed
elastic-apm-phppackage:sudo dpkg -r elastic-apm-phpsudo rpm -e elastic-apm-phpsudo apk del elastic-apm-phpInstall EDOT PHP
Download the appropriate package for your system from theGitHub releases page.
sudo dpkg -i elastic-otel-php_<version>_amd64.debsudo rpm -ivh elastic-otel-php-<version>-1.x86_64.rpmsudo apk add --allow-untrusted elastic-otel-php-<version>.apkUpdate 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 = 1ELASTIC_OTEL_ENABLED=trueEnables EDOT PHP features - enabled by default elastic_apm.service_name = my-appOTEL_SERVICE_NAME=my-appDefines the logical service name elastic_apm.server_url = http://...OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318Sets OTLP exporter endpoint elastic_apm.secret_token = token123OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer token123"Sets auth header for OTLP exporter elastic_apm.environment = productionOTEL_RESOURCE_ATTRIBUTES=deployment.environment=productionAdds environment context to exported data TipEDOT PHP does not require changes to your code or Composer configuration — instrumentation works automatically after package installation.
Restart your PHP environment
Restart the relevant PHP processes for changes to take effect. This might include:
sudo systemctl restart php8.x-fpmsudo systemctl restart apache2php 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 via 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 via standard error handling and inferred spans. |
disable_instrumentations | OTEL_PHP_DISABLED_INSTRUMENTATIONS | Comma-separated list of instrumentations to disable. |
disable_send | Not available | No direct option. Could potentially be simulated with custom exporters or filtering processors. |
enabled | ELASTIC_OTEL_ENABLED | Enables or disables EDOT PHP instrumentation entirely. |
environment | OTEL_RESOURCE_ATTRIBUTES | Add deployment metadata (e.g.,deployment.environment=prod). |
global_labels | OTEL_RESOURCE_ATTRIBUTES | Set global key-value pairs for all spans/metrics. |
log_level | OTEL_LOG_LEVEL,ELASTIC_OTEL_LOG_LEVEL_FILE | Controls log verbosity globally (OTEL_LOG_LEVEL) or per sink (e.g., file, stderr, syslog viaELASTIC_OTEL_LOG_LEVEL_*). |
server_url | OTEL_EXPORTER_OTLP_ENDPOINT | Sets OTLP exporter endpoint. Defaults tohttp://localhost:4318. |
service_name | OTEL_SERVICE_NAME | Defines service name for traces/metrics. |
transaction_sample_rate | OTEL_TRACES_SAMPLER_ARG | Sampling rate for traces (e.g.,0.25). |
transaction_max_spans | Not available | No direct support in PHP SDK for limiting spans per transaction. |
span_frames_min_duration | ELASTIC_OTEL_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 | Enable or disable 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 (e.g.,client/.*/info,healthcheck). |
transaction_name_callback | Not available | No equivalent for callback-based naming; use grouping or manualsetAttribute(). |
log_level_syslog | ELASTIC_OTEL_LOG_LEVEL_SYSLOG | Sets syslog sink verbosity. |
log_level_file | ELASTIC_OTEL_LOG_LEVEL_FILE | Controls log level for file-based output. |
log_level_stderr | ELASTIC_OTEL_LOG_LEVEL_STDERR | Controls log level for stderr (recommended in containers). |
log_file | ELASTIC_OTEL_LOG_FILE | Path for log output; supports%p (PID) and%t (timestamp) placeholders. |
log_feature | ELASTIC_OTEL_LOG_FEATURES | Fine-grained feature-based logging configuration. |
transaction_url_groups | ELASTIC_OTEL_TRANSACTION_URL_GROUPS | Group similar URL paths (e.g.,/user/*). |
inferred_spans_enabled | ELASTIC_OTEL_INFERRED_SPANS_ENABLED | Enables inferred spans (preview). |
inferred_spans_sampling_interval | ELASTIC_OTEL_INFERRED_SPANS_SAMPLING_INTERVAL | Sampling frequency for stack traces during inferred spans. |
inferred_spans_min_duration | ELASTIC_OTEL_INFERRED_SPANS_MIN_DURATION | Minimum duration of inferred span (used to limit noise). |
You can manage EDOT PHP configurations through thecentral configuration feature in the Applications UI.
Refer toCentral 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.
For a broader overview of known limitations — including technical constraints related to PHP runtime and extensions, refer toLimitations.
If you're encountering issues during migration, refer to theEDOT PHP troubleshooting guide.