Added new observability events (#1365)

docs/observability.asciidoc

@@ -49,6 +49,15 @@ client.on('response', (err, result) => {
 The client emits the following events:
 [cols=2*]
 |===
+|`serialization`
+a|Emitted before starting serialization and compression. If you want to measure this phase duration, you should measure the time elapsed between this event and `request`.
+[source,js]
+----
+client.on('serialization', (err, result) => {
+  console.log(err, result)
+})
+----
+
 |`request`
 a|Emitted before sending the actual request to {es} _(emitted multiple times in case of retries)_.
 [source,js]
@@ -58,6 +67,15 @@ client.on('request', (err, result) => {
 })
 ----
 
+|`deserialization`
+a|Emitted before starting deserialization and decompression. If you want to measure this phase duration, you should measure the time elapsed between this event and `response`. _(This event might not be emitted in certain situations)_.
+[source,js]
+----
+client.on('deserialization', (err, result) => {
+  console.log(err, result)
+})
+----
+
 |`response`
 a|Emitted once {es} response has been received and parsed.
 [source,js]
@@ -87,7 +105,7 @@ client.on('resurrect', (err, result) => {
 
 |===
 
-The values of `result` in `request`, `response` and `sniff` will be:
+The values of `result` in `serialization`, `request`, `deserialization`, `response` and `sniff` will be:
 
 [source,ts]
 ----
@@ -127,6 +145,29 @@ request: {
 };
 ----
 
+[discrete]
+==== Events order
+
+The event order is described in the following graph, in some edge cases, the order is not guaranteed.
+You can find in https://github.com/elastic/elasticsearch-js/blob/master/test/acceptance/events-order.test.js[`test/acceptance/events-order.test.js`] how the order changes based on the situation.
+
+[source]
+----
+serialization
+  │
+  │ (serialization and compression happens between those two events)
+  │
+  └─▶ request
+        │
+        │ (actual time spent over the wire)
+        │
+        └─▶ deserialization
+              │
+              │ (deserialization and decompression happens between those two events)
+              │
+              └─▶ response
+----
+
 
 [discrete]
 === Correlation id

index.d.ts

@@ -2573,8 +2573,10 @@ declare class Client {
 }
 
 declare const events: {
-  RESPONSE: string;
+  SERIALIZATION: string;
   REQUEST: string;
+  DESERIALIZATION: string;
+  RESPONSE: string;
   SNIFF: string;
   RESURRECT: string;
 };

index.js

@@ -314,7 +314,9 @@ const events = {
   RESPONSE: 'response',
   REQUEST: 'request',
   SNIFF: 'sniff',
-  RESURRECT: 'resurrect'
+  RESURRECT: 'resurrect',
+  SERIALIZATION: 'serialization',
+  DESERIALIZATION: 'deserialization'
 }
 
 module.exports = {

lib/Transport.js

@@ -268,6 +268,8 @@ class Transport {
       if (!isCompressed) {
         response.setEncoding('utf8')
       }
+
+      this.emit('deserialization', null, result)
       response.on('data', onData)
       response.on('error', onEnd)
       response.on('end', onEnd)
@@ -340,6 +342,7 @@ class Transport {
       }
     }
 
+    this.emit('serialization', null, result)
     const headers = Object.assign({}, this.headers, lowerCaseHeaders(options.headers))
 
     if (options.opaqueId !== undefined) {
@@ -354,6 +357,7 @@ class Transport {
         try {
           params.body = this.serializer.serialize(params.body)
         } catch (err) {
+          this.emit('request', err, result)
           process.nextTick(callback, err, result)
           return transportReturn
         }
@@ -369,6 +373,7 @@ class Transport {
         try {
           params.body = this.serializer.ndserialize(params.bulkBody)
         } catch (err) {
+          this.emit('request', err, result)
           process.nextTick(callback, err, result)
           return transportReturn
         }
@@ -408,6 +413,7 @@ class Transport {
         gzip(params.body, (err, buffer) => {
           /* istanbul ignore next */
           if (err) {
+            this.emit('request', err, result)
             return callback(err, result)
           }
           params.headers['content-encoding'] = compression