How to Instrument an Application with OpenTelemetry

What and why

OpenTelemetry (OTel) is a vendor-neutral standard for generating and exporting telemetry: traces, metrics, and logs. Instrumenting once with OTel lets you switch backends (Jaeger, Tempo, Prometheus, a commercial vendor) without rewriting code. This tutorial instruments a service and ships signals through the OpenTelemetry Collector.

Prerequisites

• A running HTTP service you can modify.
• A telemetry backend such as Jaeger for traces.
• Docker, to run the Collector locally.

Steps

1. Install the SDK and instrumentation

For Node.js:

npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

Every major language has an equivalent SDK (Python opentelemetry-distro, Java agent JAR, Go go.opentelemetry.io/otel).

2. Initialize the tracer provider

Create tracing.js loaded before your app:

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({ url: 'http://localhost:4318/v1/traces' }),
  instrumentations: [getNodeAutoInstrumentations()],
});
sdk.start();

Set the service name through the resource so spans are attributable:

export OTEL_SERVICE_NAME=checkout-service

3. Enable auto-instrumentation

Load the file before everything else:

node -r ./tracing.js app.js

Auto-instrumentation patches HTTP, Express, database drivers, and more, producing spans with no code changes.

4. Add manual spans and attributes

For business-specific work, create spans explicitly:

const { trace } = require('@opentelemetry/api');
const tracer = trace.getTracer('checkout');
await tracer.startActiveSpan('apply-discount', async (span) => {
  span.setAttribute('cart.items', items.length);
  // ... work ...
  span.end();
});

5. Run the OpenTelemetry Collector

Use the Collector as a single egress point. A minimal collector.yaml:

receivers:
  otlp:
    protocols:
      http:
      grpc:
exporters:
  otlp/jaeger:
    endpoint: jaeger:4317
    tls: { insecure: true }
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp/jaeger]

Run it: docker run -p 4318:4318 -v $(pwd)/collector.yaml:/etc/otelcol/config.yaml otel/opentelemetry-collector.

6. Export and verify signals

Generate traffic against your service, then open the Jaeger UI and search for checkout-service. You should see traces with nested spans for HTTP and database calls.

Verification

• Spans appear in your backend with the correct service name.
• A single request produces a connected trace across spans.
• Custom attributes (such as cart.items) are visible on manual spans.

Next Steps

Add metrics and log exporters to the same Collector pipeline, propagate context across services with W3C Trace Context headers, and sample high-volume traces to control cost.