diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index a06bc7300..5d57e6c47 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,4 +1,4 @@ -## Development +## [Development](DEVELOPMENT.md) For repeatability and consistency across different operating systems, we use the [3 Musketeers pattern](https://3musketeers.io/). 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`.** @@ -23,3 +23,188 @@ To update these dependencies, you can run ```bash make update ``` + +## Pull Requests + +To propose changes to the codebase, you need +to [open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) +to the opentelemetry-php project. + +After you open the pull request, the CI will run all the +associated [github actions](https://github.com/open-telemetry/opentelemetry-php/actions/workflows/php.yml). + +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: + +```bash +make all +``` + +This does the following things: + +* Installs/updates all the required dependencies for the project +* Uses [php-cs-fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) to style your code using our style preferences. +* Runs all of our [phpunit](https://phpunit.de/) unit tests. +* Performs static analysis with [Phan](https://github.com/phan/phan), [Psalm](https://psalm.dev/) + and [PHPStan](https://phpstan.org/user-guide/getting-started) + +### 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: + +```bash +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](https://github.com/open-telemetry/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: + +```bash +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](https://github.com/open-telemetry/opentelemetry-specification) +released. + +```bash +SEMCONV_VERSION=1.8.0 make semconv +``` + +Run this command in the root of this repository. + +## Styling + +We use [PHP-CS-Fixer](https://github.com/FriendsOfPHP/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](https://github.com/open-telemetry/opentelemetry-php/blob/master/.php_cs) + +To ensure that your code follows our coding standards, you can run: + +```bash +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](https://github.com/phan/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: + +```bash +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](https://github.com/open-telemetry/opentelemetry-php/blob/master/.phan/config.php) will emit a failure +in CI. + +We also use [Psalm](https://psalm.dev/) 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: + +```bash +make psalm +``` + +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](https://github.com/open-telemetry/opentelemetry-php/blob/main/psalm.xml.dist) will emit a failure in +CI. + +We use [PHPStan](https://github.com/phpstan/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: + +```bash +make phpstan +``` + +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](https://github.com/open-telemetry/opentelemetry-php/blob/main/phpstan.neon.dist) will emit a +failure in CI. + +## 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 + +```bash +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: + +```bash +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](/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](/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: + +1) Install the necessary dependencies by running `make install`. +2) Execute the example trace using `make trace examples`. + +Exported spans can be seen in zipkin at [http://127.0.0.1:9411](http://127.0.0.1:9411) + +Exported spans can also be seen in jaeger at [http://127.0.0.1:16686](http://127.0.0.1:16686) + +### Metrics + +You can use the [examples/prometheus/PrometheusMetricsExample.php](/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` diff --git a/README.md b/README.md index f34c32ce7..500fbd53c 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Additional packages, demos and tools are hosted or distributed in the [OpenTelem --- ## Current Project Status + ![Current Version](https://img.shields.io/github/v/tag/open-telemetry/opentelemetry-php) 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. \ @@ -58,6 +59,7 @@ If you find an inconsistency in the data in the matrix vs. the data in this repo --- ## Communication + Most of our communication is done on CNCF Slack in the channel [otel-php](https://cloud-native.slack.com/archives/C01NFPCV44V). To sign up, create a CNCF Slack account [here](http://slack.cncf.io/) @@ -67,6 +69,7 @@ A Google calendar invite with the included zoom link can be found [here](https:/ Our open issues can all be found in the [GitHub issues tab](https://github.com/open-telemetry/opentelemetry-php/issues). 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 and all separate packages requires a PHP version of 7.4.x, 8.0.x or 8.1.x ### Dependencies @@ -139,6 +142,7 @@ The protobuf extension makes both exporters more performant. _Note that protobuf --- ## Installation + The recommended way to install the library's packages is through [Composer](http://getcomposer.org): Install Composer using the [installation instructions](https://getcomposer.org/doc/00-intromd#installation-linux-unix-macos) and add @@ -190,155 +194,12 @@ For development and testing purposes you also want to install **SDK** and **Cont $ composer require --dev open-telemetry/sdk open-telemetry/sdk-contrib ``` -## [Development](DEVELOPMENT.md) - -## Pull Requests - -To propose changes to the codebase, you need to [open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) to the opentelemetry-php project. - -After you open the pull request, the CI will run all the associated [github actions](https://github.com/open-telemetry/opentelemetry-php/actions/workflows/php.yml). - -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: - -```bash -make all -``` -This does the following things: - -* Installs/updates all the required dependencies for the project -* Uses [php-cs-fixer](https://github.com/FriendsOfPHP/PHP-CS-Fixer) to style your code using our style preferences. -* Runs all of our [phpunit](https://phpunit.de/) unit tests. -* Performs static analysis with [Phan](https://github.com/phan/phan), [Psalm](https://psalm.dev/) and [PHPStan](https://phpstan.org/user-guide/getting-started) - -### 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: - -```bash -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](https://github.com/open-telemetry/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: - -```bash -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](https://github.com/open-telemetry/opentelemetry-specification) -released. - -```bash -SEMCONV_VERSION=1.8.0 make semconv -``` - -Run this command in the root of this repository. - -## Styling -We use [PHP-CS-Fixer](https://github.com/FriendsOfPHP/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](https://github.com/open-telemetry/opentelemetry-php/blob/master/.php_cs) - -To ensure that your code follows our coding standards, you can run: -```bash -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](https://github.com/phan/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: -```bash -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](https://github.com/open-telemetry/opentelemetry-php/blob/master/.phan/config.php) will emit a failure in CI. - -We also use [Psalm](https://psalm.dev/) 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: -```bash -make psalm -``` -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](https://github.com/open-telemetry/opentelemetry-php/blob/main/psalm.xml.dist) will emit a failure in CI. - -We use [PHPStan](https://github.com/phpstan/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: -```bash -make phpstan -``` -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](https://github.com/open-telemetry/opentelemetry-php/blob/main/phpstan.neon.dist) will emit a failure -in CI. - -## 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 -```bash -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: -```bash -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](/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](/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: - -1) Install the necessary dependencies by running `make install`. -2) Execute the example trace using `make trace examples`. - -Exported spans can be seen in zipkin at [http://127.0.0.1:9411](http://127.0.0.1:9411) - -Exported spans can also be seen in jaeger at [http://127.0.0.1:16686](http://127.0.0.1:16686) - -### Metrics -You can use the [examples/prometheus/PrometheusMetricsExample.php](/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` - ## User Quickstarts + * [Exploring OpenTelemetry in Laravel Applications](./docs/laravel-quickstart.md) ## Framework integrations + * [Symfony SDK Bundle](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/src/Symfony/OtelSdkBundle) is the recommended way to use opentelemetry-php with symfony ## Versioning