A "Shortlinks" service, an elastic-otel-node Example

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.

Usage

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.

Observability with @elastic/opentelemetry-node

The interesting thing here is how easy it is to enable OpenTelemetry-based observability of this app. The steps are:

1. 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
   

2. Install the Elastic OpenTelemetry Node.js distro as a dependency. This is already done in "package.json".

   npm install --save @elastic/opentelemetry-node

3. 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:

What next?

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.