Getting Started with TypeScript

From Zero to Traced in 10 Minutes

When I first integrated OpenTelemetry into my production services, I was surprised by how quickly I could get valuable telemetry. Within 10 minutes of adding the SDK, I had automatic traces for every HTTP request, database query, and Redis operation - without changing a single line of application code.

This article walks you through that same experience. You'll build a TypeScript Express API, add OpenTelemetry instrumentation, and see distributed traces flowing to Jaeger - all from scratch.

Prerequisites

Before we start, ensure you have:

node --version  # v18.0.0 or higher (v20+ recommended)
npm --version   # 9.0.0 or higher

Optional but recommended:

• Docker for running Jaeger locally

• Basic familiarity with Express.js

• Understanding of async/await in TypeScript

Project Setup

Let's create a new TypeScript project from scratch:

# Create project directory
mkdir otel-express-demo
cd otel-express-demo

# Initialize npm project
npm init -y

# Install TypeScript and development tools
npm install -D typescript @types/node tsx

# Initialize TypeScript configuration
npx tsc --init

Configure TypeScript (tsconfig.json):

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

Update package.json scripts:

{
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/app.ts",
    "start": "tsx src/app.ts",
    "build": "tsc"
  }
}

Building the Base Application

First, let's create a simple Express API without any OpenTelemetry instrumentation.

Install Express dependencies:

npm install express
npm install -D @types/express

Create src/app.ts:

import express, { Express, Request, Response } from 'express';

const PORT = parseInt(process.env.PORT || '3000');
const app: Express = express();

app.use(express.json());

// Simple in-memory database simulation
interface Order {
  id: string;
  userId: string;
  amount: number;
  status: 'pending' | 'processing' | 'completed' | 'failed';
  createdAt: Date;
}

const orders: Map<string, Order> = new Map();

// Helper function to simulate async operations
function delay(ms: number): Promise<void> {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// Simulate database query
async function findOrderById(id: string): Promise<Order | undefined> {
  await delay(50); // Simulate DB latency
  return orders.get(id);
}

// Simulate payment processing
async function processPayment(orderId: string, amount: number): Promise<boolean> {
  await delay(200); // Simulate external API call
  return Math.random() > 0.1; // 90% success rate
}

// Routes
app.get('/health', (req: Request, res: Response) => {
  res.json({ status: 'healthy', timestamp: new Date().toISOString() });
});

app.post('/api/orders', async (req: Request, res: Response) => {
  try {
    const { userId, amount } = req.body;
    
    if (!userId || !amount) {
      return res.status(400).json({ error: 'userId and amount are required' });
    }

    const orderId = `ORD-${Date.now()}`;
    const order: Order = {
      id: orderId,
      userId,
      amount,
      status: 'pending',
      createdAt: new Date()
    };

    orders.set(orderId, order);

    // Update status to processing
    order.status = 'processing';
    
    // Process payment
    const paymentSuccess = await processPayment(orderId, amount);
    
    if (paymentSuccess) {
      order.status = 'completed';
      res.status(201).json(order);
    } else {
      order.status = 'failed';
      res.status(402).json({ error: 'Payment failed', order });
    }
  } catch (error) {
    console.error('Error creating order:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.get('/api/orders/:id', async (req: Request, res: Response) => {
  try {
    const order = await findOrderById(req.params.id);
    
    if (!order) {
      return res.status(404).json({ error: 'Order not found' });
    }
    
    res.json(order);
  } catch (error) {
    console.error('Error fetching order:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Health check: http://localhost:${PORT}/health`);
});

Test the application:

npm run dev

# In another terminal:
curl http://localhost:3000/health

# Create an order
curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{"userId": "user123", "amount": 99.99}'

# Get the order (use the ID from previous response)
curl http://localhost:3000/api/orders/ORD-1704705825000

Great! Our API works, but we have zero visibility into what's happening inside.

Adding OpenTelemetry

Now comes the magic - we'll add comprehensive observability with minimal code changes.

Install OpenTelemetry packages:

npm install @opentelemetry/sdk-node \
  @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/sdk-trace-node \
  @opentelemetry/sdk-metrics

Create src/instrumentation.ts:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import {
  PeriodicExportingMetricReader,
  ConsoleMetricExporter,
} from '@opentelemetry/sdk-metrics';
import { Resource } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  // Service identification
  resource: new Resource({
    [ATTR_SERVICE_NAME]: 'order-service',
    [ATTR_SERVICE_VERSION]: '1.0.0',
  }),
  
  // Export traces to console (we'll change this to Jaeger later)
  traceExporter: new ConsoleSpanExporter(),
  
  // Export metrics to console
  metricReader: new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
    exportIntervalMillis: 10000, // Export every 10 seconds
  }),
  
  // Automatic instrumentation for popular libraries
  instrumentations: [getNodeAutoInstrumentations()],
});

// Start the SDK
sdk.start();

// Graceful shutdown
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => console.log('OpenTelemetry SDK shut down successfully'))
    .catch((error) => console.error('Error shutting down SDK', error))
    .finally(() => process.exit(0));
});

console.log('OpenTelemetry instrumentation initialized');

Update package.json to load instrumentation before app:

{
  "scripts": {
    "dev": "tsx --import ./src/instrumentation.ts src/app.ts",
    "start": "tsx --import ./src/instrumentation.ts src/app.ts"
  }
}

That's it! Now run the application:

npm run dev

You'll see:

OpenTelemetry instrumentation initialized
Server running on http://localhost:3000

Make some requests:

# Create an order
curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{"userId": "user456", "amount": 149.99}'

Check your console output - you'll see detailed trace information:

{
  "traceId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "parentId": undefined,
  "name": "POST /api/orders",
  "id": "q1w2e3r4t5y6u7i8",
  "kind": "SERVER",
  "timestamp": 1704705825000000,
  "duration": 250123,
  "attributes": {
    "http.url": "http://localhost:3000/api/orders",
    "http.host": "localhost:3000",
    "http.method": "POST",
    "http.scheme": "http",
    "http.target": "/api/orders",
    "http.user_agent": "curl/7.81.0",
    "http.status_code": 201
  }
}

Without changing a single line of application code, we now have:

• ✅ Automatic tracing for every HTTP request

• ✅ Request duration measurements

• ✅ HTTP status codes

• ✅ URL paths and methods

• ✅ User agent information

Setting Up Jaeger for Visualization

Console output is great for learning, but let's visualize traces properly with Jaeger.

Start Jaeger using Docker:

docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest

Install OTLP exporter:

npm install @opentelemetry/exporter-trace-otlp-http

Update src/instrumentation.ts:

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { Resource } from '@opentelemetry/resources';
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: 'order-service',
    [ATTR_SERVICE_VERSION]: '1.0.0',
  }),
  
  // Export to Jaeger via OTLP
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
  
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('SDK shut down'))
    .catch((error) => console.error('Shutdown error', error))
    .finally(() => process.exit(0));
});

console.log('OpenTelemetry → Jaeger configured');

Restart your application and make some requests:

npm run dev

# Create several orders
for i in {1..5}; do
  curl -X POST http://localhost:3000/api/orders \
    -H "Content-Type: application/json" \
    -d "{\"userId\": \"user$i\", \"amount\": $(($i * 25))}"
  sleep 1
done

# Fetch some orders
curl http://localhost:3000/api/orders/ORD-1704705825000

Open Jaeger UI: http://localhost:16686

• Select service: order-service

• Click "Find Traces"

• Click on any trace to see the detailed timeline

You'll see beautiful visualizations showing:

• Total request duration

• Individual operation timing

• Request metadata (URL, method, status code)

• Hierarchical span relationships

Adding Custom Instrumentation

Auto-instrumentation is great, but let's add custom spans to track our business logic.

Update src/app.ts to import the tracer:

import express, { Express, Request, Response } from 'express';
import { trace, context, SpanStatusCode } from '@opentelemetry/api';

const PORT = parseInt(process.env.PORT || '3000');
const app: Express = express();

// Get a tracer for custom instrumentation
const tracer = trace.getTracer('order-service', '1.0.0');

app.use(express.json());

// ... (keep existing interfaces and maps)

// Updated findOrderById with custom span
async function findOrderById(id: string): Promise<Order | undefined> {
  return tracer.startActiveSpan('findOrderById', async (span) => {
    try {
      span.setAttribute('order.id', id);
      await delay(50);
      const order = orders.get(id);
      
      if (order) {
        span.setAttribute('order.found', true);
        span.setAttribute('order.status', order.status);
      } else {
        span.setAttribute('order.found', false);
      }
      
      return order;
    } finally {
      span.end();
    }
  });
}

// Updated processPayment with custom span
async function processPayment(orderId: string, amount: number): Promise<boolean> {
  return tracer.startActiveSpan('processPayment', async (span) => {
    try {
      span.setAttribute('order.id', orderId);
      span.setAttribute('payment.amount', amount);
      span.setAttribute('payment.currency', 'USD');
      
      await delay(200);
      const success = Math.random() > 0.1;
      
      span.setAttribute('payment.success', success);
      
      if (!success) {
        span.setStatus({
          code: SpanStatusCode.ERROR,
          message: 'Payment processing failed'
        });
      }
      
      return success;
    } catch (error) {
      span.recordException(error as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      span.end();
    }
  });
}

// ... (keep existing routes)

Restart and test:

npm run dev

# Make requests and check Jaeger
curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{"userId": "user999", "amount": 299.99}'

Now in Jaeger, you'll see your custom spans (findOrderById, processPayment) nested under the HTTP request span, with all the custom attributes you added!

What We've Accomplished

In less than 10 minutes, you've:

✅ Built a TypeScript Express API from scratch ✅ Added OpenTelemetry SDK with auto-instrumentation ✅ Exported traces to Jaeger ✅ Created custom spans for business logic ✅ Added meaningful attributes to spans ✅ Visualized distributed traces in Jaeger UI

Real-World Insights

This simple setup has already given you superpowers:

Performance Analysis: You can now see that processPayment takes 200ms while findOrderById takes only 50ms. If users complain about slow checkout, you know exactly where to optimize.

Error Debugging: When a payment fails, you can find the exact trace, see all the attributes (order ID, amount, user ID), and understand the complete context.

Usage Patterns: By analyzing traces in Jaeger, you can see which endpoints are called most frequently and optimize accordingly.

Next Steps

You've successfully instrumented your first TypeScript application! Continue to Automatic Instrumentation where you'll:

• Explore all available auto-instrumentation libraries

• Add PostgreSQL and Redis to your application

• See automatic traces for database queries

• Learn how to configure instrumentation libraries

• Understand what gets traced automatically vs what needs custom spans

---

Previous: ← OpenTelemetry Fundamentals | Next: Automatic Instrumentation →

You just gained x-ray vision into your application. Use it wisely.