You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/_edot-sdks/php/index.md
+26-2
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,30 @@ layout: default
4
4
nav_order: 5
5
5
---
6
6
7
-
## EDOT PHP
7
+
#Elastic Distribution of OpenTelemetry PHP
8
8
9
-
TODO: Put some content here
9
+
The Elastic Distribution of OpenTelemetry PHP (EDOT PHP) is a customized version of [OpenTelemetry for PHP](https://opentelemetry.io/docs/languages/php).
10
+
EDOT PHP makes it easier to get started using OpenTelemetry in your PHP applications through strictly OpenTelemetry native means, while also providing a smooth and rich out of the box experience with [Elastic Observability](https://www.elastic.co/observability). It's an explicit goal of this distribution to introduce **no new concepts** in addition to those defined by the wider OpenTelemetry community.
11
+
12
+
With EDOT PHP you have access to all the features of the OpenTelemetry PHP agent plus:
13
+
14
+
* Access to SDK improvements and bug fixes contributed by the Elastic team _before_ the changes are available upstream in OpenTelemetry repositories.
15
+
* Access to optional features that can enhance OpenTelemetry data that is being sent to Elastic.
16
+
* Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like an Elastic Observability deployment.
17
+
* Preconfigured collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default.
18
+
* Ensuring that the OpenTelemetry protocol (OTLP) exporter is enabled by default.
19
+
* Built-in support for **asynchronous data transmission**, reducing request latency
20
+
* Out-of-the-box auto-instrumentation — no need to modify your code. EDOT PHP takes care of enabling telemetry collection automatically.
21
+
* Additional runtime features such as **automatic root span creation**, **URL grouping**, and **inferred spans** to provide richer and more structured trace data with minimal setup.
22
+
23
+
**Ready to try out EDOT PHP?** Follow the step-by-step instructions in [Get started](./docs/get-started.md).
Copy file name to clipboardexpand all lines: docs/_edot-sdks/php/migration.md
+161-5
Original file line number
Diff line number
Diff line change
@@ -7,8 +7,164 @@ parent: EDOT PHP
7
7
8
8
# Migrating to EDOT PHP from the Elastic PHP Agent
9
9
10
-
TODO:
11
-
- migration steps
12
-
- advantages of using EDOT
13
-
- limitations compared to classic agents
14
-
- (optional) performance comparison
10
+
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`).
11
+
12
+
### 1. Uninstall the Elastic APM PHP agent
13
+
14
+
Remove the previously installed `elastic-apm-php` package:
15
+
16
+
**Debian/Ubuntu:**
17
+
18
+
```bash
19
+
sudo dpkg -r elastic-apm-php
20
+
```
21
+
22
+
**CentOS/Fedora:**
23
+
24
+
```bash
25
+
sudo rpm -e elastic-apm-php
26
+
```
27
+
28
+
**Alpine Linux:**
29
+
30
+
```bash
31
+
sudo apk del elastic-apm-php
32
+
```
33
+
34
+
---
35
+
36
+
### 2. Install EDOT PHP
37
+
38
+
Download the appropriate package for your system from the [GitHub releases page](https://github.com/elastic/elastic-otel-php/releases).
|`api_key`|[`OTEL_EXPORTER_OTLP_HEADERS`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_exporter_otlp_headers)| Set API key via OTLP headers. Example: `Authorization=Bearer <token>`. |
81
+
|`breakdown_metrics`| ❌ | No span compression or breakdown-type metric generation (yet). |
82
+
|`capture_errors`| ❌ | No direct equivalent. Handled via standard error handling and inferred spans. |
83
+
|`disable_instrumentations`|[`OTEL_PHP_DISABLED_INSTRUMENTATIONS`](https://opentelemetry.io/docs/zero-code/php#disabled-instrumentations)| Comma-separated list of instrumentations to disable. |
84
+
|`disable_send`| ❌ | No direct option. Could potentially be simulated with custom exporters or filtering processors. |
85
+
|`enabled`|[`ELASTIC_OTEL_ENABLED`](./configuration.md#general-configuration)| Enables or disables EDOT PHP instrumentation entirely. |
|`global_labels`|[`OTEL_RESOURCE_ATTRIBUTES`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_resource_attributes)| Set global key-value pairs for all spans/metrics. |
88
+
|`log_level`|[`OTEL_LOG_LEVEL`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_log_level), [`ELASTIC_OTEL_LOG_LEVEL_FILE`](./configuration.md#logging-configuration)| Controls log verbosity globally (`OTEL_LOG_LEVEL`) or per sink (e.g., file, stderr, syslog via `ELASTIC_OTEL_LOG_LEVEL_*`). |
89
+
|`server_url`|[`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_exporter_otlp_endpoint)| Sets OTLP exporter endpoint. Defaults to `http://localhost:4318`. |
90
+
|`service_name`|[`OTEL_SERVICE_NAME`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_service_name)| Defines service name for traces/metrics. |
91
+
|`transaction_sample_rate`|[`OTEL_TRACES_SAMPLER_ARG`](https://opentelemetry.io/docs/languages/sdk-configuration/general/#otel_traces_sampler_arg)| Sampling rate for traces (e.g., `0.25`). |
92
+
|`transaction_max_spans`| ❌ | No direct support in PHP SDK for limiting spans per transaction. |
93
+
|`span_frames_min_duration`|[`ELASTIC_OTEL_INFERRED_SPANS_MIN_DURATION`](./configuration.md#inferred-spans-configuration)| Duration threshold for inferred spans. |
94
+
|`sanitize_field_names`| ❌ | Not yet supported in EDOT PHP. |
95
+
|`verify_server_cert`|[`ELASTIC_OTEL_VERIFY_SERVER_CERT`](./configuration.md#asynchronous-data-sending-configuration)| Enable or disable SSL verification when exporting telemetry. |
96
+
|`transaction_ignore_urls`|[`OTEL_PHP_EXCLUDED_URLS`](https://opentelemetry.io/docs/languages/php/sdk/#configuration)| A comma-separated list of regex patterns for excluding incoming HTTP URLs from tracing (e.g., `client/.*/info,healthcheck`). |
97
+
|`transaction_name_callback`| ❌ | No equivalent for callback-based naming; use grouping or manual `setAttribute()`. |
|`log_level_file`|[`ELASTIC_OTEL_LOG_LEVEL_FILE`](./configuration.md#logging-configuration)| Controls log level for file-based output. |
100
+
|`log_level_stderr`|[`ELASTIC_OTEL_LOG_LEVEL_STDERR`](./configuration.md#logging-configuration)| Controls log level for stderr (recommended in containers). |
101
+
|`log_file`|[`ELASTIC_OTEL_LOG_FILE`](./configuration.md#logging-configuration)| Path for log output; supports `%p` (PID) and `%t` (timestamp) placeholders. |
|`transaction_url_groups`|[`ELASTIC_OTEL_TRANSACTION_URL_GROUPS`](./configuration.md#transaction-span-configuration)| Group similar URL paths (e.g., `/user/*`). |
|`inferred_spans_sampling_interval`|[`ELASTIC_OTEL_INFERRED_SPANS_SAMPLING_INTERVAL`](./configuration.md#inferred-spans-configuration)| Sampling frequency for stack traces during inferred spans. |
106
+
|`inferred_spans_min_duration`|[`ELASTIC_OTEL_INFERRED_SPANS_MIN_DURATION`](./configuration.md#inferred-spans-configuration)| Minimum duration of inferred span (used to limit noise). |
107
+
108
+
109
+
---
110
+
111
+
### 4. Restart your PHP environment
112
+
113
+
Restart the relevant PHP processes for changes to take effect. This could include:
114
+
115
+
- PHP-FPM:
116
+
```bash
117
+
sudo systemctl restart php8.x-fpm
118
+
```
119
+
120
+
- Apache:
121
+
```bash
122
+
sudo systemctl restart apache2
123
+
```
124
+
125
+
- CLI scripts:
126
+
```bash
127
+
php script.php
128
+
```
129
+
130
+
---
131
+
132
+
✅ You’re now ready to start collecting traces and metrics using OpenTelemetry with Elastic!
133
+
134
+
## Advantages of EDOT PHP over the Classic Elastic APM Agent
135
+
136
+
### Fully automatic instrumentation with zero code changes
137
+
- No need to modify application code, add Composer packages, or wrap bootstrap files.
138
+
- Works out-of-the-box after system package installation.
139
+
- No need to register SDK, bootstrap, or start a tracer manually — everything is handled by the agent at the extension level.
140
+
141
+
### OpenTelemetry standard compliance
142
+
- EDOT PHP is built on top of **OpenTelemetry SDK and conventions**, ensuring compatibility with:
143
+
- community tools,
144
+
- vendor-neutral backends,
145
+
- standard propagation formats (`traceparent`, `baggage`),
146
+
- open observability pipelines (e.g., EDOT Collector or OpenTelemetry Collector).
147
+
148
+
### Modular, extensible architecture
149
+
- Based on the OpenTelemetry SDK — you can add custom exporters, processors, and samplers.
150
+
- Easy to extend or adapt to advanced use cases (e.g., exporting to multiple backends).
151
+
152
+
### Better future-proofing and community alignment
153
+
- EDOT PHP benefits from:
154
+
- upstream OpenTelemetry improvements,
155
+
- Elastic-specific early bugfixes and features,
156
+
- community-driven instrumentation libraries and patterns.
- EDOT PHP can be used in environments where **both tracing and metrics** are collected using OpenTelemetry.
160
+
- The classic APM agent focuses solely on APM/tracing.
161
+
162
+
163
+
164
+
## ⚠️ Limitations Compared to the Elastic APM Agent
165
+
166
+
- Lack of Span Compression
167
+
168
+
The classic Elastic APM agent includes span compression, which merges multiple similar spans (e.g., repeated SQL queries or HTTP calls) into a single composite span to reduce trace noise and overhead.
169
+
170
+
EDOT PHP does not currently support span compression. As a result, traces may be more verbose and produce higher cardinality, especially in loop-heavy code.
0 commit comments