Merge pull request #33 from nipwaayoni/7.1-dev

7.1 dev

Author: dstepe

README.md

@@ -77,6 +77,18 @@ All additional events will be descendents of this transaction.
 There is currently no provision to manage additional Transaction events, or to handle a non-HTTP Request
 based process. We hope to address those issues in a future release.
 
+#### Customizing Transaction Context
+
+While the `RecordTransaction` middleware sets supported APM contexts when the transaction is created, you may wish to customize the contexts based on the completed request/response. This can be done by extending the `RecordTransaction` middleware and overriding context methods as described in the [customizing transactions](docs/customizing_transactions.md) documentation.
+
+#### Excluding Requests
+
+You can exclude requests from being sent to APM by using an `except` list of URI patterns. For example, you may wish to avoid sending requests for the (DebugBar)[https://github.com/barryvdh/laravel-debugbar] resources during development or testing.
+
+Add the desired URI patterns to the `except` key in the `elastic-apm` configuration. Note that you must publish the file as described in the [configuration docs](docs/configuration.md).
+
+If you have extended the `RecordTransaction` middleware, as described in the [customizing transactions](docs/customizing_transactions.md) documentation, you may set the `except` list class member there.
+
 ### Span Events
 
 Spans occur within a Transaction. Spans represent events within the Transaction. Queries made through Laravel's 
@@ -102,7 +114,7 @@ Refer to the [configuration docs](docs/configuration.md) for more information.
 
 ### HTTP Client Customization
 
-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).
+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 provide it to the `AgentBuilder`. See the "HTTP Client Configuration" section of the [configuration docs](docs/configuration.md).
 
 ## Laravel Test Setup
 

composer.json

@@ -12,7 +12,7 @@
   "license": "MIT",
   "require": {
     "php": ">= 7.2",
-    "nipwaayoni/elastic-apm-php-agent": "^7.1",
+    "nipwaayoni/elastic-apm-php-agent": "^7.2",
     "ramsey/uuid": ">= 3.0 < 5.0"
   },
   "require-dev": {

docs/breaking_changes.md

@@ -1,6 +1,10 @@
 # Breaking Changes
 
-## 7.x
+## 7.1.0
+
+1. Removed the ability to bind "ElasticApm*" objects into the container to set on the AgentBuilder. Configuring the AgentBuilder is now done by binding an implementation into the container which the ElasticApmServiceProvider will resolve and use.
+
+## 7.0.0
 
 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.

docs/configuration.md

@@ -24,28 +24,69 @@ php artisan vendor:publish --tag=config
 
 Once published, open the `config/elastic-apm.php` file and review the various settings.
 
-## HTTP Client Configuration
+## Customizing Agent Creation
 
-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.
+The `Agent` object used to manage APM events is created using the provided `AgentBuilder` class. You can control many aspects of the `Agent` creation by binding your own implementation into the service container. Some helpful examples are shown below. For more details, refer to the [Elastic APM PHP Agent](https://github.com/nipwaayoni/elastic-apm-php-agent/blob/master/docs/agent.md) documentation.
+
+### Binding an AgentBuilder
+
+Bind your implementation as a singleton in the service container:
+
+```php
+$this->app->bind(AgentBuilder::class, function () {
+    $builder = new AgentBuilder();
+
+    // configure the builder
+
+    return $builder;
+});
+```
+
+Note that the `ElasticApmServiceProvider` will always call the `AgentBuilder::withConfig()` and `AgentBuilder::withEnvData()` methods. You must use the provided `elastic-apm` configuration options to influence those 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 provide it to the `AgentBuilder. 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.
+The following example demonstrates how to create a GuzzleHttp client that will not verify server certificates.
 
 ```php
-$this->app->bind('ElasticApmHttpClient', function () {
-    // Create the configured client
+$this->app->bind(AgentBuilder::class, function () {
+    $builder = new AgentBuilder();
+
     $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);
-});
+    $builder->withHttpClient(new \Http\Adapter\Guzzle6\Client($client));
 
+    return $builder;
+});
 ```
 
-If the service container has a binding for `ElasticApmHttpClient`, the concrete implementation will be retrieved and passed into the `Agent`.
+### APM Transaction Hooks
+
+You can hook the APM HTTP request/response process to examine the data to be sent to APM and the response after sending. This may be helpful in troubleshooting issues.
+
+```php
+$this->app->bind(AgentBuilder::class, function () {
+    $builder = new AgentBuilder();
+
+    $builder->withPreCommitCallback(function (RequestInterface $request) {
+        Log::info(sprintf('Pre commit url is: %s', $request->getUri()));
+    });
+
+    $builder->withPostCommitCallback(function (ResponseInterface $response) {
+        Log::info(sprintf('Post commit response status: %s', $response->getStatusCode()));
+        Log::debug($response->getBody()->getContents());
+    });
+
+    return $builder;
+});
+```

src/Exceptions/ApmAgent.php

@@ -17,6 +17,9 @@ class RecordTransaction
      * @var Agent
      */
     protected $agent;
+
+    protected $except = [];
+
     /**
      * @var Timer
      */
@@ -37,6 +40,7 @@ public static function getTransactionName()
     /**
      * RecordTransaction constructor.
      * @param Agent $agent
+     * @param Timer $timer
      */
     public function __construct(Agent $agent, Timer $timer)
     {
@@ -52,6 +56,10 @@ public function __construct(Agent $agent, Timer $timer)
      */
     final public function handle($request, Closure $next)
     {
+        if ($this->inExceptArray($request)) {
+            return $next($request);
+        }
+
         self::setTransactionName($this->getTransactionNameFromRequest($request));
         $transaction = $this->agent->startTransaction(
             self::getTransactionName()
@@ -85,28 +93,9 @@ final public function handle($request, Closure $next)
 
         $transaction->stop($this->timer->getElapsedInMilliseconds());
 
-        $this->agent->send();
-
         return $response;
     }
 
-    /**
-     * Perform any final actions for the request lifecycle.
-     *
-     * @param  \Illuminate\Http\Request $request
-     * @param  \Symfony\Component\HttpFoundation\Response $response
-     *
-     * @return void
-     */
-    public function terminate($request, $response)
-    {
-        try {
-            $this->agent->send();
-        } catch (\Throwable $t) {
-            Log::error($t);
-        }
-    }
-
     protected function response(Response $response): array
     {
         return [
@@ -192,4 +181,31 @@ private function makeTransactionName(string $method, string $path): string
 
         return sprintf("%s %s", $method, $path);
     }
+
+    /**
+     * Determine if the request has a URI that should be recorded.
+     * From \Illuminate\Foundation\Http\Middleware\VerifyCsrfToken
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @return bool
+     */
+    protected function inExceptArray($request)
+    {
+        $exceptList = array_merge(
+            $this->except,
+            config('elastic-apm.except', [])
+        );
+
+        foreach ($exceptList as $except) {
+            if ($except !== '/') {
+                $except = trim($except, '/');
+            }
+
+            if ($request->fullUrlIs($except) || $request->is($except)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }

src/Middleware/RecordTransaction.php

@@ -3,7 +3,10 @@
 namespace Nipwaayoni\ElasticApmLaravel\Providers;
 
 use Illuminate\Database\Events\QueryExecuted;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
 use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\App;
 use Illuminate\Support\ServiceProvider;
 use Illuminate\Support\Str;
 use Illuminate\Support\Arr;
@@ -51,16 +54,16 @@ public function register()
             'elastic-apm'
         );
 
-        $this->app->singleton(Agent::class, function ($app) {
-            $container = resolve(ContainerInterface::class);
+        $this->app->singleton(Agent::class, function () {
+            $builder = resolve(AgentBuilder::class);
 
-            $builder = new AgentBuilder();
             $builder->withConfig(new Config(
                 array_merge(
                     [
                         'active' => config('elastic-apm.active'),
                         'framework' => 'Laravel',
                         'frameworkVersion' => app()->version(),
+                        'environment' => config('elastic-apm.environment'),
                     ],
                     $this->getAppConfig(),
                     config('elastic-apm.server')
@@ -69,26 +72,6 @@ public function register()
 
             $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();
         });
 
@@ -98,6 +81,14 @@ public function register()
         $this->app->alias(Agent::class, 'elastic-apm');
 
         $this->app->instance('query-log', new Collection());
+
+        // Register a callback on terminating to send the events
+        $this->app->terminating(function (Request $request, Response $response) {
+            /** @var Agent $agent */
+            $agent = resolve(Agent::class);
+
+            $agent->send();
+        });
     }
 
     /**

src/Providers/ElasticApmServiceProvider.php

@@ -13,6 +13,9 @@
         'appVersion'    => env('APM_APPVERSION', ''),
     ],
 
+    // list of URIs not to record as transactions
+    'except' => [],
+
     // list allowed environment variables OR empty array to send everything
     'env' => ['DOCUMENT_ROOT', 'REMOTE_ADDR'],
 

src/config/elastic-apm.php

@@ -120,6 +120,28 @@ public function testSetsTransactionNameToRouteUriLogsErrorWhenWithoutCurrentRout
         $recorder->handle($request, $next);
     }
 
+    protected function useExceptList($app)
+    {
+        $app->config->set('elastic-apm.except', ['/except/uri']);
+    }
+
+    /**
+     * @environment-setup useExceptList
+     */
+    public function testDoesNotStartTransactionForUriInExceptList(): void
+    {
+        $this->agent->expects($this->never())->method('startTransaction');
+
+        $request = $this->makeRequest('GET', ['server' => ['REQUEST_URI' => '/except/uri']]);
+        $next = function () {
+            return new Response();
+        };
+
+        $recorder = new RecordTransaction($this->agent, $this->timer);
+
+        $recorder->handle($request, $next);
+    }
+
     protected function makeRequest(string $method = 'GET', array $options = []): Request
     {
         $query = $options['query'] ?? [];