From 49b36d328ccfcbda543f6b20eac77cc0404d36cc Mon Sep 17 00:00:00 2001 From: svrnm Date: Mon, 22 May 2023 12:03:36 +0200 Subject: [PATCH 1/5] Roll-the-dice application for PHP --- content/en/docs/instrumentation/php/_index.md | 56 +++ .../instrumentation/php/getting-started.md | 379 ++++++++---------- content/en/docs/instrumentation/php/manual.md | 20 + 3 files changed, 233 insertions(+), 222 deletions(-) diff --git a/content/en/docs/instrumentation/php/_index.md b/content/en/docs/instrumentation/php/_index.md index 504d4e42fd4e..ba5052c94472 100644 --- a/content/en/docs/instrumentation/php/_index.md +++ b/content/en/docs/instrumentation/php/_index.md @@ -13,3 +13,59 @@ weight: 21 - [OpenTelemetry for PHP on GitHub](https://github.com/open-telemetry/opentelemetry-php) - [Installation](https://github.com/open-telemetry/opentelemetry-php#installation) - [Examples](https://github.com/open-telemetry/opentelemetry-php/tree/main/examples) + +## Requirements + +OpenTelemetry for PHP requires a minimum PHP version of 7.4, and +auto-instrumentation requires version 8.0+. + +### Dependencies + +Some of the `SDK` and `Contrib` packages have a dependency on both a +[HTTP Factories (PSR17)](https://www.php-fig.org/psr/psr-17/) and a +[php-http/async-client](https://docs.php-http.org/en/latest/clients.html) +implementation. You can find appropriate composer packages implementing given +standards on [packagist.org](https://packagist.org/). + +See +[http-factory-implementations](https://packagist.org/providers/psr/http-factory-implementation) +to find a `PSR17 (HTTP factories)` implementation, and +[async-client-implementations](https://packagist.org/providers/php-http/async-client-implementation) +to find a `php-http/async-client` implementation. + +### Optional PHP extensions + +| Extension | Purpose | +| ------------------------------------------------------------------------- | ----------------------------------------------------------------- | +| [ext-grpc](https://github.com/grpc/grpc/tree/master/src/php) | Required to use gRPC as a transport for the OTLP exporter | +| [ext-mbstring](https://www.php.net/manual/en/book.mbstring.php) | More performant than the fallback, `symfony/polyfill-mbstring` | +| [ext-zlib](https://www.php.net/manual/en/book.zlib.php) | If you want to compress exported data | +| [ext-ffi](https://www.php.net/manual/en/book.ffi.php) | Fiber-based context storage | +| [ext-protobuf](https://github.com/protocolbuffers/protobuf/tree/main/php) | _Significant_ performance improvement for otlp+protobuf exporting | + +#### ext-ffi + +Fibers support 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`](https://www.php.net/manual/en/ffi.configuration.php#ini.ffi.preload) +to `src/Context/fiber/zend_observer_fiber.h` and setting +[`opcache.preload`](https://www.php.net/manual/en/opcache.preloading.php) to +`vendor/autoload.php`. + +#### ext-protobuf + +The [native protobuf library](https://packagist.org/packages/google/protobuf) is +significantly slower than the extension. We strongly encourage the use of the +extension. + +## Setup + +OpenTelemetry for PHP is distributed via +[packagist](https://packagist.org/packages/open-telemetry/), in a number of +packages. We recommend that you install only the packages that you need, which +as a minimum is usually `API`, `Context`, `SDK` and an exporter. + +We strongly encourage that your code only depend on classes and interfaces in +the `API` package. diff --git a/content/en/docs/instrumentation/php/getting-started.md b/content/en/docs/instrumentation/php/getting-started.md index 20b83c139ce2..f522e43d694c 100644 --- a/content/en/docs/instrumentation/php/getting-started.md +++ b/content/en/docs/instrumentation/php/getting-started.md @@ -3,82 +3,58 @@ title: Getting Started description: Get up and running with OpenTelemetry for PHP. aliases: [/docs/instrumentation/php/getting_started] weight: 1 +spelling: cSpell:ignore Wordpress Symfony Laravel rolldice autoload strval PECL +spelling: cSpell:ignore darwin --- -## Requirements +This page will show you how to get started with OpenTelemetry in PHP. -OpenTelemetry for PHP requires a minimum PHP version of 7.4, and -auto-instrumentation requires version 8.0+. +You will learn how you can instrument a simple java application automatically, +in such a way that [traces][], [metrics][] and [logs][] are emitted to the +console. -### Dependencies - -Some of the `SDK` and `Contrib` packages have a dependency on both a -[HTTP Factories (PSR17)](https://www.php-fig.org/psr/psr-17/) and a -[php-http/async-client](https://docs.php-http.org/en/latest/clients.html) -implementation. You can find appropriate composer packages implementing given -standards on [packagist.org](https://packagist.org/). - -See -[http-factory-implementations](https://packagist.org/providers/psr/http-factory-implementation) -to find a `PSR17 (HTTP factories)` implementation, and -[async-client-implementations](https://packagist.org/providers/php-http/async-client-implementation) -to find a `php-http/async-client` implementation. - -### Optional PHP extensions +## Prerequisites -| Extension | Purpose | -| ------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| [ext-grpc](https://github.com/grpc/grpc/tree/master/src/php) | Required to use gRPC as a transport for the OTLP exporter | -| [ext-mbstring](https://www.php.net/manual/en/book.mbstring.php) | More performant than the fallback, `symfony/polyfill-mbstring` | -| [ext-zlib](https://www.php.net/manual/en/book.zlib.php) | If you want to compress exported data | -| [ext-ffi](https://www.php.net/manual/en/book.ffi.php) | Fiber-based context storage | -| [ext-protobuf](https://github.com/protocolbuffers/protobuf/tree/main/php) | _Significant_ performance improvement for otlp+protobuf exporting | +Ensure that you have the following installed locally: open source -#### ext-ffi +- [PHP 8.0+](https://www.php.net/) +- [PECL](https://pecl.php.net/) +- [composer](https://getcomposer.org/) -Fibers support 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`](https://www.php.net/manual/en/ffi.configuration.php#ini.ffi.preload) -to `src/Context/fiber/zend_observer_fiber.h` and setting -[`opcache.preload`](https://www.php.net/manual/en/opcache.preloading.php) to -`vendor/autoload.php`. +Before you get started make sure that you have both available in your shell: -#### ext-protobuf - -The [native protobuf library](https://packagist.org/packages/google/protobuf) is -significantly slower than the extension. We strongly encourage the use of the -extension. - -## Introduction +```sh +$ php -v +$ composer -v +``` -OpenTelemetry for PHP is distributed via -[packagist](https://packagist.org/packages/open-telemetry/), in a number of -packages. We recommend that you install only the packages that you need, which -as a minimum is usually `API`, `Context`, `SDK` and an exporter. +## Example Application -We strongly encourage that your code only depend on classes and interfaces in -the `API` package. +The following example uses a basic [Slim](https://www.slimframework.com/) +application. If you are not using Slim, that's ok — you can use OpenTelemetry +PHP with other web frameworks as well, such as Wordpress, Symfony and Laravel. +For a complete list of libraries for supported frameworks, see the +[registry](/ecosystem/registry/?component=instrumentation&language=php). -## Setup +### Dependencies -Before you get started make sure that you have php and -[composer](https://getcomposer.org/download/) available in your shell: +In an empty directory create a minimal `composer.json` file in your directory: ```sh -php -v -composer -v +echo '{"require": {}, "minimum-stability": "beta", "config": {"allow-plugins": {"php-http/discovery": true}}}' > composer.json ``` In an empty directory create a minimal `composer.json` file in your directory: -```json -{ - "require": {} -} +```sh +composer require slim/slim:"4.*" +composer require slim/psr7 ``` +### Create and launch an HTTP Server + +In that same directory, create a file called `index.php` + ## Export to Console In your directory create a file called `GettingStarted.php` with the following @@ -86,198 +62,157 @@ content: ```php create() - ) -); - -$tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php'); - -$rootSpan = $tracer->spanBuilder('root')->startSpan(); -$rootScope = $rootSpan->activate(); - -try { - $span1 = $tracer->spanBuilder('foo')->startSpan(); - $scope = $span1->activate(); - try { - $span2 = $tracer->spanBuilder('bar')->startSpan(); - echo 'OpenTelemetry welcomes PHP' . PHP_EOL; - } finally { - $span2->end(); - } -} finally { - $span1->end(); - $scope->detach(); -} -$rootSpan->end(); -$rootScope->detach(); -``` +$app = AppFactory::create(); -To use the OpenTelemetry SDK for PHP you need packages that satisfy the -dependencies for `php-http/async-client-implementation` and -`psr/http-factory-implementation`, for example the Guzzle 7 HTTP Adapter -satisfies both: +$app->get('/rolldice', function (Request $request, Response $response, $args) { + $response->getBody()->write(strval(random_int(1,6))); + return $response; +}); + +$app->run(); -```sh -composer require "php-http/guzzle7-adapter" ``` -Now you can install the OpenTelemetry SDK: +Run the application with the following command and open + in your web browser to ensure it is working. ```sh -composer require open-telemetry/sdk +php -S localhost:8080 ``` -The example uses the `ConsoleSpanExporter`, which prints Spans to stdout. A Span -typically represents a single unit of work. A Trace is a grouping of Spans. +## Instrumentation + +Next, you’ll use the OpenTelemetry PHP extension to +[automatically instrument](/automatic/) the application at launch time. + +1. Since the extension is built from source, you need to setup some build tools + + {{< tabpane lang=shell persistLang=false >}} + + {{< tab "Linux (apt)" >}}sudo apt-get install gcc make autoconf{{< /tab >}} + + {{< tab "MacOS (homebrew)" >}}brew install gcc make autoconf{{< /tab >}} + + {{< /tabpane >}} + +2. Build the extension with `PECL`: + + ```sh + $ pecl install opentelemetry-beta + ``` + + {{% alert title="Note" color="warning" %}}If you want to pickle or the + docker-specific use php-extension-installer to build/install the extension, + [read the instructions here](../automatic). {{% /alert %}} + +3. Add the extension to your `php.ini` file: -Run the script: + ```ini + [opentelemetry] + extension=opentelemetry.so + ``` -```console -$ php GettingStarted.php -Starting ConsoleSpanExporter -OpenTelemetry welcomes PHP -... +4. Verify that the extension is installed and enabled: + + ```sh + $ php -m | grep opentelemetry + ``` + +5. Add additional dependencies to your application, which are required for the + automatic instrumentation of your code: + + ```sh + $ composer require php-http/guzzle7-adapter open-telemetry/sdk open-telemetry/opentelemetry-auto-slim + ``` + +With the OpenTelemetry PHP extension set up you can now run your application and +automatically instrument it at launch time: + +```sh +env OTEL_PHP_AUTOLOAD_ENABLED=true OTEL_TRACES_EXPORTER=console OTEL_METRICS_EXPORTER=none OTEL_LOGS_EXPORTER=none php -S localhost:8080 ``` -You'll see output similar to the following, which shows 3 spans within a single -trace: +Open in your web browser and reload the page a +few times. After a while you should see the spans printed to your console: + +
+View example output ```json -{ - "name": "bar", +[ + { + "name": "GET /rolldice", "context": { - "trace_id": "e7bc999fb17f453c6e6445802ba1e558", - "span_id": "24afe9c453481636", - "trace_state": null + "trace_id": "16d7c6da7c021c574205736527816eb7", + "span_id": "268e52331de62e33", + "trace_state": "" }, - "parent_span_id": "c63030cc93c48641", - "kind": "KIND_INTERNAL", - "start": 1635373538696880128, - "end": 1635373538697000960, - "attributes": [], - "status": { - "code": "Unset", - "description": "" - }, - "events": [] -} -{ - "name": "foo", - "context": { - "trace_id": "e7bc999fb17f453c6e6445802ba1e558", - "span_id": "c63030cc93c48641", - "trace_state": null - }, - "parent_span_id": "4e6396224842fc15", - "kind": "KIND_INTERNAL", - "start": 1635373538696482048, - "end": 1635373538700564992, - "attributes": [], - "status": { - "code": "Unset", - "description": "" - }, - "events": [] -} -{ - "name": "root", - "context": { - "trace_id": "e7bc999fb17f453c6e6445802ba1e558", - "span_id": "4e6396224842fc15", - "trace_state": null + "resource": { + "service.name": "__root__", + "service.version": "1.0.0+no-version-set", + "telemetry.sdk.name": "opentelemetry", + "telemetry.sdk.language": "php", + "telemetry.sdk.version": "1.0.0beta10", + "telemetry.auto.version": "1.0.0beta5", + "process.runtime.name": "cli-server", + "process.runtime.version": "8.2.6", + "process.pid": 24435, + "process.executable.path": "/bin/php", + "process.owner": "php", + "os.type": "darwin", + "os.description": "22.4.0", + "os.name": "Darwin", + "os.version": "Darwin Kernel Version 22.4.0: Mon Mar 6 20:59:28 PST 2023; root:xnu-8796.101.5~3/RELEASE_ARM64_T6000", + "host.name": "OPENTELEMETRY-PHP", + "host.arch": "arm64" }, "parent_span_id": "", - "kind": "KIND_INTERNAL", - "start": 1635373538691308032, - "end": 1635373538700800000, - "attributes": [], + "kind": "KIND_SERVER", + "start": 1684749478068582482, + "end": 1684749478072715774, + "attributes": { + "code.function": "handle", + "code.namespace": "Slim\\App", + "code.filepath": "/vendor/slim/slim/Slim/App.php", + "code.lineno": 197, + "http.url": "http://localhost:8080/rolldice", + "http.method": "GET", + "http.request_content_length": "", + "http.scheme": "http", + "http.status_code": 200, + "http.flavor": "1.1", + "http.response_content_length": "" + }, "status": { - "code": "Unset", - "description": "" + "code": "Unset", + "description": "" }, - "events": [] -} + "events": [], + "links": [] + } +] ``` -## Export to collector - -The next step is to modify the code to send spans to the collector via OTLP -instead of the console. +
-This will require the installation of the otlp exporter: - -```shell -composer require open-telemetry/exporter-otlp -``` +## What's next? -Next, using the `GettingStarted.php` from earlier, replace the console exporter -with an OTLP exporter: - -```php -create('http://collector:4318/v1/traces', 'application/x-protobuf'); -$exporter = new SpanExporter($transport); - -$tracerProvider = new TracerProvider( - new SimpleSpanProcessor( - $exporter - ) -); - -$tracer = $tracerProvider->getTracer('io.opentelemetry.contrib.php'); - -$rootSpan = $tracer->spanBuilder('root')->startSpan(); -$rootScope = $rootSpan->activate(); - -try { - $span1 = $tracer->spanBuilder('foo')->startSpan(); - $scope = $span1->activate(); - try { - $span2 = $tracer->spanBuilder('bar')->startSpan(); - echo 'OpenTelemetry welcomes PHP' . PHP_EOL; - } finally { - $span2->end(); - } -} finally { - $span1->end(); - $scope->detach(); -} -$rootSpan->end(); -$rootScope->detach(); -``` - -Run the PHP application: - -```console -$ php GettingStarted.php -Starting OtlpHttpExporter -OpenTelemetry welcomes PHP -``` +- Run this example with another [exporter][] for telemetry data. +- Try [automatic instrumentation](../automatic/) on one of your own apps. +- Learn about [manual instrumentation][] and try out more + [examples](/docs/instrumentation/java/examples/). -Now, telemetry will be exported to the collector. +[traces]: /docs/concepts/signals/traces/ +[metrics]: /docs/concepts/signals/metrics/ +[logs]: /docs/concepts/signals/logs/ +[exporter]: + https://github.com/open-telemetry/opentelemetry-java/blob/main/sdk-extensions/autoconfigure/README.md#exporters +[manual instrumentation]: ../manual diff --git a/content/en/docs/instrumentation/php/manual.md b/content/en/docs/instrumentation/php/manual.md index 07c1d2a2a7a5..fb2c341f3fad 100644 --- a/content/en/docs/instrumentation/php/manual.md +++ b/content/en/docs/instrumentation/php/manual.md @@ -13,6 +13,26 @@ depend on the `opentelemetry-sdk` package, or any other implementation of the OpenTelemetry API. This way, libraries will obtain a real implementation only if the user application is configured for it. +## Installation + +The following shows how to install, initialize, and run an application +instrumented with OpenTelemetry. + +To use the OpenTelemetry SDK for PHP you need packages that satisfy the +dependencies for `php-http/async-client-implementation` and +`psr/http-factory-implementation`, for example the Guzzle 7 HTTP Adapter +satisfies both: + +```sh +composer require "php-http/guzzle7-adapter" +``` + +Now you can install the OpenTelemetry SDK: + +```sh +composer require open-telemetry/sdk +``` + ## Tracing ### Setup From 801312d02333ea8ac9cbce7b32b15ca4f99f54f2 Mon Sep 17 00:00:00 2001 From: svrnm Date: Mon, 22 May 2023 14:41:49 +0200 Subject: [PATCH 2/5] fix links --- .../docs/instrumentation/php/getting-started.md | 2 +- static/refcache.json | 16 ++++++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/content/en/docs/instrumentation/php/getting-started.md b/content/en/docs/instrumentation/php/getting-started.md index f522e43d694c..ae0bf988b17f 100644 --- a/content/en/docs/instrumentation/php/getting-started.md +++ b/content/en/docs/instrumentation/php/getting-started.md @@ -89,7 +89,7 @@ php -S localhost:8080 ## Instrumentation Next, you’ll use the OpenTelemetry PHP extension to -[automatically instrument](/automatic/) the application at launch time. +[automatically instrument](../automatic) the application at launch time. 1. Since the extension is built from source, you need to setup some build tools diff --git a/static/refcache.json b/static/refcache.json index e994805684cb..d89bbd38ca65 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -1443,6 +1443,10 @@ "StatusCode": 206, "LastSeen": "2023-02-15T21:26:28.637715-05:00" }, + "https://getcomposer.org/": { + "StatusCode": 200, + "LastSeen": "2023-05-22T14:37:50.903169+02:00" + }, "https://getcomposer.org/download/": { "StatusCode": 200, "LastSeen": "2023-02-15T21:25:27.904356-05:00" @@ -3559,6 +3563,10 @@ "StatusCode": 206, "LastSeen": "2023-02-18T09:19:14.053259-05:00" }, + "https://pecl.php.net/": { + "StatusCode": 206, + "LastSeen": "2023-05-22T14:37:49.798026+02:00" + }, "https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs": { "StatusCode": 200, "LastSeen": "2023-02-18T09:19:08.332591-05:00" @@ -4511,6 +4519,10 @@ "StatusCode": 206, "LastSeen": "2023-02-28T03:33:35.061283512Z" }, + "https://www.php.net/": { + "StatusCode": 200, + "LastSeen": "2023-05-22T14:37:49.249509+02:00" + }, "https://www.php.net/manual/en/book.ffi.php": { "StatusCode": 200, "LastSeen": "2023-03-29T03:57:50.206342903Z" @@ -4623,6 +4635,10 @@ "StatusCode": 206, "LastSeen": "2023-02-18T13:46:09.073514-05:00" }, + "https://www.slimframework.com/": { + "StatusCode": 206, + "LastSeen": "2023-05-22T14:37:51.429125+02:00" + }, "https://www.splunk.com/en_us/blog/conf-splunklive/announcing-native-opentelemetry-support-in-splunk-apm.html": { "StatusCode": 200, "LastSeen": "2023-02-18T13:34:28.98952-05:00" From f0a2a0061044b00903f140cd7d626f8f42cd5884 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Wed, 24 May 2023 08:56:46 +0200 Subject: [PATCH 3/5] Update content/en/docs/instrumentation/php/getting-started.md Co-authored-by: Brett McBride --- content/en/docs/instrumentation/php/getting-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/instrumentation/php/getting-started.md b/content/en/docs/instrumentation/php/getting-started.md index ae0bf988b17f..051abe6e10c9 100644 --- a/content/en/docs/instrumentation/php/getting-started.md +++ b/content/en/docs/instrumentation/php/getting-started.md @@ -9,7 +9,7 @@ spelling: cSpell:ignore darwin This page will show you how to get started with OpenTelemetry in PHP. -You will learn how you can instrument a simple java application automatically, +You will learn how you can instrument a simple PHP application automatically, in such a way that [traces][], [metrics][] and [logs][] are emitted to the console. From 6a4ebbb6a12d7f3086351b1031c8abf71af837c0 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Wed, 24 May 2023 08:56:59 +0200 Subject: [PATCH 4/5] Update content/en/docs/instrumentation/php/_index.md Co-authored-by: Brett McBride --- content/en/docs/instrumentation/php/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/instrumentation/php/_index.md b/content/en/docs/instrumentation/php/_index.md index ba5052c94472..c81a436d5b26 100644 --- a/content/en/docs/instrumentation/php/_index.md +++ b/content/en/docs/instrumentation/php/_index.md @@ -46,7 +46,7 @@ to find a `php-http/async-client` implementation. #### ext-ffi Fibers support can be enabled by setting the `OTEL_PHP_FIBERS_ENABLED` -environment variable to a truthy value (`1`, `true`, `on`). Using fibers with +environment variable to `true`. Using fibers with non-`CLI` SAPIs may require preloading of bindings. One way to achieve this is setting [`ffi.preload`](https://www.php.net/manual/en/ffi.configuration.php#ini.ffi.preload) From eb54f5b24420a551d3873051da5d6eab408e343c Mon Sep 17 00:00:00 2001 From: svrnm Date: Wed, 24 May 2023 09:02:52 +0200 Subject: [PATCH 5/5] fix format --- content/en/docs/instrumentation/php/_index.md | 5 ++--- content/en/docs/instrumentation/php/getting-started.md | 5 ++--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/content/en/docs/instrumentation/php/_index.md b/content/en/docs/instrumentation/php/_index.md index c81a436d5b26..77aaf6ca24c3 100644 --- a/content/en/docs/instrumentation/php/_index.md +++ b/content/en/docs/instrumentation/php/_index.md @@ -46,9 +46,8 @@ to find a `php-http/async-client` implementation. #### ext-ffi Fibers support can be enabled by setting the `OTEL_PHP_FIBERS_ENABLED` -environment variable to `true`. Using fibers with -non-`CLI` SAPIs may require preloading of bindings. One way to achieve this is -setting +environment variable to `true`. Using fibers with non-`CLI` SAPIs may require +preloading of bindings. One way to achieve this is setting [`ffi.preload`](https://www.php.net/manual/en/ffi.configuration.php#ini.ffi.preload) to `src/Context/fiber/zend_observer_fiber.h` and setting [`opcache.preload`](https://www.php.net/manual/en/opcache.preloading.php) to diff --git a/content/en/docs/instrumentation/php/getting-started.md b/content/en/docs/instrumentation/php/getting-started.md index 051abe6e10c9..897e8365f69a 100644 --- a/content/en/docs/instrumentation/php/getting-started.md +++ b/content/en/docs/instrumentation/php/getting-started.md @@ -9,9 +9,8 @@ spelling: cSpell:ignore darwin This page will show you how to get started with OpenTelemetry in PHP. -You will learn how you can instrument a simple PHP application automatically, -in such a way that [traces][], [metrics][] and [logs][] are emitted to the -console. +You will learn how you can instrument a simple PHP application automatically, in +such a way that [traces][], [metrics][] and [logs][] are emitted to the console. ## Prerequisites