OpenTelemetry php library

Current Project Status

This project currently lives in a alpha status. Our current release is not production ready; it has been created in order to receive feedback from the community.
As long as this project is in alpha status, things may and probably will break once in a while.
We aim to provide backward compatibility (without any guarantee) even for alpha releases, however the library will raise notices indicating breaking changes and what to do about them.
If you don't want these notices to appear or change the error message level, you can do so by calling:

OpenTelemetry\SDK\Common\Dev\Compatibility\Util::setErrorLevel(0)

to turn messages off completely, or (for example)

OpenTelemetry\SDK\Common\Dev\Compatibility\Util::setErrorLevel(E_USER_DEPRECATED)

to trigger only deprecation notices. Valid error levels are 0 (none), E_USER_DEPRECATED, E_USER_NOTICE, E_USER_WARNING and E_USER_ERROR
However (as long as in alpha) it is safer to pin a dependency on the library to a specific version and/or make the adjustments mentioned in the provided messages, since doing otherwise may break things completely for you in the future!

There is a supplemental repository for OpenTelemetry PHP contributions that are not part of the core distribution of the library. Typically, these contributions are vendor specific receivers/exporters and/or components that are only useful to a relatively small number of users. This repository can be found here.

We attempt to keep the OpenTelemetry Specification Matrix up to date in order to show which features are available and which have not yet been implemented.

If you find an inconsistency in the data in the matrix vs. the data in this repository, please let us know in our slack channel and we'll get it rectified.

Communication

Most of our communication is done on CNCF Slack in the channel otel-php. To sign up, create a CNCF Slack account here

Our meetings are held weekly on zoom on Wednesdays at 10:30am PST / 1:30pm EST.
A Google calendar invite with the included zoom link can be found here

Our open issues can all be found in the GitHub issues tab. Feel free to reach out on Slack if you have any additional questions about these issues; we are always happy to talk through implementation details.

Requirements

The library requires a PHP version of 7.4.x, 8.0.x or 8.1.x

Dependencies

REQUIRED DEPENDENCIES

1) Install PSR17/18 implementations

The library has a dependency on both a HTTP Factories (PSR17) and a php-http/async-client implementation. You can find appropriate composer packages implementing given standards on packagist.org. Follow this link to find a PSR17 (HTTP factories) implementation, and this link to find a php-http/async-client implementation.

OPTIONAL DEPENDENCIES

1) Install PHP ext-grpc

The PHP gRPC extension is only needed, if you want to use the OTLP GRPC Exporter.

Three ways to install the gRPC extension are described below. Keep in mind, that whatever way to install the extension you choose, the compilation can take up to 10-15 minutes. (As an alternative you can search for a pre-compiled extension binary for your OS and PHP version, or you might be lucky and the package manager of your OS provides a package for the extension)

Installation with pecl installer (which should come with your PHP installation):

[sudo] pecl install grpc

Installation with pickle installer (which you can find here):

[sudo] pickle install grpc

Manually compiling the extension, which is not really complicated either, but you should know what you are doing, so we won't cover it here.

Notice: The artifact of the gRPC extension can be as large as 100mb (!!!), Some 'hacks' to reduce that size, are mentioned in this thread. Use at your own risk.

2) Install PHP ext-mbstring

The library will load the symfony/polyfill-mbstring package, but for better performance you should install the PHP mbstring extension. You can use the same install methods as described for the gRPC extension above, however most OS` package managers provide a package for the extension.

3) Install PHP ext-zlib

In order to use compression in HTTP requests you should install the PHP zlib extension. You can use the same install methods as described for the gRPC extension above, however most OS` package managers provide a package for the extension.

4) Install PHP ext-ffi

Experimental support for using fibers in PHP 8.1 for Context storage requires the ffi extension, and can be enabled by setting the OTEL_PHP_FIBERS_ENABLED environment variable to a truthy value (1, true, on).

Using fibers with non-CLI SAPIs may require preloading of bindings. One way to achieve this is setting ffi.preload to src/Context/fiber/zend_observer_fiber.h and setting opcache.preload to vendor/autoload.php.

5) Install PHP ext-protobuf

The PHP protobuf extension is optional when using either the OTLPHttp or OTLPGrpc exporters.

The protobuf extension makes both exporters more performant. Note that protobuf 3.20.0+ is required for php 8.1 support

Installation

The recommended way to install the library is through Composer:

Install the composer package using Composer's installation instructions.
Add

 "minimum-stability": "dev"

To your project's composer.json file, as this utility has not reached a stable release status yet.

Install the dependency with composer:

$ composer require open-telemetry/opentelemetry

Development

For repeatability and consistency across different operating systems, we use the 3 Musketeers pattern. If you're on Windows, it might be a good idea to use Git bash for following the steps below.

Note: After cloning the repository, copy .env.dist to .env.

Skipping the step above would result in a "The "PHP_USER" variable is not set. Defaulting to a blank string" warning

We use docker and docker-compose to perform a lot of our static analysis and testing. If you're planning to develop for this library, it'll help to install docker engine and docker-compose.

The installation instructions for these tools are here, under the Docker Engine and Docker Compose submenus respectively.

To ensure you have all the correct packages installed locally in your dev environment, you can run

make install

This will install all the library dependencies to the /vendor directory.

To update these dependencies, you can run

make update

Pull Requests

To propose changes to the codebase, you need to open a pull request to the opentelemetry-php project.

After you open the pull request, the CI will run all the associated github actions.

To ensure your PR doesn't emit a failure with GitHub actions, it's recommended that you run important the CI tests locally with the following command:

make all

This does the following things:

Installs/updates all the required dependencies for the project
Uses php-cs-fixer to style your code using our style preferences.
Runs all of our phpunit unit tests.
Performs static analysis with Phan, Psalm and PHPStan

Other PHP versions

We aim to support officially supported PHP versions, according to https://www.php.net/supported-versions.php. The developer image ghcr.io/open-telemetry/opentelemetry-php/opentelemetry-php-base is tagged as 7.4, 8.0 and 8.1 respectively, with 7.4 being the default. You can execute the test suite against other PHP versions by running the following command:

PHP_VERSION=8.0 make all
#or
PHP_VERSION=8.1 make all

Proto Generation

Our protobuf files are committed to the repository into the /proto folder. These are used in gRPC connections to the upstream. These get updated when the opentelemetry-proto repo has a meaningful update. The maintainer SIG is discussing a way to make this more automatic in the future.

To generate protobuf files for use with this repository, you can run the following command:

make protobuf

This will replace proto/otel/Opentelemetry and proto/otel/GPBMetadata with freshly generated code based on the latest tag from opentelemetry-proto, which can then be committed.

Semantic Conventions Generation

Autogenerated semantic convention files are committed to the repository in the /src/SemConv directory. These files get updated when new version of opentelemetry-specification released.

SEMCONV_VERSION=1.8.0 make semconv

Run this command in the root of this repository.

Styling

We use PHP-CS-Fixer for our code linting and standards fixer. The associated configuration for this standards fixer can be found in the root of the repository here

To ensure that your code follows our coding standards, you can run:

make style

This command executes a required test that also runs during CI. This process performs the required fixes and prints them out. Code that doesn't meet the style pattern will emit a failure with GitHub actions.

Static Analysis

We use Phan for static analysis. Currently, our phan configuration is just a standard default analysis configuration. You can use our phan docker wrapper to easily perform static analysis on your changes.

To run Phan, one can run the following command:

make phan

This process will return 0 on success. Usually this process is performed as part of a code checkin. This process runs during CI and is a required check. Code that doesn't match the standards that we have defined in our phan config will emit a failure in CI.

We also use Psalm as a second static analysis tool.
You can use our psalm docker wrapper to easily perform static analysis on your changes.

To run Psalm, one can run the following command:

make psalm

We use PHPStan as our third tool for static analysis. You can use our PHPStan docker wrapper to easily perform static analysis on your changes.

To perform static analysis with PHPStan run:

make phpstan

Testing

To make sure the tests in this repo work as you expect, you can use the included docker test wrapper.
To run the test suite, execute

make test

This will output the test output as well as a test coverage analysis (text + html - see tests/coverage/html). Code that doesn't pass our currently defined tests will emit a failure in CI

PhpMetrics

To generate a report showing a variety of metrics for the library and its classes, you can run:

make phpmetrics

This will generate a HTML PhpMetrics report in the var/metrics directory. Make sure to run make test before to create the test log-file, used by the metrics report.

Examples

Trace

You can use the examples/AlwaysOnZipkinExample.php file to test out the reference implementation we have for zipkin. This example performs a sample trace with a grouping of 5 spans and POSTs the result to a local zipkin instance.

You can also use the examples/AlwaysOnJaegerExample.php file to test out the reference implementation we have for Jaeger. This example performs a sample trace with a grouping of 5 spans and POSTs the result to a local Jaeger instance.

If you'd like a no-fuss way to test this out with docker and docker-compose, you can perform the following simple steps:

Install the necessary dependencies by running make install.
Execute the example trace using make trace examples.

Exported spans can be seen in zipkin at http://127.0.0.1:9411

Exported spans can also be seen in jaeger at http://127.0.0.1:16686

Metrics

You can use the examples/prometheus/PrometheusMetricsExample.php file to test out the reference implementation we have. This example will create a counter that will be scraped by local Prometheus instance.

The easy way to test the example out with docker and docker-compose is:

Run make metrics-prometheus-example. Make sure that local ports 8080, 6379 and 9090 are available.
Open local Prometheus instance: http://localhost:9090
Go to Graph section, type "opentelemetry_prometheus_counter" in the search field or select it in the dropdown menu. You will see the counter value. Every other time you run make metrics-prometheus-example will increment the counter but remember that Prometheus scrapes values once in 10 seconds.
In order to stop docker containers for this example just run make stop-prometheus

User Integration Guides

Versioning

Versioning rationale can be found in the Versioning Documentation

yuktea / opentelemetry-php