This repository holds a small Node.js service, called "Shortlinks", to demonstrate usage of
@elastic/opentelemetry-node
(the Elastic OpenTelemetry Distribution for Node.js) in
instrumenting Node.js apps for observability.
The app is a barebones shortlinks service: add a URL with a shortname, then
use the service to redirect to that URL. This implementation uses PostgreSQL
to store shortlinks (using the pg
client package), and express
for the
HTTP server.
The Elastic OpenTelemetry Distribution for Node.js (the "Distro") is light wrapper around the core OpenTelemetry JS SDK. It provides for convenient usage of the SDK for Node.js. It works with any downstream OpenTelemetry-compatible collector, of which an Elastic Observability cloud deployment is one.
As prerequisites, this demo assumes you have Docker installed and are running
Node.js v20 or later. (This uses Node.js v20 for the convenience of its
--env-file
option.)
Download and start the service:
git clone https://github.com/elastic/elastic-otel-node-example.git
cd elastic-otel-node-example
npm install
cp config.env.template config.env
vim config.env # Edit the OTEL_ values as appropriate (see section below)
npm run db:start # Start PostgreSQL in Docker and setup table(s)
npm start # Start the service at http://127.0.0.1:3000/
To try it out, first add a shortlink at http://127.0.0.1:3000/ or via the CLI:
curl http://127.0.0.1:3000/ -X POST -d shortname=el -d url=https://elastic.co
Then open http://127.0.0.1:3000/el in your browser. You should be redirected.
That is mostly it. When you are done, run npm run db:stop
to stop the
PostgreSQL container. The link data is not persisted outside of the container.
Definitely barebones.
@elastic/opentelemetry-node
The interesting thing here is how easy it is to enable OpenTelemetry-based observability of this app. The steps are:
You'll need somewhere to send the gathered OpenTelemetry data, so it can be viewed and analyzed. The @elastic/opentelemetry-node
package supports sending to any OTLP endpoint (e.g. an OpenTelemetry collector instance). Here we will show using an Elastic Observability cloud deployment.
If you don't have an Elastic cloud deployment, you can start a free trial. After registering, click "Create deployment". Once that is created you should visit your Kibana home page, https://{DEPLOYMENT_NAME}.kb.{REGION}.cloud.es.io/app/home#/getting_started
.
To configure @elastic/opentelemetry-node
you'll need the deployment's OTLP endpoint and authorization header to set the appropriate OTLP_*
environment variables. You can find these in Kibana's APM tutorial.
To configure the Shortlinks service, copy the "config.env.template" file to "config.env" and fill in the values for your Elastic cloud deployment. For example:
...
OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer P....I"
OTEL_SERVICE_NAME=shortlinks
Install the Elastic OpenTelemetry Node.js distro as a dependency. This is already done in "package.json".
npm install --save @elastic/opentelemetry-node
Use the Node.js -r, --require
option to load and start the distro. This is already setup in the npm start
script in "package.json".
node --env-file ./config.env -r @elastic/opentelemetry-node lib/app.js
If all has gone well, then after some usage of the service, you will see telemetry data for the shortlinks service in the "APM" section of Kibana.
For example, the "Transactions" section of "shortlinks" service overview page shows the top routes of the service:
A trace of the GET /:shortname
route shows Express middleware and PostgresSQL
client handling for that endpoint:
See the Elastic OpenTelemetry Distribution for Node.js project for more details on the distro.
See the Elastic APM guide for features of Elastic Observability.