Tutorial: OTEL Instrumentation

Overview

Tracing data is an essential element to making a software system observable. Traces can be generated by instrumenting your application with OpenTelemetry Libraries & SDKs. This tutorial provides examples of using OpenTelemetry to instrument a Node.js application called Dice, and ship the resulting traces to an Observe tenant. There are four examples covered in this tutorial, using two instrumentation strategies; manual instrumentation, and auto-instrumentation.

The source code for these examples are available at the following GitHub page: https://github.com/observeinc/otel-autoinstrumentation-examples

Manual Instrumentation Examples

  • Run Local Raw - this will install the OTEL SDK for Node, instrument, and run the example Dice application on your local machine.

  • Run Local Docker - this will instrument the example Dice application via the OTEL SDK, create a container image, and run it via Docker Desktop.

  • Run in Kubernetes via local Docker - this will instrument the example Dice application via the OTEL SDK, create a container image and run it in Kubernetes, running via Docker Desktop.

Auto Instrumentation Example

  • Run in Kubernetes via local Docker - Create a container image of our Dice application without including the OTEL SDK for Node, and run it in Kubernetes. Using the OpenTelemetry Operator for Kubernetes, and associated “annotation” settings, the application will be auto-instrumented during deployment.

Getting started

Clone the examples repository at https://github.com/observeinc/otel-autoinstrumentation-examples to your local machine. There are container image build instructions in each directory (dice_auto and dice_manual). For step-by-step instructions, follow the specific README.MD files in each subdirectory.

dice_manual directory

Run Local Raw - this is done via the runme.sh script, and presumes you have NodeJS installed locally on your machine. Be sure to set the TENANT_ID and DATASTREAM_TOKEN.

Run Local Docker - this is done via the docker-compose.yml file and the associated docker compose up –build command. You need to ensure that the environment variables OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS are properly set with your Observe tenant and Ingest token.

Run in K8s via local Docker - you must enable K8s on your Docker install. The steps here are a bit more complex, and outlined in more detail in the repository.

Note

For examples 1 and 2, the dice application is reachable via http://localhost:8080.

For example 3, it’s reachable via https://localhost:30001.

dice_auto directory

Run in K8s via local Docker - Use the OTEL Operator for Kubernetes (again, you must enable K8s on your Docker install). The steps here are a bit more complex, but are outlined in the README.MD in the dice_auto directory.

Note

The dice application is reachable via https://localhost:30001.