This project currently lives in a pre-alpha status. Our current release is not production ready; it has been created in order to receive feedback from the community.
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.
Most of our communication is done on CNCF Slack, in the otel-php channel. To sign up, create a CNCF slack account here http://slack.cncf.io/
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.
The recommended way to install the library is through Composer:
1.) Install the composer package using Composer's installation instructions.
2.) Add
"minimum-stability": "dev"To your project's composer.json file, as this utility has not reached a stable release status yet.
2.) Install the dependency with composer:
$ composer require open-telemetry/opentelemetryWe 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.
You can find installation instructions for these packages can be found 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 installFrom your bash compatible shell. This will install all of the necessary vendored libraries that the project uses to
the
/vendor directory.
To update these dependencies, you can run
make updateIn order to update all the vendored libraries in the /vendor directory.
Once you've made the update to the codebase that you'd like to submit, you may create a pull request to the opentelemetry-php project.
After you open the pull request, the CI/CD pipeline will run all of the associated github actions.
You can simulate the important github actions locally before you submit your PR by running the following command:
make install && make update && make style && make test && make phan && make psalm && make phpstanfrom your bash compatible shell. This does the following things:
- Installs all the required dependencies for the project and ensures they are up to date
- 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
Our proto 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.
If you'd like to generate proto files for use with this repository, one can run the following command:
make protoFrom your bash compatible shell in the root of this directory. This wil create a /proto folder in the root
directory of the
repository.
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 is stylish, you can run the follwing command:
make stylefrom your bash compatible shell. This process will print out the fixes that it is making to your associated files. 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 follow this style pattern will emit a failure in CI.
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 phanfrom your bash compatible shell. 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 psalmfrom your bash compatible shell. 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 psalm config will emit a failure in CI.
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.
Execute make phpstan from your bash compatible shell. 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 PHPStan config will emit a failure
in CI.
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 testfrom your bash compatible shell. This will output the test output as well as a test coverage analysis. Code that doesn't pass our currently defined tests will emit a failure in CI
You can use the examples/AlwaysOnZipkinExample.php file to test out the reference implementation we have for zipkin. This example perfoms 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 jaegar. This example perfoms a sample trace with a grouping of 5 spans and POSTs the result to a local jaegar instance.
You can use the examples/AlwaysOnZipkinToNewrelicExample.php file to test out the reference implementation we have for zipkin to Newrelic. This example perfoms a sample trace with spans and POSTs the result to a Newrelic endpoint. This requires a license key (free accounts available) to be set in the environment (NEW_RELIC_INSERT_KEY) to authenticate to the backend.
You can use the examples/AlwaysOnNewrelicExample.php file to test out the reference implementation we have for Newrelic. This example perfoms a sample trace with spans and POSTs the result to a Newrelic endpoint. This requires a license key (free accounts available) set in the environment (NEW_RELIC_INSERT_KEY) to authenticate to the backend.
The PHP for all examples should execute by itself (if you have a zipkin or jaegar instance running on localhost), but if you'd like a no-fuss way to test this out with docker and docker-compose, you can perform the following simple steps:
1.) Install the necessary dependencies by running make install. This will install the composer dependencies and store them in /vendor
2.) 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
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:
1.) Run make metrics-prometheus-example. Make sure that local ports 8080, 6379 and 9090 are available.
2.) Open local Prometheus instance: http://localhost:9090
3.) 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.
4.) In order to stop docker containers for this example just run make stop-prometheus
- Integrating OpenTelemetry PHP into Laravel Applications
- Integrating OpenTelemetry PHP into Symfony Applications
Versioning rationale can be found in the Versioning Documentation