From 22529782c53f2a40f314b5294e8269745aabe66c Mon Sep 17 00:00:00 2001 From: Pawel Chojnacki Date: Tue, 16 Oct 2018 11:40:39 +0200 Subject: [PATCH 01/11] Create initial version of installation guide --- docs/getting_started.md | 142 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/getting_started.md diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 0000000000..cc038201d8 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,142 @@ +# Datadog PHP integration + +Datadog's PHP APM integration provides the ability to trace critical parts of your PHP applications by automatically instrumenting code and submitting data to Datadog’s APM service using the OpenTracing API. + +To provide a great out-of-the-box experience that automatically instruments common libraries without requiring intrusive code changes or wrapping every object, we provide a PHP extension that allows introspecting any PHP function or method. + +## Datadog PHP extension installation + +Datadog’s PHP extension (`ddtrace`) allows introspection of arbitrary PHP code. + +At this moment it is only distributed in source code form, and requires manual compilation. + +### Compiling and installing the extension manually + +```bash +mkdir dd-trace +cd dd-trace +curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.2.tar.gz | tar x --strip-components=1 +phpize # generate files needed to build PHP extension +./configure +make +sudo make install +``` + +#### Bash one-liner + +```bash +(cd $(mktemp -d); curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.2.tar.gz | tar x --strip-components=1 && phpize && ./configure && make && sudo make install ) +``` + +### Enabling the extension + +After the extensions has been installed, the PHP runtime needs to be configured to use it. + +To do that we need to modify `php.ini`. This file’s location depends on how PHP has been built and configured on your system. To find out where yours is, run the following command: + +```bash +$ php --ini + +Configuration File (php.ini) Path: /usr/local/etc/php/7.2 +Loaded Configuration File: /usr/local/etc/php/7.2/php.ini +Scan for additional .ini files in: /usr/local/etc/php/7.2/conf.d +Additional .ini files parsed: /usr/local/etc/php/7.2/conf.d/ext-opcache.ini +``` + +Now the only remaining thing is to add following line to the `.ini` file found using above command: + +```ini +extension=ddtrace.so +``` + +After restarting the PHP application (eg. `apachectl restart`) the extension should now be enabled. To confirm that it’s being loaded, run: + +```bash +php -m | grep ddtrace +``` + +Some systems use different `php.ini` files for command line PHP vs. the web server module, so you may need to confirm both. If you look at the output of `phpinfo()` in a web page, you will see `ddtrace` listed if it’s loaded. + +## Enabling automatic tracing + +Once the C extension is installed, we need to install the PHP package that provides the actual integrations and framework for sending traces to Datadog. + +### Install `datadog/dd-trace` package + +```bash + +composer config minimum-stability beta # required to install opentracing 1.0.0-beta5 +composer require opentracing/opentracing +composer require datadog/dd-trace +``` + +#### Alternative: Install `datadog/dd-trace` package without changing `minimum-stability` + +```bash +composer require datadog/dd-trace # first add dd-trace require +# then manually add following entry to your `composer.json` ”require” entry +# "opentracing/opentracing": "@dev" + +# Example end result should look like: +# "require": { +# "datadog/dd-trace": "^0.2.2", +# "opentracing/opentracing": "@dev" +# } +# Next run: +composer update +``` + +### Enabling tracing + +#### Laravel integration + +To enable Laravel integration we need to configure a new Provider in `config/app.php` + +```php + 'providers' => array_merge(include(base_path('modules/system/providers.php')), [ +# ..... + 'DDTrace\Integrations\LaravelProvider', +``` + +Now your Laravel application should start sending traces to the Datadog agent running on localhost (in default configuration). The Datadog agent must have APM enabled; see https://docs.datadoghq.com/tracing/setup/ for instructions on installing and configuring the agent. + +#### Symfony integration + +For Symfony applications, add the bundle in app/AppKernel.php: + + +```php + $bundles = [ + // ... + new DDTrace\Integrations\SymfonyBundle(), + // ... + ]; +``` + +#### Adding tracing to a function or method + +To add spans for another function or method, you can use `dd_trace` to open a span before the code executes, close it when it’s done, set additional tags or errors on the span, and for more advanced usage, modify either the arguments or the return value. + +Here’s an example of tracing the `CustomDriver` class’s `doWork` method, including noting and re-throwing exceptions: + +```php +dd_trace("CustomDriver", "doWork", function (...$args) { + $scope = GlobalTracer::get()->startActiveSpan('CustomDriver.doWork’); + $span = $scope->getSpan(); + + // we can access object data via $this, and also execute + // the original method the same way + $span->setResource($this->workToDo); + + try { + $result = $this->doWork(...$args); + $span->setTag(‘doWork.size’, count($result)); + return $result; + } catch (Exception $e) { + $span->setError($e); + throw $e + } finally { + $span->finish(); + } +}); +``` From 0bb0429ed2b4b22c604443f289be5d81cde96384 Mon Sep 17 00:00:00 2001 From: Chuck Hagenbuch Date: Thu, 18 Oct 2018 11:17:00 -0400 Subject: [PATCH 02/11] a few tweaks I missed in the gdoc version --- docs/getting_started.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index cc038201d8..a09108568e 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -30,7 +30,7 @@ sudo make install ### Enabling the extension -After the extensions has been installed, the PHP runtime needs to be configured to use it. +After the extension has been installed, the PHP runtime needs to be configured to use it. To do that we need to modify `php.ini`. This file’s location depends on how PHP has been built and configured on your system. To find out where yours is, run the following command: @@ -43,7 +43,7 @@ Scan for additional .ini files in: /usr/local/etc/php/7.2/conf.d Additional .ini files parsed: /usr/local/etc/php/7.2/conf.d/ext-opcache.ini ``` -Now the only remaining thing is to add following line to the `.ini` file found using above command: +Now the only remaining thing is to add following line to the `.ini` file found using the above command: ```ini extension=ddtrace.so @@ -113,7 +113,7 @@ For Symfony applications, add the bundle in app/AppKernel.php: ]; ``` -#### Adding tracing to a function or method +#### Adding tracing to a custom function or method To add spans for another function or method, you can use `dd_trace` to open a span before the code executes, close it when it’s done, set additional tags or errors on the span, and for more advanced usage, modify either the arguments or the return value. From d98afe7db0049e74fdc7935413fce29546e58ef5 Mon Sep 17 00:00:00 2001 From: Luca Abbati Date: Thu, 18 Oct 2018 17:22:30 +0200 Subject: [PATCH 03/11] Update docs/getting_started.md --- docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index a09108568e..ed8d60d10f 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -93,7 +93,7 @@ composer update To enable Laravel integration we need to configure a new Provider in `config/app.php` ```php - 'providers' => array_merge(include(base_path('modules/system/providers.php')), [ + 'providers' => [ # ..... 'DDTrace\Integrations\LaravelProvider', ``` From 194e367e625f1697ed3e8e5f8cab25f35778aea1 Mon Sep 17 00:00:00 2001 From: Luca Abbati Date: Thu, 18 Oct 2018 17:25:41 +0200 Subject: [PATCH 04/11] Update docs/getting_started.md --- docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index ed8d60d10f..93bf9ae544 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -110,7 +110,7 @@ For Symfony applications, add the bundle in app/AppKernel.php: // ... new DDTrace\Integrations\SymfonyBundle(), // ... - ]; + ]; ``` #### Adding tracing to a custom function or method From fd1a5ba142035b6c33ae3f223f2a8b92cdc15c16 Mon Sep 17 00:00:00 2001 From: Luca Abbati Date: Thu, 18 Oct 2018 19:17:21 +0200 Subject: [PATCH 05/11] Update docs/getting_started.md --- docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 93bf9ae544..f35c4638bb 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -15,7 +15,7 @@ At this moment it is only distributed in source code form, and requires manual c ```bash mkdir dd-trace cd dd-trace -curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.2.tar.gz | tar x --strip-components=1 +curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.3.tar.gz | tar x --strip-components=1 phpize # generate files needed to build PHP extension ./configure make From a9044ad8641c6a8341be6b02368c80a1875f28c9 Mon Sep 17 00:00:00 2001 From: Luca Abbati Date: Thu, 18 Oct 2018 19:17:31 +0200 Subject: [PATCH 06/11] Update docs/getting_started.md --- docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index f35c4638bb..25de2a5e52 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -106,7 +106,7 @@ For Symfony applications, add the bundle in app/AppKernel.php: ```php - $bundles = [ + return [ // ... new DDTrace\Integrations\SymfonyBundle(), // ... From 4f11607fdfdc54fec0d757a1e0a0210032dc8597 Mon Sep 17 00:00:00 2001 From: Luca Abbati Date: Thu, 18 Oct 2018 19:17:42 +0200 Subject: [PATCH 07/11] Update docs/getting_started.md --- docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 25de2a5e52..90104aa046 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -117,7 +117,7 @@ For Symfony applications, add the bundle in app/AppKernel.php: To add spans for another function or method, you can use `dd_trace` to open a span before the code executes, close it when it’s done, set additional tags or errors on the span, and for more advanced usage, modify either the arguments or the return value. -Here’s an example of tracing the `CustomDriver` class’s `doWork` method, including noting and re-throwing exceptions: +Here’s an example of tracing the `CustomDriver` class’s `doWork` method, including reporting any exceptions as errors on the span and re-throwing them: ```php dd_trace("CustomDriver", "doWork", function (...$args) { From b55c05afb9fc1c9fd5a741f935f02e1b0b7c1057 Mon Sep 17 00:00:00 2001 From: Luca Abbati Date: Thu, 18 Oct 2018 19:17:51 +0200 Subject: [PATCH 08/11] Update docs/getting_started.md --- docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 90104aa046..d4a0727d98 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -108,7 +108,7 @@ For Symfony applications, add the bundle in app/AppKernel.php: ```php return [ // ... - new DDTrace\Integrations\SymfonyBundle(), + DDTrace\Integrations\SymfonyBundle::class => ['all' => true], // ... ]; ``` From c6d69e2eea532d76c0ac34163172c97a8584ce72 Mon Sep 17 00:00:00 2001 From: Luca Abbati Date: Thu, 18 Oct 2018 19:17:57 +0200 Subject: [PATCH 09/11] Update docs/getting_started.md --- docs/getting_started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index d4a0727d98..8ca69c4015 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -102,7 +102,7 @@ Now your Laravel application should start sending traces to the Datadog agent ru #### Symfony integration -For Symfony applications, add the bundle in app/AppKernel.php: +For Symfony applications, add the bundle in `config/bundles.php`: ```php From 334d8bd2a79728671876117cfe78b3c08b64fe8a Mon Sep 17 00:00:00 2001 From: Pawel Chojnacki Date: Thu, 18 Oct 2018 19:20:47 +0200 Subject: [PATCH 10/11] Bump to version v0.2.4 --- docs/getting_started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 8ca69c4015..7e0f47407a 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -15,7 +15,7 @@ At this moment it is only distributed in source code form, and requires manual c ```bash mkdir dd-trace cd dd-trace -curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.3.tar.gz | tar x --strip-components=1 +curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.4.tar.gz | tar x --strip-components=1 phpize # generate files needed to build PHP extension ./configure make @@ -25,7 +25,7 @@ sudo make install #### Bash one-liner ```bash -(cd $(mktemp -d); curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.2.tar.gz | tar x --strip-components=1 && phpize && ./configure && make && sudo make install ) +(cd $(mktemp -d); curl -L https://github.com/DataDog/dd-trace-php/archive/v0.2.4.tar.gz | tar x --strip-components=1 && phpize && ./configure && make && sudo make install ) ``` ### Enabling the extension From 39270cb3109ab5fd1ccc24d78b41dc48fd4ed295 Mon Sep 17 00:00:00 2001 From: Pawel Chojnacki Date: Thu, 18 Oct 2018 19:23:06 +0200 Subject: [PATCH 11/11] Fix Indentation --- docs/getting_started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting_started.md b/docs/getting_started.md index 7e0f47407a..3f516c9591 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -93,9 +93,9 @@ composer update To enable Laravel integration we need to configure a new Provider in `config/app.php` ```php - 'providers' => [ + 'providers' => [ # ..... - 'DDTrace\Integrations\LaravelProvider', + 'DDTrace\Integrations\LaravelProvider', ``` Now your Laravel application should start sending traces to the Datadog agent running on localhost (in default configuration). The Datadog agent must have APM enabled; see https://docs.datadoghq.com/tracing/setup/ for instructions on installing and configuring the agent.