Elasticsearch (#81)

* chore: update readme

Author: Yaniv Davidi

packages/instrumentation-elasticsearch/README.md

@@ -21,7 +21,15 @@ registerInstrumentations({
   traceProvider,
   instrumentations: [
     new ElasticsearchInstrumentation({
-      // see under for available configuration
+      // Config example (all optional)
+      suppressInternalInstrumentation: false,
+      moduleVersionAttributeName: 'elasticsearchClient.version',
+      responseHook: (span, result) => {
+        span.setAttribute('db.response', JSON.stringify(result));
+      },
+      dbStatementSerializer: (operation, params, options) => {
+        return JSON.stringify(params);
+      }
     })
   ]
 });
@@ -31,15 +39,26 @@ registerInstrumentations({
 
 Elasticsearch instrumentation has few options available to choose from. You can set the following (all optional):
 
-| Options        | Type                                   | Description                                                                                     |
-| -------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `suppressInternalInstrumentation` | `boolean` | Elasticsearch operation use http/https under the hood. Setting this to true will hide the underlying request spans (if instrumented). |
-| `responseHook` | `ElasticsearchResponseCustomAttributesFunction` | Hook called before response is returned, which allows to add custom attributes to span.      |
-| `dbStatementSerializer` | `DbStatementSerializer` | Elasticsearch instrumentation will serialize `db.statement` using the specified function.
-| `moduleVersionAttributeName` | `string` | If passed, a span attribute will be added to all spans with key of the provided `moduleVersionAttributeName` and value of the patched module version |
+| Options | Type | Default | Description |
+| --- | --- | --- | --- |
+| `suppressInternalInstrumentation` | `boolean` | `false` | Elasticsearch operation use http/https under the hood. Setting this to true will hide the underlying request spans (if instrumented). |
+| `responseHook` | `ResponseHook` (function) | `undefined` | Hook called before response is returned, which allows to add custom attributes to span.<br>Function receive params: `span`<br>`result` (object) |
+| `dbStatementSerializer` | `DbStatementSerializer` (function) | `JSON.stringify({params, options})` | Elasticsearch instrumentation will serialize `db.statement` using this function response.<br>Function receive params: `operation` (string)<br>`params` (object)<br>`options` (object)<br>Function response must be a `string`
+| `moduleVersionAttributeName` | `string` | `undefined` | If passed, a span attribute will be added to all spans with key of the provided `moduleVersionAttributeName` and value of the `@elastic/elasticsearch` version |
 
 Please make sure `dbStatementSerializer` is error proof, as errors are not handled while executing this function.
 
+### `db.operation` attribute
+`db.operation` contain the API function called. 
+For the full list see [API reference](https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference.html).
+
+Few examples: 
+* `client.bulk`
+* `client.search`
+* `client.index`
+* `cat.shards`
+* `cluster.health`
+
 ---
 
 This extension (and many others) was developed by [Aspecto](https://www.aspecto.io/) with ❤️

packages/instrumentation-elasticsearch/src/types.ts

@@ -3,7 +3,7 @@ import { InstrumentationConfig } from '@opentelemetry/instrumentation';
 
 export type DbStatementSerializer = (operation?: string, params?: object, options?: object) => string;
 
-export type ElasticsearchResponseCustomAttributesFunction = (span: Span, response: any) => void;
+export type ResponseHook = (span: Span, response: any) => void;
 
 export interface ElasticsearchInstrumentationConfig extends InstrumentationConfig {
     /**
@@ -19,7 +19,7 @@ export interface ElasticsearchInstrumentationConfig extends InstrumentationConfi
     dbStatementSerializer?: DbStatementSerializer;
 
     /** hook for adding custom attributes using the response payload */
-    responseHook?: ElasticsearchResponseCustomAttributesFunction;
+    responseHook?: ResponseHook;
 
     /**
      * If passed, a span attribute will be added to all spans with key of the provided "moduleVersionAttributeName"

packages/instrumentation-elasticsearch/src/utils.ts

@@ -1,5 +1,5 @@
 import { Tracer, SpanAttributes, SpanStatusCode, diag, Span, SpanKind } from '@opentelemetry/api';
-import { DbStatementSerializer, ElasticsearchResponseCustomAttributesFunction } from './types';
+import { DbStatementSerializer, ResponseHook } from './types';
 import { safeExecuteInTheMiddle } from '@opentelemetry/instrumentation';
 import { DatabaseAttribute, GeneralAttribute } from '@opentelemetry/semantic-conventions';
 import { ApiResponse } from '@elastic/elasticsearch/lib/Transport';
@@ -66,11 +66,7 @@ export function getNetAttributes(url: string): SpanAttributes {
     };
 }
 
-export function onResponse(
-    span: Span,
-    result: ApiResponse,
-    responseHook?: ElasticsearchResponseCustomAttributesFunction
-) {
+export function onResponse(span: Span, result: ApiResponse, responseHook?: ResponseHook) {
     span.setAttributes({
         ...getNetAttributes(result.meta.connection.url.toString()),
     });

packages/instrumentation-elasticsearch/test/utils.spec.ts

@@ -175,7 +175,7 @@ describe('elasticsearch utils', () => {
         const tracerMock = {
             startSpan: (name, options?, context?): any => {},
         };
-        it('should start span with client kink', () => {
+        it('should start span with client kind', () => {
             const startSpanStub = stub(tracerMock, 'startSpan');
 
             Utils.startSpan({