Step 1: Install Dependencies

Ensure all necessary dependencies are installed in your development environment. If you are working in a Node.js-based setup, you can install the required OpenTelemetry packages via npm:

npm install @opentelemetry/sdk-node @opentelemetry/tracing @opentelemetry/exporter-zipkin

This installs the Node SDK, tracing capabilities, and the Zipkin exporter.

Step 2: Set Up Basic Tracing

In your main application file (e.g., app.js), you can initiate the OpenTelemetry tracing setup. Below is a sample code implementation:

const { NodeTracerProvider } = require('@opentelemetry/sdk-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
const { Tracer } = require('@opentelemetry/api');

// Create and configure the provider
const provider = new NodeTracerProvider();
const exporter = new ZipkinExporter({
  serviceName: 'my-service',
});

// Register the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
provider.register();

const tracer = provider.getTracer('my-service');

// Example usage of tracer
const span = tracer.startSpan('my-span');
span.end();

This code sets up a basic tracing configuration with Zipkin as the exporter.

Step 3: Configure Sampling

You can configure sampling by specifying a sampler in the tracer provider:

const { ParentBasedSampler, TraceIdRatioBasedSampler } = require('@opentelemetry/core');

const provider = new NodeTracerProvider({
  sampler: new ParentBasedSampler({
    root: new TraceIdRatioBasedSampler(0.1), // 10% sampling
  }),
});

In this setup, only 10% of the traces will be sampled and sent to the exporter.

Step 4: Instrumentation

To automatically instrument your application, you can use the @opentelemetry/instrumentation package, which generates spans for various Node.js HTTP requests and other protocols:

const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');

registerInstrumentations({
  instrumentations: [
    new ExpressInstrumentation(),
    // You can add other instrumentations as needed
  ],
});

Make sure to include the instrumentation registration before you register the provider.

Step 5: Configure Environment Variables

Environment variables are often used to configure various aspects of telemetry, such as the endpoint for the Zipkin exporter. You can set these in your shell environment or in a .env file. Here’s an example of how to reference them in your application:

const exporter = new ZipkinExporter({
  serviceName: process.env.SERVICE_NAME || 'default-service',
  url: process.env.ZIPKIN_URL || 'http://localhost:9411/api/v2/spans',
});

Make sure to define these variables in your shell:

export SERVICE_NAME='my-service'
export ZIPKIN_URL='http://localhost:9411/api/v2/spans'

Step 6: Serve Static Files with SCSS and HTML

If your application serves web pages, you may need to configure a static file server. Below is an example using Express.js to serve SCSS and HTML files:

const express = require('express');
const path = require('path');

const app = express();

// Set up SCSS to CSS compilation
app.use(express.static(path.join(__dirname, 'public')));

// Route to serve HTML
app.get('/', function(req, res) {
    res.sendFile(path.join(__dirname, 'public', 'index.html'));
});

Ensure your SCSS files are compiled to CSS before serving.

Step 7: Define Shell Commands in Makefile

You may want to automate the start and build processes of your OpenTelemetry application. Create a Makefile with relevant commands:

run:
    npm start

build:
    npm run build

clean:
    rm -rf node_modules

Using make run, make build, and make clean will facilitate the management of your Node.js application.

Conclusion

This configuration enables a comprehensive setup for tracing and instrumentation using OpenTelemetry in your development environment. Ensure that you adjust parameters as needed and reference the OpenTelemetry documentation for more complex scenarios.

Source: adaptions from OpenTelemetry Node.js documentation and instrumentation details.