Skip to content

Commit 0a35024

Browse files
intuibaseintuibase
authored
Distro documentation (#32) (#34)
1 parent ac3502e commit 0a35024

File tree

7 files changed

+409
-2
lines changed

7 files changed

+409
-2
lines changed

‎README.md‎

Lines changed: 94 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,97 @@
1-
# OpenTelemetry Php Distro
1+
# OpenTelemetry PHP Distro
22

3-
> **⚠️ Note:** This project is currently in the process of being contributed to the OpenTelemetry community. The first official release is coming soon. Stay tuned for updates!
3+
Production-ready, zero-code OpenTelemetry instrumentation for PHP, delivered as native Linux packages.
4+
5+
## Why this project exists
6+
7+
Many PHP environments are hard to instrument with a Composer-only workflow (locked-down hosts, limited build tooling, or strict deployment pipelines). OpenTelemetry PHP Distro focuses on those production realities:
8+
9+
- install via OS package (`deb`, `rpm`, `apk`)
10+
- restart PHP process
11+
- start sending telemetry
12+
13+
No app code changes are required for common setups.
14+
15+
## Project status
16+
17+
The donation proposal to OpenTelemetry community was accepted and this repository is developed as `opentelemetry-php-distro`.
18+
The project is actively developed in collaboration with OpenTelemetry maintainers.
19+
20+
- Donation proposal: [open-telemetry/community#2846](https://github.com/open-telemetry/community/issues/2846)
21+
22+
## What is this project?
23+
24+
OpenTelemetry PHP Distro is a production-focused distribution for instrumenting PHP applications with OpenTelemetry.
25+
26+
The distro combines:
27+
28+
- native PHP extension and loader (`.so` artifacts)
29+
- PHP runtime/bootstrap logic
30+
- auto-instrumentation dependencies for popular libraries/frameworks
31+
- packaging scripts for Linux distributions
32+
33+
The goal is to provide a consistent, packaged, and testable way to enable telemetry (traces/metrics/log-related signals as supported by the underlying components) in PHP workloads.
34+
35+
## Key features
36+
37+
- Native OS packages for `deb`, `rpm`, and `apk` workflows
38+
- Automatic bootstrap and auto-instrumentation after installation
39+
- Background telemetry sending (non-blocking)
40+
- Inferred spans and automatic root span creation
41+
- URL grouping for transaction/root spans
42+
- Native OTLP protobuf serialization (no separate `ext-protobuf` requirement)
43+
- Support for PHP `8.1` to `8.4`
44+
45+
## Quick start (60s)
46+
47+
1. Install the distro package for your platform (`deb`, `rpm`, or `apk`).
48+
2. Set `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS`.
49+
3. Restart your PHP process and verify traces in your backend.
50+
51+
Full setup guide: [docs/getting-started/setup.md](docs/getting-started/setup.md)
52+
53+
## Why use it?
54+
55+
- Provides one integrated distribution instead of assembling native + PHP parts manually.
56+
- Supports multiple PHP versions and Linux package formats.
57+
- Uses OpenTelemetry ecosystem components (SDK/exporters/instrumentations).
58+
- After package installation, the agent is loaded automatically after restarting PHP processes.
59+
60+
## Relationship to other OTel PHP projects
61+
62+
OpenTelemetry PHP Distro is complementary to `opentelemetry-php` and `opentelemetry-php-instrumentation`.
63+
64+
- Choose the distro when you want package-managed, production-first, zero-code onboarding.
65+
- Choose Composer-centric instrumentation when you need maximum manual control or platform flexibility.
66+
67+
## Supported matrix
68+
69+
- PHP: `8.1`, `8.2`, `8.3`, `8.4`
70+
- Package types: `deb`, `rpm`, `apk`
71+
- Build architectures used in tooling: `linux-x86-64`, `linuxmusl-x86-64`, `linux-arm64`, `linuxmusl-arm64`
72+
73+
## Development
74+
75+
For contributor workflows, local build/test commands, and advanced development options, see [DEVELOPMENT.md](DEVELOPMENT.md).
76+
77+
## Repository structure (high level)
78+
79+
- `prod/native` — native extension, loader, C/C++ code, Conan/CMake build logic
80+
- `prod/php` — PHP runtime/bootstrap and distro PHP code
81+
- `packaging` — package metadata and install/uninstall scripts
82+
- `tools/build` — build/test/package scripts used locally and in CI
83+
- `tests` — unit/component and integration-oriented tests
84+
85+
## Documentation
86+
87+
- Documentation index: [docs/README.md](docs/README.md)
88+
- Setup and installation: [docs/getting-started/setup.md](docs/getting-started/setup.md)
89+
- Limitations: [docs/getting-started/limitations.md](docs/getting-started/limitations.md)
90+
- Configuration reference: [docs/reference/configuration.md](docs/reference/configuration.md)
91+
- Supported technologies: [docs/reference/supported-technologies.md](docs/reference/supported-technologies.md)
92+
- Performance overhead: [docs/reference/performance-overhead.md](docs/reference/performance-overhead.md)
93+
- Development guide: [DEVELOPMENT.md](DEVELOPMENT.md)
94+
- Dockerized build images: [prod/native/building/dockerized/README.md](prod/native/building/dockerized/README.md)
495

596
## Maintainers
697

@@ -15,3 +106,4 @@ For more information about the maintainer role, see the [community repository](h
15106
- [@SergeyKleyman](https://github.com/SergeyKleyman)
16107

17108
For more information about the approver role, see the [community repository](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md#approver).
109+

‎docs/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Documentation
2+
3+
Documentation for OpenTelemetry PHP Distro.
4+
5+
## Getting started
6+
7+
- [Setup and installation](getting-started/setup.md)
8+
- [Limitations](getting-started/limitations.md)
9+
10+
## Reference
11+
12+
- [Configuration](reference/configuration.md)
13+
- [Supported technologies](reference/supported-technologies.md)
14+
- [Performance overhead](reference/performance-overhead.md)

‎docs/getting-started/limitations.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Limitations
2+
3+
This page describes known limitations and constraints of OpenTelemetry PHP Distro.
4+
5+
## Running with another PHP telemetry agent
6+
7+
Do not run OpenTelemetry PHP Distro together with another PHP APM or OpenTelemetry agent in the same process. Running both can cause conflicts, duplicate instrumentation, and unstable behavior.
8+
9+
## `open_basedir`
10+
11+
If `open_basedir` is enabled in `php.ini`, the distro installation path must be included in allowed paths, otherwise the agent may fail to load.
12+
13+
## `xdebug`
14+
15+
Running with `xdebug` is not recommended in production and may cause stability or memory issues in instrumented processes.

‎docs/getting-started/setup.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Set up OpenTelemetry PHP Distro
2+
3+
Learn how to instrument your PHP application with OpenTelemetry PHP Distro and send telemetry data to an OTLP-compatible backend.
4+
5+
## Prerequisites
6+
7+
- Have a destination for telemetry data (OTLP endpoint).
8+
- Use a supported Linux and PHP version.
9+
- Do not run another PHP APM or OpenTelemetry agent in the same process.
10+
11+
For supported operating systems and PHP versions, see [Supported technologies](../reference/supported-technologies.md).
12+
13+
## Limitations
14+
15+
Known runtime and compatibility limitations are described in [Limitations](limitations.md).
16+
17+
## Download and install packages
18+
19+
Download a package for your platform from the project releases and install it.
20+
21+
### RPM (RHEL/CentOS/Fedora)
22+
23+
```bash
24+
sudo rpm -ivh <package-file>.rpm
25+
```
26+
27+
### DEB (Debian/Ubuntu)
28+
29+
```bash
30+
sudo dpkg -i <package-file>.deb
31+
```
32+
33+
### APK (Alpine)
34+
35+
```bash
36+
sudo apk add --allow-untrusted <package-file>.apk
37+
```
38+
39+
## Configure exporter
40+
41+
At a minimum, set:
42+
43+
- `OTEL_EXPORTER_OTLP_ENDPOINT`
44+
- `OTEL_EXPORTER_OTLP_HEADERS`
45+
46+
Example:
47+
48+
```bash
49+
export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-otlp-endpoint:443/"
50+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
51+
```
52+
53+
## Restart PHP processes
54+
55+
After installation and configuration, restart PHP processes (for example `php-fpm`, Apache workers, or long-running CLI workers) so the extension loads.
56+
57+
## Confirm telemetry
58+
59+
1. Open your observability backend.
60+
2. Find your service in traces.
61+
3. Generate traffic if no traces are visible yet.
62+
63+
## Troubleshooting
64+
65+
- Verify configuration options in [Configuration](../reference/configuration.md).
66+
- Check known constraints in [Limitations](limitations.md).

‎docs/reference/configuration.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Configuration
2+
3+
OpenTelemetry PHP Distro supports standard OpenTelemetry SDK configuration and distro-specific options.
4+
5+
## Configuration method
6+
7+
Configure via environment variables available to PHP processes:
8+
9+
- `OTEL_*` for OpenTelemetry standard options
10+
- `OTEL_PHP_*` for distro-specific options
11+
12+
Example:
13+
14+
```bash
15+
export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-endpoint:443/"
16+
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
17+
export OTEL_PHP_LOG_LEVEL_STDERR="INFO"
18+
```
19+
20+
## OpenTelemetry options
21+
22+
The distro supports standard OpenTelemetry PHP SDK options.
23+
24+
| Option | Default | Accepted values | Description |
25+
| --- | --- | --- | --- |
26+
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318` | URL | OTLP endpoint URL |
27+
| `OTEL_EXPORTER_OTLP_HEADERS` | (empty) | `key=value,key2=value2` | OTLP request headers |
28+
| `OTEL_EXPORTER_OTLP_INSECURE` | `false` | `true` or `false` | Disable TLS verification (testing only) |
29+
| `OTEL_EXPORTER_OTLP_CERTIFICATE` | (empty) | Filesystem path (PEM) | CA certificate path for OTLP TLS |
30+
| `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE` | (empty) | Filesystem path (PEM) | Client certificate for OTLP mTLS |
31+
| `OTEL_EXPORTER_OTLP_CLIENT_KEY` | (empty) | Filesystem path (PEM) | Client key for OTLP mTLS |
32+
| `OTEL_EXPORTER_OTLP_CLIENT_KEYPASS` | (empty) | String | Passphrase for encrypted OTLP client key |
33+
| `OTEL_SERVICE_NAME` | `unknown_service` | String | Value of `service.name` resource attribute |
34+
| `OTEL_RESOURCE_ATTRIBUTES` | (empty) | `key=value,key2=value2` | Resource attributes |
35+
| `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | Sampler name | Trace sampler |
36+
| `OTEL_TRACES_SAMPLER_ARG` | (empty) | String/number | Sampler argument |
37+
| `OTEL_LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug` | SDK internal log level |
38+
39+
## Distro-specific options (`OTEL_PHP_*`)
40+
41+
All `OTEL_PHP_*` options can be set as environment variables or in `php.ini`.
42+
43+
For `php.ini`, use the `opentelemetry_distro.` prefix and lowercase option names.
44+
45+
Example:
46+
47+
```bash
48+
export OTEL_PHP_ENABLED=true
49+
```
50+
51+
```ini
52+
opentelemetry_distro.enabled=true
53+
```
54+
55+
### General configuration
56+
57+
| Option | Default | Accepted values | Description |
58+
| --- | --- | --- | --- |
59+
| `OTEL_PHP_ENABLED` | `true` | `true` or `false` | Enables automatic bootstrap |
60+
| `OTEL_PHP_NATIVE_OTLP_SERIALIZER_ENABLED` | `true` | `true` or `false` | Enables native OTLP protobuf serializer |
61+
62+
### Asynchronous data sending
63+
64+
| Option | Default | Accepted values | Description |
65+
| --- | --- | --- | --- |
66+
| `OTEL_PHP_ASYNC_TRANSPORT` | `true` | `true` or `false` | Enables background transfer of telemetry |
67+
| `OTEL_PHP_ASYNC_TRANSPORT_SHUTDOWN_TIMEOUT` | `30s` | Duration (`ms`, `s`, `m`) | Flush timeout at shutdown |
68+
| `OTEL_PHP_MAX_SEND_QUEUE_SIZE` | `2MB` | Integer with optional `B`, `MB`, `GB` | Max async buffer size per worker |
69+
70+
### Logging
71+
72+
| Option | Default | Accepted values | Description |
73+
| --- | --- | --- | --- |
74+
| `OTEL_PHP_LOG_FILE` | (empty) | Filesystem path | Log output file path |
75+
| `OTEL_PHP_LOG_LEVEL_FILE` | `OFF` | `OFF`, `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, `TRACE` | File sink log level |
76+
| `OTEL_PHP_LOG_LEVEL_STDERR` | `OFF` | `OFF`, `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, `TRACE` | Stderr sink log level |
77+
| `OTEL_PHP_LOG_LEVEL_SYSLOG` | `OFF` | `OFF`, `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, `TRACE` | Syslog sink log level |
78+
| `OTEL_PHP_LOG_FEATURES` | (empty) | `FEATURE=LEVEL,...` | Per-feature log levels |
79+
80+
### Transaction span
81+
82+
| Option | Default | Accepted values | Description |
83+
| --- | --- | --- | --- |
84+
| `OTEL_PHP_TRANSACTION_SPAN_ENABLED` | `true` | `true` or `false` | Auto root span for web SAPI |
85+
| `OTEL_PHP_TRANSACTION_SPAN_ENABLED_CLI` | `true` | `true` or `false` | Auto root span for CLI |
86+
| `OTEL_PHP_TRANSACTION_URL_GROUPS` | (empty) | Comma-separated wildcards | URL grouping patterns |
87+
88+
### Inferred spans
89+
90+
| Option | Default | Accepted values | Description |
91+
| --- | --- | --- | --- |
92+
| `OTEL_PHP_INFERRED_SPANS_ENABLED` | `false` | `true` or `false` | Enables inferred spans |
93+
| `OTEL_PHP_INFERRED_SPANS_REDUCTION_ENABLED` | `true` | `true` or `false` | Reduces consecutive duplicate frames |
94+
| `OTEL_PHP_INFERRED_SPANS_STACKTRACE_ENABLED` | `true` | `true` or `false` | Attaches stacktrace to inferred spans |
95+
| `OTEL_PHP_INFERRED_SPANS_SAMPLING_INTERVAL` | `50ms` | Duration (`ms`, `s`, `m`) | Stacktrace sampling interval |
96+
| `OTEL_PHP_INFERRED_SPANS_MIN_DURATION` | `0` | Duration (`ms`, `s`, `m`) | Minimum inferred span duration |
97+
98+
### Central configuration (OpAMP)
99+
100+
| Option | Default | Accepted values | Description |
101+
| --- | --- | --- | --- |
102+
| `OTEL_PHP_OPAMP_ENDPOINT` | (empty) | HTTP/HTTPS URL ending with `/v1/opamp` | OpAMP endpoint |
103+
| `OTEL_PHP_OPAMP_HEADERS` | (empty) | `key=value,key2=value2` | OpAMP request headers |
104+
| `OTEL_PHP_OPAMP_HEARTBEAT_INTERVAL` | `30s` | Duration (`ms`, `s`, `m`) | OpAMP heartbeat interval |
105+
| `OTEL_PHP_OPAMP_SEND_TIMEOUT` | `10s` | Duration (`ms`, `s`, `m`) | OpAMP send timeout |
106+
| `OTEL_PHP_OPAMP_SEND_MAX_RETRIES` | `3` | Integer >= 0 | Retry count |
107+
| `OTEL_PHP_OPAMP_SEND_RETRY_DELAY` | `10s` | Duration (`ms`, `s`, `m`) | Retry delay |
108+
| `OTEL_PHP_OPAMP_INSECURE` | `false` | `true` or `false` | Disable TLS verification (testing only) |
109+
| `OTEL_PHP_OPAMP_CERTIFICATE` | (empty) | Filesystem path (PEM) | CA certificate path for OpAMP TLS |
110+
| `OTEL_PHP_OPAMP_CLIENT_CERTIFICATE` | (empty) | Filesystem path (PEM) | Client certificate path for OpAMP mTLS |
111+
| `OTEL_PHP_OPAMP_CLIENT_KEY` | (empty) | Filesystem path (PEM) | Client key path for OpAMP mTLS |
112+
| `OTEL_PHP_OPAMP_CLIENT_KEYPASS` | (empty) | String | Passphrase for encrypted client key |
113+
114+
## Notes
115+
116+
- Background transfer works with OTLP HTTP/protobuf mode.
117+
- `OTEL_PHP_AUTOLOAD_ENABLED` is enforced as enabled by the distro runtime.

‎docs/reference/performance-overhead.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Performance overhead
2+
3+
This document outlines performance implications of using OpenTelemetry PHP Distro and provides guidance for minimizing overhead.
4+
5+
Like any instrumentation agent, the distro runs in application processes and adds runtime cost. The exact impact depends on architecture, configuration, deployment environment, and workload.
6+
7+
The benchmark below compares multiple PHP observability variants in a local Docker setup (`PHP-FPM 8.2 + NGINX`). In scenarios with a collector, the collector also runs locally and shares host CPU resources.
8+
9+
## Benchmark setup
10+
11+
- Application: Laravel/Aimeos on PHP-FPM 8.2
12+
- Environment: local Docker with NGINX
13+
- Telemetry destinations: OTLP-compatible endpoints
14+
15+
## Results
16+
17+
| Variant | Avg. time per request [ms] | Overhead [ms] |
18+
| --- | ---: | ---: |
19+
| No agent | 17.36 | 0.00 |
20+
| Vendor-specific APM agent | 20.63 | 3.27 |
21+
| OpenTelemetry PHP Distro | 23.08 | 5.71 |
22+
| OpenTelemetry PHP Distro + local collector | 24.37 | 7.01 |
23+
| Vanilla OpenTelemetry PHP + protobuf (C extension) + collector | 25.76 | 8.40 |
24+
| Vanilla OpenTelemetry PHP pure-PHP protobuf export + collector | 49.02 | 31.66 |
25+
| Vanilla OpenTelemetry PHP pure-PHP protobuf export | 2158.58 | 2141.22 |
26+
27+
## Key findings
28+
29+
- OpenTelemetry PHP Distro significantly reduces overhead compared to vanilla OpenTelemetry PHP with pure-PHP protobuf export.
30+
- Local collector placement can increase overhead when it contends for CPU with PHP workers.
31+
- Pure-PHP protobuf export in vanilla OpenTelemetry PHP introduces very high overhead under this benchmark.
32+
33+
## Recommendations
34+
35+
- Measure overhead in your own workload and infrastructure.
36+
- Prefer OTLP HTTP/protobuf with asynchronous transport.
37+
- Avoid colocating heavy collector workloads with latency-sensitive application workers.
38+
- Tune sampling and exporter settings to meet your SLOs.

0 commit comments

Comments
 (0)