Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Correct error in DEVELOPMENT.md/README.md #736

Merged
merged 1 commit into from
Jun 29, 2022
Merged

Correct error in DEVELOPMENT.md/README.md #736

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 186 additions & 1 deletion DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.**
Expand All @@ -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`
151 changes: 6 additions & 145 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. \
Expand All @@ -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/)

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down