Merge branch 'philkra-add-opaque-id-mutator'

docs/per-request-configuration.asciidoc

@@ -4,6 +4,32 @@
 There are several configurations that can be set on a per-request basis, rather than at a connection- or client-level.
 These are specified as part of the request associative array.
 
+
+=== Request Identification
+
+You can enrich your requests against Elasticsearch with an identifier string, that allows you to discover this identifier
+in https://www.elastic.co/guide/en/elasticsearch/reference/7.4/logging.html#deprecation-logging[deprecation logs], to support you with
+https://www.elastic.co/guide/en/elasticsearch/reference/7.4/index-modules-slowlog.html#_identifying_search_slow_log_origin[identifying search slow log origin]
+or to help with https://www.elastic.co/guide/en/elasticsearch/reference/current/tasks.html#_identifying_running_tasks[identifying running tasks].
+
+
+[source,php]
+----
+$client = ClientBuilder::create()->build();
+
+$params = [
+    'index' => 'test',
+    'id'    => 1,
+    'client' => [
+        'opaqueId' => '[email protected]_user1234', <1>
+    ]
+];
+$response = $client->get($params);
+
+----
+<1> This will populate the `X-Opaque-Id` header with the value `[email protected]_user1234`
+
+
 === Ignoring exceptions
 The library attempts to throw exceptions for common problems.  These exceptions match the HTTP response code provided
 by Elasticsearch.  For example, attempting to GET a nonexistent document will throw a `MissingDocument404Exception`.

src/Elasticsearch/Connections/Connection.php

@@ -374,6 +374,7 @@ public function logRequestSuccess(array $request, array $response): void
             array(
                 'method'    => $request['http_method'],
                 'uri'       => $response['effective_url'],
+                'port'      => $response['transfer_stats']['primary_port'],
                 'headers'   => $request['headers'],
                 'HTTP code' => $response['status'],
                 'duration'  => $response['transfer_stats']['total_time'],
@@ -408,11 +409,13 @@ public function logRequestSuccess(array $request, array $response): void
     public function logRequestFail(array $request, array $response, \Exception $exception): void
     {
         $this->log->debug('Request Body', array($request['body']));
+
         $this->log->warning(
             'Request Failure:',
             array(
                 'method'    => $request['http_method'],
                 'uri'       => $response['effective_url'],
+                'port'      => $response['transfer_stats']['primary_port'],
                 'headers'   => $request['headers'],
                 'HTTP code' => $response['status'],
                 'duration'  => $response['transfer_stats']['total_time'],

src/Elasticsearch/Endpoints/AbstractEndpoint.php

@@ -225,7 +225,7 @@ private function checkUserParams(array $params)
 
         $whitelist = array_merge(
             $this->getParamWhitelist(),
-            [ 'pretty', 'human', 'error_trace', 'source', 'filter_path' ]
+            [ 'pretty', 'human', 'error_trace', 'source', 'filter_path', 'opaqueId' ]
         );
 
         $invalid = array_diff(array_keys($params), $whitelist);
@@ -249,6 +249,15 @@ private function extractOptions(&$params)
     {
         // Extract out client options, then start transforming
         if (isset($params['client']) === true) {
+            // Check if the opaqueId is populated and add the header
+            if (isset($params['client']['opaqueId']) === true) {
+                if (isset($params['client']['headers']) === false) {
+                    $params['client']['headers'] = [];
+                }
+                $params['client']['headers']['x-opaque-id'] = [trim($params['client']['opaqueId'])];
+                unset($params['client']['opaqueId']);
+            }
+
             $this->options['client'] = $params['client'];
             unset($params['client']);
         }

tests/Elasticsearch/Tests/ClientBuilder/ArrayLogger.php

@@ -0,0 +1,57 @@
+<?php
+declare(strict_types = 1);
+
+namespace Elasticsearch\Tests\ClientBuilder;
+
+use Psr\Log\LoggerInterface;
+use Psr\Log\LogLevel;
+
+class ArrayLogger implements LoggerInterface
+{
+    public $output = [];
+
+    public function emergency($message, array $context = array())
+    {
+        $this->log(LogLevel::EMERGENCY, $message, $context);
+    }
+
+    public function alert($message, array $context = array())
+    {
+        $this->log(LogLevel::ALERT, $message, $context);
+    }
+
+    public function critical($message, array $context = array())
+    {
+        $this->log(LogLevel::CRITICAL, $message, $context);
+    }
+
+    public function error($message, array $context = array())
+    {
+        $this->log(LogLevel::ERROR, $message, $context);
+    }
+
+    public function warning($message, array $context = array())
+    {
+        $this->log(LogLevel::WARNING, $message, $context);
+    }
+
+    public function notice($message, array $context = array())
+    {
+        $this->log(LogLevel::NOTICE, $message, $context);
+    }
+
+    public function info($message, array $context = array())
+    {
+        $this->log(LogLevel::INFO, $message, $context);
+    }
+
+    public function debug($message, array $context = array())
+    {
+        $this->log(LogLevel::DEBUG, $message, $context);
+    }
+
+    public function log($level, $message, array $context = array())
+    {
+        $this->output[] = sprintf("%s: %s %s", $level, $message, json_encode($context));
+    }
+}

tests/Elasticsearch/Tests/ClientBuilder/DummyLogger.php

@@ -5,5 +5,5 @@
 
 class DummyLogger
 {
-
+    
 }

tests/Elasticsearch/Tests/ClientIntegrationTests.php

@@ -4,7 +4,10 @@
 
 namespace Elasticsearch\Tests;
 
-use Elasticsearch;
+use Elasticsearch\ClientBuilder;
+use Elasticsearch\Common\Exceptions\Missing404Exception;
+use Elasticsearch\Tests\ClientBuilder\ArrayLogger;
+use Psr\Log\LogLevel;
 
 /**
  * Class ClientTest
@@ -18,22 +21,62 @@
  */
 class ClientIntegrationTests extends \PHPUnit\Framework\TestCase
 {
-    public function testCustomQueryParams()
+    public function setUp()
     {
-        $client = Elasticsearch\ClientBuilder::create()
+        if (empty(getenv('ES_TEST_HOST'))) {
+            $this->markTestSkipped('I cannot execute integration test without ES_TEST_HOST env');
+        }
+        $this->logger = new ArrayLogger();
+    }
+
+    public function testLogRequestSuccessHasInfoNotEmpty()
+    {
+        $client = ClientBuilder::create()
+            ->setHosts([getenv('ES_TEST_HOST')])
+            ->setLogger($this->logger)
+            ->build();
+
+        $result = $client->info();
+
+        $this->assertNotEmpty($this->getLevelOutput(LogLevel::INFO, $this->logger->output));
+    }
+
+    public function testLogRequestSuccessHasPortInInfo()
+    {
+        $client = ClientBuilder::create()
             ->setHosts([getenv('ES_TEST_HOST')])
+            ->setLogger($this->logger)
             ->build();
 
-        $getParams = [
-            'index' => 'test',
-            'type' => 'test',
-            'id' => 1,
-            'parent' => 'abc',
-            'custom' => ['customToken' => 'abc', 'otherToken' => 123],
-            'client' => ['ignore' => 400]
-        ];
-        $exists = $client->exists($getParams);
-
-        $this->assertFalse((bool) $exists);
+        $result = $client->info();
+
+        $this->assertContains('"port"', $this->getLevelOutput(LogLevel::INFO, $this->logger->output));
+    }
+
+    public function testLogRequestFailHasWarning()
+    {
+        $client = ClientBuilder::create()
+            ->setHosts([getenv('ES_TEST_HOST')])
+            ->setLogger($this->logger)
+            ->build();
+
+        try {
+            $result = $client->get([
+                'index' => 'foo',
+                'id' => 'bar'
+            ]);
+        } catch (Missing404Exception $e) {
+            $this->assertNotEmpty($this->getLevelOutput(LogLevel::WARNING, $this->logger->output));
+        }
+    }
+
+    private function getLevelOutput(string $level, array $output): string
+    {
+        foreach ($output as $out) {
+            if (false !== strpos($out, $level)) {
+                return $out;
+            }
+        }
+        return '';
     }
 }

tests/Elasticsearch/Tests/Endpoints/AbstractEndpointTest.php

@@ -10,6 +10,11 @@ class AbstractEndpointTest extends \PHPUnit\Framework\TestCase
 {
     private $endpoint;
 
+    protected function setUp()
+    {
+        $this->endpoint = $this->getMockForAbstractClass(AbstractEndpoint::class);
+    }
+
     public static function invalidParameters(): array
     {
         return [
@@ -20,6 +25,8 @@ public static function invalidParameters(): array
 
     /**
      * @dataProvider invalidParameters
+     *
+     * @covers AbstractEndpoint::setParams
      */
     public function testInvalidParamsCauseErrorsWhenProvidedToSetParams(array $params)
     {
@@ -32,8 +39,21 @@ public function testInvalidParamsCauseErrorsWhenProvidedToSetParams(array $param
         $this->endpoint->setParams($params);
     }
 
-    protected function setUp()
+    /**
+     * @covers AbstractEndpoint::setParams
+     * @covers AbstractEndpoint::extractOptions
+     * @covers AbstractEndpoint::getOptions
+     */
+    public function testOpaqueIdInHeaders()
     {
-        $this->endpoint = $this->getMockForAbstractClass(AbstractEndpoint::class);
+        $params = ['client' => ['opaqueId' => 'test_id_' . rand(1000, 9999)]];
+        $this->endpoint->setParams($params);
+
+        $options = $this->endpoint->getOptions();
+        $this->assertArrayHasKey('client', $options);
+        $this->assertArrayHasKey('headers', $options['client']);
+        $this->assertArrayHasKey('x-opaque-id', $options['client']['headers']);
+        $this->assertNotEmpty($options['client']['headers']['x-opaque-id']);
+        $this->assertEquals($params['client']['opaqueId'], $options['client']['headers']['x-opaque-id'][0]);
     }
 }