Documentation for OpenTelemetry support (#2289)
* Documentation for OpenTelemetry support * Update docs/observability.asciidoc Co-authored-by: Miguel Grinberg <miguel.grinberg@gmail.com> * Fix docs typo * Fix bad link references in asciidoc changelog * Drop link to 8.15 changelog For now. Link just doesn't work yet. --------- Co-authored-by: Miguel Grinberg <miguel.grinberg@gmail.com>
This commit is contained in:
Josh Mock
@ -1,6 +1,19 @@
|
||||
[[changelog-client]]
|
||||
== Release notes
|
||||
|
||||
[discrete]
|
||||
=== 8.15.0
|
||||
|
||||
[discrete]
|
||||
==== Features
|
||||
|
||||
[discrete]
|
||||
===== OpenTelemetry zero-code instrumentation support
|
||||
|
||||
For those that use an observability service that supports OpenTelemetry spans, the client will now automatically generate traces for each Elasticsearch request it makes.
|
||||
See {jsclient}/observability.html#_opentelemetry[the docs]
|
||||
for more information.
|
||||
|
||||
[discrete]
|
||||
=== 8.14.0
|
||||
|
||||
@ -198,7 +211,7 @@ https://www.elastic.co/guide/en/elasticsearch/reference/8.9/release-notes-8.9.0.
|
||||
[discrete]
|
||||
===== Allow document to be overwritten in `onDocument` iteratee of bulk helper https://github.com/elastic/elasticsearch-js/pull/1732[#1732]
|
||||
|
||||
In the https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-helpers.html#bulk-helper[bulk helper], documents could not be modified before being sent to Elasticsearch. It is now possible to https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-helpers.html#_modifying_a_document_before_operation[modify a document] before sending it.
|
||||
In the {jsclient}/client-helpers.html#bulk-helper[bulk helper], documents could not be modified before being sent to Elasticsearch. It is now possible to {jsclient}/client-helpers.html#_modifying_a_document_before_operation[modify a document] before sending it.
|
||||
|
||||
[discrete]
|
||||
==== Fixes
|
||||
|
||||
@ -1,24 +1,52 @@
|
||||
[[observability]]
|
||||
=== Observability
|
||||
|
||||
The client does not provide a default logger, but instead it offers an event
|
||||
To observe and measure Elasticsearch client usage, several client features are provided.
|
||||
|
||||
First, as of 8.15.0, the client provides native support for OpenTelemetry, which allows you to send client usage data to any endpoint that supports OpenTelemetry without having to make any changes to your JavaScript codebase.
|
||||
|
||||
Also, rather than providing a default logger, the client offers an event
|
||||
emitter interface to hook into internal events, such as `request` and
|
||||
`response`.
|
||||
`response`, allowing you to log the events you care about, or otherwise react
|
||||
to client usage however you might need.
|
||||
|
||||
Correlating those events can be hard, especially if your applications have a
|
||||
large codebase with many events happening at the same time.
|
||||
Correlating events can be hard, especially if your applications have a large codebase with many events happening at the same time. To help you with this, the client provides a correlation ID system, and other
|
||||
features.
|
||||
|
||||
To help you with this, the client offers you a correlation id system and other
|
||||
features. Let's see them in action.
|
||||
All of these observability features are documented below.
|
||||
|
||||
[discrete]
|
||||
==== OpenTelemetry
|
||||
|
||||
The client supports OpenTelemetry's https://opentelemetry.io/docs/zero-code/js/[zero-code
|
||||
instrumentation] to enable tracking each client request as an
|
||||
https://opentelemetry.io/docs/concepts/signals/traces/#spans[OpenTelemetry span]. These spans
|
||||
follow all of the https://opentelemetry.io/docs/specs/semconv/database/elasticsearch/[semantic
|
||||
OpenTelemetry conventions for Elasticsearch] except for `db.query.text`.
|
||||
|
||||
To start sending Elasticsearch trace data to your OpenTelemetry endpoint, follow
|
||||
https://opentelemetry.io/docs/zero-code/js/[OpenTelemetry's zero-code instrumentation guide],
|
||||
or the following steps:
|
||||
|
||||
1. Install `@opentelemetry/api` and `@opentelemetry/auto-instrumentations-node` as Node.js dependencies
|
||||
2. Export the following environment variables with the appropriate values:
|
||||
- `OTEL_EXPORTER_OTLP_ENDPOINT`
|
||||
- `OTEL_EXPORTER_OTLP_HEADERS`
|
||||
- `OTEL_RESOURCE_ATTRIBUTES`
|
||||
- `OTEL_SERVICE_NAME`
|
||||
3. `require` the Node.js auto-instrumentation library at startup:
|
||||
[source,bash]
|
||||
----
|
||||
node --require '@opentelemetry/auto-instrumentations-node/register' index.js
|
||||
----
|
||||
|
||||
[discrete]
|
||||
==== Events
|
||||
|
||||
The client is an event emitter, this means that you can listen for its event and
|
||||
add additional logic to your code, without need to change the client internals
|
||||
or your normal usage. You can find the events names by access the `events` key
|
||||
of the client.
|
||||
The client is an event emitter. This means that you can listen for its events to
|
||||
add additional logic to your code, without needing to change the client's internals
|
||||
or how you use the client. You can find the events' names by accessing the `events` key
|
||||
of the client:
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -26,9 +54,8 @@ const { events } = require('@elastic/elasticsearch')
|
||||
console.log(events)
|
||||
----
|
||||
|
||||
|
||||
The event emitter functionality can be useful if you want to log every request,
|
||||
response and error that is happening during the use of the client.
|
||||
response or error that is created by the client:
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -48,7 +75,6 @@ client.diagnostic.on('response', (err, result) => {
|
||||
})
|
||||
----
|
||||
|
||||
|
||||
The client emits the following events:
|
||||
[cols=2*]
|
||||
|===
|
||||
@ -135,7 +161,6 @@ meta: {
|
||||
};
|
||||
----
|
||||
|
||||
|
||||
While the `result` value in `resurrect` is:
|
||||
|
||||
[source,ts]
|
||||
@ -175,9 +200,8 @@ serialization
|
||||
└─▶ response
|
||||
----
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Correlation id
|
||||
==== Correlation ID
|
||||
|
||||
Correlating events can be hard, especially if there are many events at the same
|
||||
time. The client offers you an automatic (and configurable) system to help you
|
||||
@ -211,8 +235,7 @@ client.search({
|
||||
}).then(console.log, console.log)
|
||||
----
|
||||
|
||||
|
||||
By default the id is an incremental integer, but you can configure it with the
|
||||
By default the ID is an incremental integer, but you can configure it with the
|
||||
`generateRequestId` option:
|
||||
|
||||
[source,js]
|
||||
@ -231,7 +254,7 @@ const client = new Client({
|
||||
----
|
||||
|
||||
|
||||
You can also specify a custom id per request:
|
||||
You can also specify a custom ID per request:
|
||||
|
||||
[source,js]
|
||||
----
|
||||
|
||||
Reference in New Issue
Block a user