Introducing Elastic's OpenTelemetry Distribution for Node.js

We are delighted to announce the alpha release of the Elastic OpenTelemetry Distribution for Node.js. This distribution is a light wrapper around the OpenTelemetry Node.js SDK that makes it easier to get started using OpenTelemetry to observe your Node.js applications.

Background

Elastic is standardizing on OpenTelemetry (OTel) for observability and security data collection. As part of that effort, we are providing distributions of the OpenTelemetry Language SDKs. Our Android and iOS SDKs have been OpenTelemetry-based from the start, and we have recently released alpha distributions for Java and .NET. The Elastic OpenTelemetry Distribution for Node.js is the latest addition.

Getting started

To get started with the Elastic OTel Distribution for Node.js (the "distro"), you need only install and load a single npm dependency (@elastic%2Fopentelemetry-node). The distro sets up the collection of traces, metrics, and logs for a number of popular Node.js packages. It sends data to any OTLP endpoint you configure. This could be a standard OTel Collector or, as shown below, an Elastic Observability cloud deployment.

npm install --save @elastic/opentelemetry-node  # (1) install the SDK

# (2) configure it, for example:
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ...REDACTED..."
export OTEL_SERVICE_NAME=my-service

# (3) load and start it
node --require @elastic/opentelemetry-node my-service.js

A small example with Express and PostgreSQL

For a concrete example, let's look at a small Node.js "Shortlinks" service implemented using the Express web framework and the pgPostgreSQL client package. This service provides a POST %2F route for creating short links (a short name for a URL) and a GET %2F:shortname route for using them.

The git repository is here. The README shows how to create a free trial Elastic cloud deployment and get the appropriate OTEL_... config settings. Try it out (prerequisites are Docker and Node.js v20 or later):

git clone https://github.com/elastic/elastic-otel-node-example.git
cd elastic-otel-node-example
npm install

cp config.env.template config.env
# Edit OTEL_ values in "config.env" to point to your collection endpoint.

npm run db:start
npm start

The only steps needed to set up observability are these small changes to the "package.json" file and configuring a few standard OTEL_... environment variables.

  // ...
  "scripts": {
	"start": "node --env-file=./config.env -r @elastic/opentelemetry-node lib/app.js"
  },
  "dependencies": {
	"@elastic/opentelemetry-node": "*",
  // ...

The result is an observable application using the industry-standard OpenTelemetry — offering high-quality instrumentation of many popular Node.js libraries, a portable API to avoid vendor lock-in, and an active community.

Using Elastic Observability, some out-of-the-box benefits you can expect are: rich trace viewing, Service maps, integrated metrics and log analysis, and more. The distro ships host-metrics and Kibana provides a curated service metrics UI. There is out-of-the-box sending of logs for the popular Winston and Bunyan logging frameworks, with support planned for Pino.

What's next?

Elastic is committed to helping OpenTelemetry succeed and to helping our customers use OpenTelemetry effectively in their systems. Last year, we donated ECS and continue to work on integrating it with OpenTelemetry Semantic Conventions. More recently, we are working on donating our eBPF-based profiler to OpenTelemetry. We contribute to many of the language SDKs and other OpenTelemetry projects.

As authors of the Node.js distribution, we are excited to work with the OpenTelemetry JavaScript community and to help make the JS API & SDK a more robust, featureful, and obvious choice for JavaScript observability. Having a distro gives us the flexibility to build features on top of the vanilla OTel SDK. Currently, some advantages of the distro include: single package for installation, easy auto-instrumentation with reasonable default configuration, ESM enabled by default, and automatic logs telemetry sending. We will certainly contribute features upstream to the OTel JavaScript project when possible and will include additional features in the distro when it makes more sense for them to be there.

The Elastic OpenTelemetry Distribution for Node.js is currently an alpha. Please try it out and let us know if it might work for you. Watch for the latest releases here. You can engage with us on the project issue tracker or Elastic's Node.js APM Discuss forum.

The release and timing of any features or functionality described in this post remain at Elastic's sole discretion. Any features or functionality not currently available may not be delivered on time or at all.