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
+25-2
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,29 @@ 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/setup/index.md
+114-4
Original file line number
Diff line number
Diff line change
@@ -5,9 +5,119 @@ nav_order: 1
5
5
parent: EDOT PHP
6
6
---
7
7
8
-
# Setting up EDOT PHP
9
-
10
-
TODO:
8
+
<!-- TODO:
11
9
- where to download
12
10
- explicit description of basic setup here (even if it overlaps with upstream docs)
13
-
- link to upstream docs for more advanced setup use cases
11
+
- link to upstream docs for more advanced setup use cases -->
12
+
13
+
# Setting up EDOT PHP
14
+
15
+
This guide shows you how to use the Elastic Distribution of OpenTelemetry PHP (EDOT PHP) to instrument your PHP application and send OpenTelemetry data to an Elastic Observability deployment.
16
+
17
+
**Already familiar with OpenTelemetry?** It's an explicit goal of this distribution to introduce _no new concepts_ outside those defined by the wider OpenTelemetry community.
18
+
19
+
**New to OpenTelemetry?** This section will guide you through the _minimal_ configuration options to get EDOT PHP set up in your application. You do _not_ need any existing experience with OpenTelemetry to set up EDOT PHP initially. If you need more control over your configuration after getting set up, you can learn more in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/php/).
20
+
21
+
## Prerequisites
22
+
23
+
Before getting started, you'll need somewhere to send the gathered OpenTelemetry data so it can be viewed and analyzed. EDOT PHP supports sending data to any OpenTelemetry protocol (OTLP) endpoint, but this guide assumes you are sending data to an [Elastic Observability](https://www.elastic.co/observability) cloud deployment. You can use an existing one or set up a new one.
24
+
25
+
<details>
26
+
<summary><strong>Expand for setup instructions</strong></summary>
27
+
28
+
To create your first Elastic Observability deployment:
29
+
30
+
1. Sign up for a [free Elastic Cloud trial](https://cloud.elastic.co/registration) or sign into an existing account.
31
+
1. Go to <https://cloud.elastic.co/home>.
32
+
1. Click **Create deployment**.
33
+
1. When the deployment is ready, click **Open** to visit your Kibana home page (for example, `https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started`).
34
+
</details>
35
+
36
+
## Install
37
+
38
+
### Prerequisites
39
+
40
+
#### Operating system
41
+
42
+
-**Linux**
43
+
- Architectures: **x86_64** and **ARM64**
44
+
-**glibc-based systems**: Packages available as **DEB** and **RPM**
45
+
-**musl libc-based systems (Alpine Linux)**: Packages available as **APK**
46
+
47
+
#### PHP
48
+
49
+
Supported PHP versions are 8.1-8.4.
50
+
You can find more details in [supported technologies](../supported-technologies.md) doc.
51
+
52
+
### Other limitations
53
+
See [limitations](./limitations.md) about other limitations of EDOT PHP.
54
+
55
+
### Download and install packages
56
+
57
+
To install EDOT PHP download one of the [packages for supported platforms](https://github.com/elastic/elastic-otel-php/releases/latest).
58
+
59
+
#### Install RPM package (RHEL/CentOS, Fedora)
60
+
61
+
rpm -ivh <package-file>.rpm
62
+
63
+
#### Install DEB package (Debian, Ubuntu 18+)
64
+
65
+
dpkg -i <package-file>.deb
66
+
67
+
#### Install APK package (Alpine)
68
+
69
+
apk add --allow-untrusted <package-file>.apk
70
+
71
+
<!-- Start-to-finish operation -->
72
+
## Send data to Elastic
73
+
74
+
After installing EDOT PHP, configure and initialize it to start sending data to Elastic.
75
+
76
+
### Configure EDOT PHP
77
+
78
+
To configure EDOT PHP, at a minimum you'll need your Elastic Observability cloud deployment's OTLP endpoint and
79
+
authorization data to set a few `OTLP_*` environment variables that will be available when running EDOT PHP:
80
+
81
+
*`OTEL_EXPORTER_OTLP_ENDPOINT`: The full URL of the endpoint where data will be sent.
82
+
*`OTEL_EXPORTER_OTLP_HEADERS`: A comma-separated list of `key=value` pairs that will
83
+
be added to the headers of every request. This is typically used for authentication information.
84
+
85
+
<!--
86
+
These are the instructions used in other distro docs, but in the README in this repo
87
+
it looks like you might be recommending using an API key rather than using the secret
88
+
token method used in the setup guides in Kibana.
89
+
-->
90
+
You can find the values of the endpoint and header variables in Kibana's APM tutorial. In Kibana:
91
+
92
+
1. Go to **Setup guides**.
93
+
1. Select **Observability**.
94
+
1. Select **Monitor my application performance**.
95
+
1. Scroll down and select the **OpenTelemetry** option.
96
+
1. The appropriate values for `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are shown there.
97
+
98
+
Here's an example how to connect to Serverless environment:
:warning: After completing the configuration, you should restart the PHP process. If you are using PHP as an Apache Webserver module or PHP-FPM, you need to perform a **full** process restart to ensure that the extension with the agent is loaded correctly.
108
+
109
+
## Confirm that EDOT PHP is working
110
+
111
+
To confirm that EDOT PHP has successfully connected to Elastic:
112
+
113
+
1. Go to **APM** → **Traces**.
114
+
1. You should see the name of the service to which you just added EDOT PHP. It can take several minutes after initializing EDOT PHP for the service to show up in this list.
115
+
1. Click on the name in the list to see trace data.
116
+
117
+
> [!NOTE]
118
+
> There may be no trace data to visualize unless you have _used_ your application since initializing EDOT PHP.
119
+
120
+
## Next steps
121
+
122
+
* Reference all available [configuration options](../configuration.md).
123
+
* Learn more about viewing and interpreting data in the [Observability guide](https://www.elastic.co/guide/en/observability/current/apm.html).
This section describes potential limitations of Elastic Distribution of OpenTelemetry PHP (EDOT PHP)
12
+
and how you can work around them.
13
+
14
+
## OpenTelemetry extension and SDK loaded in parallel with EDOT PHP
15
+
16
+
Currently, the Elastic Distribution of OpenTelemetry PHP (EDOT PHP) does not support scenarios where both EDOT and a vanilla OpenTelemetry PHP setup are installed in the application. This includes the `opentelemetry.so` extension and the OpenTelemetry PHP SDK.
17
+
18
+
In such cases, a conflict will occur, preventing both solutions from functioning correctly. To resolve this, remove OpenTelemetry components from your application's `composer.json` and update the project accordingly.
19
+
20
+
We are actively working on an automated solution to address this issue.
21
+
22
+
## `open_basedir` PHP configuration option
23
+
24
+
Please be aware that if the `open_basedir` option ([documentation](https://www.php.net/manual/en/ini.core.php#ini.open-basedir)) is configured in your php.ini, the installation directory of EDOT PHP (by default `/opt/elastic/apm-agent-php`) must be located within one of the paths specified in the `open_basedir` option.
25
+
Otherwise, EDOT PHP will not be loaded correctly.
26
+
27
+
28
+
## `Xdebug` stability and memory issues
29
+
30
+
We strongly advise against running the agent alongside the Xdebug extension. Using both extensions simultaneously can lead to stability issues in the instrumented application, such as increased memory usage or memory leaks. It is highly recommended to disable xdebug, preferably by disabling it directly in your `php.ini` configuration.
Copy file name to clipboardexpand all lines: docs/_edot-sdks/php/supported-technologies.md
+50-4
Original file line number
Diff line number
Diff line change
@@ -5,8 +5,54 @@ nav_order: 3
5
5
parent: EDOT PHP
6
6
---
7
7
8
-
# Technologies Supported by the EDOT PHP SDK
8
+
# The Elastic Distribution of OpenTelemetry PHP supports the following technologies
9
9
10
-
TODO:
11
-
- Reference the upstream PHP instrumentation.
12
-
- Describe differences (also in default behavior) of EDOT PHP compared to upstream.
10
+
## PHP Versions
11
+
- PHP 8.1 - 8.4
12
+
13
+
> Unlike the upstream OpenTelemetry PHP agent, EDOT PHP supports extension-level instrumentation starting from PHP 8.1 (not just 8.2).
14
+
> This allows you to capture **detailed traces** from libraries such as **cURL**, **PDO**, and **MySQLi**, even in PHP 8.1 environments.
15
+
16
+
## Supported PHP SAPI's
17
+
- php-cli
18
+
- php-fpm
19
+
- php-cgi/fcgi
20
+
- mod_php (prefork)
21
+
22
+
EDOT PHP supports all popular variations of using PHP in combination with a web server, such as Apache + mod_php, Apache + php_fpm or cgi, NGINX + php_fpm or cgi, and others.
23
+
24
+
## Supported Operating Systems
25
+
-**Linux**
26
+
- Architectures: **x86_64** and **ARM64**
27
+
-**glibc-based systems**: Packages available as **DEB** and **RPM**
28
+
-**musl libc-based systems (Alpine Linux)**: Packages available as **APK**
29
+
30
+
## Instrumented Frameworks
31
+
- Laravel (v6.x/v7.x/v8.x/v9.x/v10.x/v11.x)
32
+
- Slim (v4.x)
33
+
34
+
## Instrumented Libraries
35
+
- Curl (v8.1 - v8.4)
36
+
- HTTP Async (php-http/httplug v2.x)
37
+
- MySQLi (v8.1 - v8.4)
38
+
- PDO (v8.1 - v8.4)
39
+
40
+
## Extends the upstream OpenTelemetry PHP with additional features and improvements
41
+
-**Truly zero-config auto-instrumentation**
42
+
Unlike the upstream OpenTelemetry PHP agent, **EDOT PHP works fully automatically** — no need to modify your application code, add Composer packages, or adjust deployment scripts.
43
+
Once the system package is installed, EDOT PHP automatically detects your application and injects the instrumentation code at runtime, with **no manual integration required**.
44
+
45
+
-**Automatic Root/Transaction Span**
46
+
Automatically creates the root span for each incoming request, providing a consistent entry point for trace data without requiring manual instrumentation.
47
+
48
+
-**Root/Transaction Span URL Grouping**
49
+
Groups transaction spans by URL patterns to reduce cardinality and improve readability in dashboards and trace views.
50
+
51
+
-**Inferred Spans (preview version)**
52
+
Automatically detects and generates spans for common operations like database queries or HTTP calls, even when no manual instrumentation is present (currently in preview).
53
+
54
+
-**Asynchronous data sending**
55
+
Sends telemetry data in the background to avoid impacting application performance, ensuring minimal latency and efficient resource usage.
56
+
57
+
> EDOT PHP supports background data transmission (non-blocking export), but **only when the exporter is set to `http/protobuf` (OTLP over HTTP)** — which is the default configuration.
58
+
> If you change the exporter or the transport protocol (e.g., to gRPC or another format), telemetry data will be sent **synchronously**, potentially impacting request latency.
Copy file name to clipboardexpand all lines: docs/_edot-sdks/php/troubleshooting.md
+107-1
Original file line number
Diff line number
Diff line change
@@ -7,4 +7,110 @@ parent: EDOT PHP
7
7
8
8
# Troubleshooting the EDOT PHP Agent
9
9
10
-
TODO
10
+
Is something not working as expected?
11
+
Don't worry if you can't figure out what the problem is; we’re here to help!
12
+
As a first step, make sure your application is compatible with the [technologies supported by EDOT PHP](./supported-technologies.md).
13
+
14
+
If you're an existing Elastic customer with a support contract, please create a ticket in the
15
+
[Elastic Support portal](https://support.elastic.co/customers/s/login/).
16
+
Other users can post in the [APM discuss forum](https://discuss.elastic.co/c/apm).
17
+
18
+
### Enable logging
19
+
20
+
In diagnosing issues with the agent's operation, logs play a key role. A detailed explanation of the logging configuration options can be found in the [configuration documentation](configure.md#logging-configuration).
21
+
22
+
In most cases, setting the logging level to `debug` is sufficient. In extreme cases, `trace` can be used, but keep in mind that the amount of generated data may be significant.
23
+
24
+
Additionally, it is recommended to enable logging for OpenTelemetry components, for example, as shown in the example below using an environment variable. Logs from OpenTelemetry components will be directed to the same output configured for EDOT logs.
25
+
26
+
```
27
+
export OTEL_LOG_LEVEL=DEBUG
28
+
```
29
+
30
+
> **IMPORTANT:**_Please upload your complete debug logs_ to a service like [GitHub Gist](https://gist.github.com) so that we can analyze the problem. Logs should include everything from when the application starts up until the first request executes. It is important to note that logs may contain sensitive data — be sure to review and sanitize them before sharing.
31
+
32
+
33
+
### Disable the Agent
34
+
35
+
In the unlikely event the agent causes disruptions to a production application,
36
+
you can disable the agent while you troubleshoot.
37
+
38
+
You can disable the agent by setting [`elastic_otel.enabled`](./configuration.md#general-configuration) to `false`.
39
+
40
+
> **IMPORTANT:** You'll need to restart your application for the changes to apply.
41
+
42
+
43
+
### Agent is not instrumenting code
44
+
45
+
#### `open_basedir` PHP configuration option
46
+
47
+
If you see a similar entry in the agent log, this indicates an incorrect open_basedir configuration.
48
+
For more details please see [limitations documentation](setup/limitations.md#open_basedir-php-configuration-option).
49
+
50
+
51
+
`Elastic Agent bootstrap file (...php/bootstrap_php_part.php) is located outside of paths allowed by open_basedir ini setting.
52
+
`
53
+
54
+
### Collection of diagnostic information
55
+
56
+
For a more detailed analysis of issues, it is necessary to collect diagnostic information. The agent allows for the automatic collection of such information - all data will be saved to the file specified in the configuration.
57
+
58
+
There are two possible ways to enable this feature:
59
+
60
+
- By php.ini - To enable this feature, you need to modify the php.ini file (or 99-elastic.ini) and provide the path to the file where the data will be saved, f.ex:
- By environment variable. You can also enable information collection using the environment variable `ELASTIC_OTEL_DEBUG_DIAGNOSTIC_FILE`. It must be exported or directly specified when running php process.
Remember, the provided file path must be writable by the PHP process.
73
+
74
+
If there are multiple PHP processes in your system, we allow you to specify directives in the diagnostic file name. This way, the files will remain unique and won't be overwritten.
75
+
76
+
-`%p` - In this place, the agent will substitute the process identifier.
77
+
78
+
-`%t` - In this place, the agent will substitute the UNIX timestamp.
79
+
80
+
>:warning:**IMPORTANT:** After setting the path, remember to _fully restart the process_ for which you are collecting diagnostic information. This may 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.
81
+
>
82
+
>Please 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. Make sure to review the data and mask sensitive information before sharing the file publicly.
83
+
>
84
+
>After collecting diagnostic information, remember to disable this feature and restore the previous configuration in php.ini or the environment variable.
85
+
86
+
87
+
What information will be collected:
88
+
89
+
- Process identifier and parent process identifier
90
+
- User identifier of the worker process
91
+
- List of loaded PHP extensions
92
+
- Result from the `phpinfo()` function
93
+
- Process memory information and memory maps (`/proc/{id}/maps` and `/proc/{id}/smaps_rollup`)
94
+
- Process status information (`/proc/{id}/status`)
95
+
96
+
### Enabling Debugging for Instrumented Functions
97
+
98
+
EDOT allows detailed diagnostics of arguments passed to instrumented functions. This makes it possible to verify whether the data used by the instrumented application is correctly analyzed by the instrumentation code.
99
+
100
+
This feature can be enabled using an environment variable:
101
+
102
+
```bash
103
+
ELASTIC_OTEL_DEBUG_PHP_HOOKS_ENABLED=true
104
+
```
105
+
106
+
107
+
### Enabling instrumentation of the entire application code
108
+
109
+
For diagnostic purposes (*this feature is not suitable for production use*), EDOT allows instrumentation of the entire code. This enables tracking function calls throughout the processing of an entire request or script. It provides better insight into the application's behavior and can help diagnose issues.
110
+
111
+
This feature can be enabled using an environment variable:
0 commit comments