@elastic/opentelemetry-node
v0.3.0
Published
Elastic Distribution for OpenTelemetry Node.js
Downloads
120
Maintainers
Readme
Elastic Distribution for OpenTelemetry Node.js
This is the Elastic Distribution for OpenTelemetry Node.js (the "Distro"). It is a light wrapper around the OpenTelemetry Node SDK that makes it easier to get started using OpenTelemetry in your Node.js applications, especially if you are using Elastic Observability as your observability solution.
Current status
The current release is alpha, and not yet recommended for production use. We welcome your feedback! You can reach us either on the issue tracker or on Elastic's Discuss forum.
Some limitations / notes:
- We expect to support most every instrumentation included in
@opentelemetry/auto-instrumentations-node
. However, currently only a subset is supported. See the supported instrumentations here.
Usage
# 1. install
npm install --save @elastic/opentelemetry-node
# 2. configure via OTEL_ envvars, for example:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://{your-otlp-endpoint.example.com}
export OTEL_EXPORTER_OTLP_HEADERS="Authorization={authorization-information}"
export OTEL_SERVICE_NAME=my-service
# 3. start
node -r @elastic/opentelemetry-node my-service.js
If using an Elastic Observability deployment
to which to send telemetry data, the OTEL_EXPORTER_*
settings will look
something like:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://{deployment-name}.apm.{cloud-region}.cloud.es.io
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {deployment-secret-token}"
The Distro will automatically instrument popular modules (see supported instrumentations)) used by your service, and send trace, metrics, and logs telemetry data (using OTLP) to your configured observability backend.
The Distro can be configured via OTEL_*
environment variables, per the
OpenTelemetry Environment Variable spec.
See the Getting Started guide for more details.
Documentation
Why this distribution?
As mentioned above, this Distro is a wrapper around the OpenTelemetry Node
SDK (@opentelemetry/sdk-node
). So why the separate package?
A few reasons:
With this separate package we hope to experiment with making it easier to get started with OpenTelemetry instrumentation in Node.js services. For example,
@elastic/opentelemetry-node
includes a number of OTel packages as dependencies, so the user only needs to install/update a single package -- at least for the default use case. This is similar to the OTel@opentelemetry/auto-instrumentations-node
package.Having a separate package will sometimes allow us to iterate more quickly with changes in SDK behavior. However, our plan is to upstream any improvements to the OpenTelemetry JS repositories.
Should it be necessary, having a separate package would allow us to more quickly release a fix for a particular issue required by a customer of ours.
Providing an eventual easy migration path for customers of our current non-OpenTelemetry-based Node.js APM agent to this SDK may be made easier by having our own package entry point.