Merge pull request #14 from nipwaayoni/add-agentbuilder

Add agentbuilder

Author: dstepe

CHANGELOG

@@ -18,11 +18,15 @@ This package is a continuation of the excellent work done by [philkra](https://g
 composer require nipwaayoni/elastic-apm-laravel
 ```
 
+The [nipwaayoni/elastic-apm-php-agent](https://github.com/nipwaayoni/elastic-apm-php-agent) no longer includes and http client. You must ensure a [PSR-18](https://www.php-fig.org/psr/psr-18/) compatible implementation is available. Please see the [agent install guide](https://github.com/nipwaayoni/elastic-apm-php-agent/blob/master/docs/install.md) for more information.
+
 ## Service Provider
 
 ### Laravel
 
-No need to register service provider manually. It is registered automatically by [package discovery](https://laravel.com/docs/5.6/packages#package-discovery).
+If using Laravel >=5.5, registration is done automatically by [package discovery](https://laravel.com/docs/7.x/packages#package-discovery).
+
+This package is not tested or asserted to work with Laravel <5.5.
 
 ### Lumen
 
@@ -73,92 +77,31 @@ based process. We hope to address those issues in a future release.
 
 Spans occur within a Transaction. Spans represent events within the Transaction. Queries made through Laravel's 
 database layer are automatically added to the Transaction. You can add your own Span events using the `EventTimer` 
-class from this package. 
+class from this package. See the docs for [creating spans](docs/creating_spans.md).
 
 Nested Spans are not supported by this package yet.
 
-#### Laravel
-
-Acquire the EventTimer object from the container.
-
-```php
-class MyClass
-{
-    /**
-     * @var EventTimer
-     */
-    private $eventTimer;
-    
-    public function __construct(EventTimer $eventTimer)
-    {
-        $this->eventTimer = $eventTimer;
-    }
-
-    public function runSomeRequest(int $number): AnObject
-    {
-        $event = $this->eventTimer->begin('Request the data');
-        $result = $this->someMethod($number);
-        $this->eventTimer->finish($event);
-
-        return new AnObject($result);
-    }
-}
-```
-
-#### Lumen
-
-pending
-
 ### Error Events
 
-#### Laravel
-
-In `app/Exceptions/Handler`, add the following to the `report` method:
-
-```php
-ElasticApm::captureThrowable($exception);
-```
-
-Make sure to import the facade at the top of your file:
-
-```php
-use ElasticApm;
-```
-
-#### Lumen
-
-pending
+The APM service defines exception events as a valid type. Exceptions in your application can be sent to APM in addition to any normal exception handling. See the docs for [exceptions](docs/exceptions.md).
 
 ## Agent Configuration
 
-### Laravel
-
-The following environment variables are supported in the default configuration:
+You can use a number of environment settings to influence the behavior of this package. At a minimum, you must set the APM server URL and, if applicable, the secret toke:
 
 | Variable          | Description |
 |-------------------|-------------|
-|APM_ACTIVE         | `true` or `false` defaults to `true`. If `false`, the agent will collect, but not send, transaction data. |
-|APM_APPNAME        | Name of the app as it will appear in APM. |
-|APM_APPVERSION     | Version of the app as it will appear in APM. |
 |APM_SERVERURL      | URL to the APM intake service. |
 |APM_SECRETTOKEN    | Secret token, if required. |
-|APM_APIVERSION     | APM API version, defaults to `v1` (only v1 is supported at this time). |
-|APM_USEROUTEURI    | `true` or `false` defaults to `false`. The default behavior is to record the URL as sent in the request. This can result in excessive unique entries in APM. Set to `true` to have the agent use the route URL instead. |
-|APM_QUERYLOG       | `true` or `false` defaults to 'true'. Set to `false` to completely disable query logging, or to `auto` if you would like to use the threshold feature. |
-|APM_THRESHOLD      | Query threshold in milliseconds, defaults to `200`. If a query takes longer then 200ms, we enable the query log. Make sure you set `APM_QUERYLOG=auto`. |
-|APM_BACKTRACEDEPTH | Defaults to `25`. Depth of backtrace in query span. |
-|APM_RENDERSOURCE   | Defaults to `true`. Include source code in query span. |
 
-You may also publish the `elastic-apm.php` configuration file to change additional settings:
+Refer to the [configuration docs](docs/configuration.md) for more information.
 
-```bash
-php artisan vendor:publish --tag=config
-```
+### HTTP Client Customization
 
-Once published, open the `config/elastic-apm.php` file and review the various settings.
+It is no longer possible to provide HTTP client options through the APM PHP Agent configuration. If you need to customize the HTTP client, you must implement and configure a suitable client object and properly register it with the Laravel service container. See the "HTTP Client Configuation" section of the [configuration docs](docs/configuration.md).
 
-### Laravel Test Setup
+## Laravel Test Setup
 
 Laravel provides classes to support running unit and feature tests with PHPUnit. In most cases, you will want to explicitly disable APM during testing since it is enabled by default. Refer to the Laravel documentation for more information (https://laravel.com/docs/5.7/testing).
 
-Because the APM agent checks it's active status using a strict boolean type, you must ensure your `APM_ACTIVE` value is a boolean `false` rather than simply a falsy value. The best way to accomplish this is to create an `.env.testing` file and include `APM_ACTIVE=false`, along with any other environment settings required for your tests. This file should be safe to include in your SCM.
+Because the APM agent checks its active status using a strict boolean type, you must ensure your `APM_ACTIVE` value is a boolean `false` rather than simply a falsy value. The best way to accomplish this is to create an `.env.testing` file and include `APM_ACTIVE=false`, along with any other environment settings required for your tests. This file should be safe to include in your SCM.

README.md

@@ -12,11 +12,7 @@
   "license": "MIT",
   "require": {
     "php": ">= 7.2",
-    "illuminate/database": ">= 6.0 < 8",
-    "illuminate/http": ">= 6.0 < 8",
-    "illuminate/routing": ">= 6.0 < 8",
-    "illuminate/support": ">= 6.0 < 8",
-    "nipwaayoni/elastic-apm-php-agent": "7.1.0-rc1",
+    "nipwaayoni/elastic-apm-php-agent": "^7.1",
     "ramsey/uuid": ">= 3.0 < 5.0"
   },
   "require-dev": {

composer.json

@@ -0,0 +1,9 @@
+# Breaking Changes
+
+## 7.x
+
+1. The [Elastic APM PHP Agent](https://github.com/nipwaayoni/elastic-apm-php-agent) minimum version has been updated.
+2. It is no longer recommended to call `Agent::send()` in `Exceptions\Handler::report()`. This will likely result in duplicate reporting of exceptions.
+3. The `elastic-apm.env` settings have been redefined. This key now contains the allowed list of environment variables to include the APM context. The application environment is now set in `elastic-apm.environment`. If you previously published the `config/elastic-apm.php` file, you must make certain it is updated.
+4. The [Elastic APM PHP Agent](https://github.com/nipwaayoni/elastic-apm-php-agent) no longer provides an HTTP client implementation. Please see the [agent install guide](https://github.com/nipwaayoni/elastic-apm-php-agent/blob/master/docs/install.md) for more information. The configuration passed to the `Agent` can no longer contain the `httpClient` key. If you previously published the `config/elastic-apm.php` file, you must remove that key.
+5. The method of creating span events has changed. See the [creating spans](creating_spans.md) documentation.

docs/breaking_changes.md

@@ -0,0 +1,51 @@
+# Configuration
+
+The following environment variables are supported in the default configuration:
+
+| Variable          | Description |
+|-------------------|-------------|
+|APM_ACTIVE         | `true` or `false` defaults to `true`. If `false`, the agent will collect, but not send, transaction data. |
+|APM_APPNAME        | Name of the app as it will appear in APM. |
+|APM_APPVERSION     | Version of the app as it will appear in APM. |
+|APM_SERVERURL      | URL to the APM intake service. |
+|APM_SECRETTOKEN    | Secret token, if required. |
+|APM_APIVERSION     | APM API version, defaults to `v2` (only v2 is supported at this time). |
+|APM_USEROUTEURI    | `true` or `false` defaults to `false`. The default behavior is to record the URL as sent in the request. This can result in excessive unique entries in APM. Set to `true` to have the agent use the route URL instead. |
+|APM_QUERYLOG       | `true` or `false` defaults to 'true'. Set to `false` to completely disable query logging, or to `auto` if you would like to use the threshold feature. |
+|APM_THRESHOLD      | Query threshold in milliseconds, defaults to `200`. If a query takes longer then 200ms, we enable the query log. Make sure you set `APM_QUERYLOG=auto`. |
+|APM_BACKTRACEDEPTH | Defaults to `25`. Depth of backtrace in query span. |
+|APM_RENDERSOURCE   | Defaults to `true`. Include source code in query span. |
+
+You may also publish the `elastic-apm.php` configuration file to change additional settings:
+
+```bash
+php artisan vendor:publish --tag=config
+```
+
+Once published, open the `config/elastic-apm.php` file and review the various settings.
+
+## HTTP Client Configuration
+
+If you need to customize the HTTP client, you must create a [PSR-18](https://www.php-fig.org/psr/psr-18/) compatible implementation and bind it in the Laravel service container. For now, we will use a GuzzleHttp adapter from the PHP-HTTP project.
+
+```bash
+composer require http-interop/http-factory-guzzle php-http/guzzle6-adapter
+```
+
+The following example demonstrates how to create a GuzzleHttp client that will not verify server certificates. Once you create the client, bind it in the service container under the `ElasticApmHttpClient` abstract.
+
+```php
+$this->app->bind('ElasticApmHttpClient', function () {
+    // Create the configured client
+    $client = new \GuzzleHttp\Client([
+        'verify' => false,
+        // other client options
+    ]);
+    
+    // Wrap the client object in the adapter and return it
+    return new \Http\Adapter\Guzzle6\Client($client);
+});
+
+```
+
+If the service container has a binding for `ElasticApmHttpClient`, the concrete implementation will be retrieved and passed into the `Agent`.

docs/configuration.md

@@ -0,0 +1,29 @@
+# Creating Spans 
+
+The current event implementation creates a single APM transaction to represent the Laravel Request/Response. You can create APM span events to represent discrete actions within the transaction. The `\Nipwaayoni\ElasticApmLaravel\Apm\EventTimer` class facilitates making spans.
+
+```php
+class MyClass
+{
+    /**
+     * @var \Nipwaayoni\ElasticApmLaravel\Apm\EventTimer
+     */
+    private $eventTimer;
+    
+    public function __construct(\Nipwaayoni\ElasticApmLaravel\Apm\EventTimer $eventTimer)
+    {
+        $this->eventTimer = $eventTimer;
+    }
+
+    public function runSomeRequest(int $number): MyObject
+    {
+        $event = $this->eventTimer->begin('Request the data');
+        $result = $this->someMethod($number);
+        $this->eventTimer->finish($event);
+
+        return new MyObject($result);
+    }
+}
+```
+
+The `EventTimer` makes the transaction the parent event of all spans.

docs/creating_spans.md

@@ -0,0 +1,19 @@
+# Exceptions
+
+Laravel provides a convenient method for working with application exceptions which we can leverage to send Exceptions to APM. In `app/Exceptions/Handler`, add the following to the `report` method:
+
+```php
+ElasticApm::captureThrowable($exception);
+```
+
+Make sure to import the facade at the top of your file:
+
+```php
+use ElasticApm;
+```
+
+The collected Exceptions will be sent when `Agent::send()` is called in the middleware.
+
+Note that previous versions of this package suggested calling `Agent::send()` explicitly in `Handler::report()`. The was related to APM  < 7 intake and is no longer suggested as it may lead to duplicate events.
+
+Note that the Laravel exception handler is only aware of exceptions generated after the Laravel framework is minimally bootstrapped. An error preventing the proper executation of the bootstrap process will not be captured in `Handler::report()`.

docs/exceptions.md

@@ -8,8 +8,11 @@
 use Illuminate\Support\Str;
 use Illuminate\Support\Arr;
 use Nipwaayoni\Agent;
+use Nipwaayoni\AgentBuilder;
+use Nipwaayoni\Config;
 use Nipwaayoni\ElasticApmLaravel\Contracts\VersionResolver;
 use Nipwaayoni\Helper\Timer;
+use Psr\Container\ContainerInterface;
 
 class ElasticApmServiceProvider extends ServiceProvider
 {
@@ -49,21 +52,44 @@ public function register()
         );
 
         $this->app->singleton(Agent::class, function ($app) {
-            return new Agent(
+            $container = resolve(ContainerInterface::class);
+
+            $builder = new AgentBuilder();
+            $builder->withConfig(new Config(
                 array_merge(
                     [
+                        'active' => config('elastic-apm.active'),
                         'framework' => 'Laravel',
                         'frameworkVersion' => app()->version(),
                     ],
-                    [
-                        'active' => config('elastic-apm.active'),
-                        'httpClient' => config('elastic-apm.httpClient'),
-                    ],
                     $this->getAppConfig(),
-                    config('elastic-apm.env'),
                     config('elastic-apm.server')
                 )
-            );
+            ));
+
+            $builder->withEnvData(config('elastic-apm.env'));
+
+            if ($container->has('ElasticApmEventFactory')) {
+                $builder->withEventFactory($container->get('ElasticApmEventFactory'));
+            }
+
+            if ($container->has('ElasticApmTransactionStore')) {
+                $builder->withTransactionStore($container->get('ElasticApmTransactionStore'));
+            }
+
+            if ($container->has('ElasticApmHttpClient')) {
+                $builder->withHttpClient($container->get('ElasticApmHttpClient'));
+            }
+
+            if ($container->has('ElasticApmRequestFactory')) {
+                $builder->withRequestFactory($container->get('ElasticApmRequestFactory'));
+            }
+
+            if ($container->has('ElasticApmStreamFactory')) {
+                $builder->withStreamFactory($container->get('ElasticApmStreamFactory'));
+            }
+
+            return $builder->build();
         });
 
         $this->startTime = $this->app['request']->server('REQUEST_TIME_FLOAT') ?? microtime(true);

src/Providers/ElasticApmServiceProvider.php

@@ -3,6 +3,7 @@
 return [
     // Sets whether the apm reporting should be active or not
     'active'        => env('APM_ACTIVE', true),
+    'environment'   => env('APM_ENVIRONMENT', 'development'),
 
     'app' => [
         // The app name that will identify your app in Kibana / Elastic APM
@@ -12,16 +13,8 @@
         'appVersion'    => env('APM_APPVERSION', ''),
     ],
 
-    'env' => [
-        // whitelist environment variables OR send everything
-        'env' => ['DOCUMENT_ROOT', 'REMOTE_ADDR'],
-        //'env' => []
-        // Application environment
-        'environment'   => env('APM_ENVIRONMENT', 'development'),
-    ],
-
-    // GuzzleHttp\Client options (http://docs.guzzlephp.org/en/stable/request-options.html#request-options)
-    'httpClient' => [],
+    // list allowed environment variables OR empty array to send everything
+    'env' => ['DOCUMENT_ROOT', 'REMOTE_ADDR'],
 
     'server' => [
         // The apm-server to connect to
@@ -31,7 +24,7 @@
         'secretToken'   => env('APM_SECRETTOKEN', null),
 
         // API version of the apm agent you connect to
-        'apmVersion'    => env('APM_APIVERSION', 'v1'),
+        'apmVersion'    => env('APM_APIVERSION', 'v2'),
 
         // Hostname of the system the agent is running on.
         'hostname'      => gethostname(),