OpenTelemetry Dice Rolling Demo

This project demonstrates OpenTelemetry instrumentation in a Node.js application with a custom OTLP collector for receiving telemetry data.

Project Structure

• dice-server.ts - Express server with dice rolling endpoints
• dice-lib.ts - Business logic with OpenTelemetry spans
• collector-server.js - Mock OTLP collector to receive traces and metrics
• instrumentation.ts - OpenTelemetry SDK configuration

Prerequisites

• Node.js (version 14 or higher)
• npm

Installation

Install the required dependencies:

npm install

Running the Application

1. Start the Collector Server

The collector server receives and logs telemetry data from your instrumented application.

npm run collector

This will start the collector on http://localhost:4318 and you should see:

Collector rodando em http://localhost:4318

2. Start the Dice Server (Instrumented Application)

In a new terminal, start the instrumented dice rolling server:

npm start

This will start the dice server on http://localhost:8080 and you should see:

Listening for requests on http://localhost:8080

Note: The --require ./instrumentation.ts flag is important as it loads the OpenTelemetry instrumentation before your application starts.

3. Test the Application

Make a request to roll some dice:

curl "http://localhost:8080/rolldice?rolls=3"

You should see:

• The dice results returned as JSON
• Console output in the dice server terminal showing the rolled numbers
• Detailed telemetry data logged in the collector server terminal, including:
  • Trace spans showing the execution flow
  • Events and attributes from the dice rolling operations
  • Parent-child relationships between spans

API Endpoints

Dice Server (http://localhost:8080)

• GET /rolldice?rolls=<number> - Roll dice the specified number of times

Example:

curl "http://localhost:8080/rolldice?rolls=5"

Collector Server (http://localhost:4318)

• POST /v1/traces - Receives OTLP trace data
• POST /v1/metrics - Receives OTLP metrics data
• GET /v1/metrics - Health check endpoint

Understanding the Output

When you make requests, you'll see spans in the collector logs with the following structure:

1. rollTheDice - Root span for the entire operation
2. rollOnce:0, rollOnce:1, etc. - Child spans for each individual dice roll
3. logNumber - Nested spans within each roll that include:
   • Events: number-rolled, number-resolved
   • Attributes: lastRolled with the dice value

Troubleshooting

• "req.body is undefined": Make sure the collector server is running and has the JSON parsing middleware
• No telemetry data: Ensure you're using --require ./instrumentation.ts when starting the dice server
• Connection errors: Verify both servers are running on the correct ports (4318 for collector, 8080 for dice server)

Development Notes

• The collector server uses JSON.stringify(req.body, null, 2) to format the telemetry data for easy reading
• The instrumentation uses HTTP/JSON exporters instead of protobuf for easier debugging
• All spans are properly nested using startActiveSpan for automatic parent-child relationships