Instrumenting TypeScript Applications: From Zero to Production Metrics

The First Time I Added Metrics

I still remember the first time I instrumented a TypeScript application with Prometheus. I was nervous—would it slow down my API? Would it be complicated? Would I break something in production?

Turns out, adding Prometheus metrics was one of the easiest and most impactful changes I've made. Within an hour, I had basic metrics flowing. Within a day, I had comprehensive monitoring. Within a week, I caught a performance issue I didn't even know existed.

Let me show you exactly how I do it, step by step.

Setting Up prom-client

The prom-client library is the official Prometheus client for Node.js. It has excellent TypeScript support and a clean API.

Installation

npm install prom-client
# or
yarn add prom-client

TypeScript Types

Good news: prom-client includes TypeScript definitions out of the box. No need for @types/prom-client.

Basic Setup: Exposing the /metrics Endpoint

Every Prometheus-instrumented application needs a /metrics endpoint. Let's start with the minimal setup.

Express Example

// src/metrics.ts
import { Registry, collectDefaultMetrics } from 'prom-client';

// Create a registry
export const register = new Registry();

// Collect default Node.js metrics (memory, CPU, event loop, etc.)
collectDefaultMetrics({
  register,
  prefix: 'nodejs_'
});

// src/server.ts
import express from 'express';
import { register } from './metrics';

const app = express();
const PORT = 3000;

// Your regular routes
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

// Prometheus metrics endpoint
app.get('/metrics', async (req, res) => {
  res.setHeader('Content-Type', register.contentType);
  res.send(await register.metrics());
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  console.log(`Metrics available at http://localhost:${PORT}/metrics`);
});

That's it! You now have a working /metrics endpoint.

Test it:

curl http://localhost:3000/metrics

You'll see output like:

# HELP nodejs_heap_size_total_bytes Process heap size from Node.js in bytes.
# TYPE nodejs_heap_size_total_bytes gauge
nodejs_heap_size_total_bytes 18874368

# HELP nodejs_heap_size_used_bytes Process heap size used from Node.js in bytes.
# TYPE nodejs_heap_size_used_bytes gauge
nodejs_heap_size_used_bytes 9876544

Fastify Example

If you use Fastify, here's the equivalent:

import Fastify from 'fastify';
import { register } from './metrics';

const server = Fastify();

server.get('/api/users', async (request, reply) => {
  return { users: [] };
});

server.get('/metrics', async (request, reply) => {
  reply.type('text/plain');
  return register.metrics();
});

server.listen({ port: 3000 }, (err, address) => {
  if (err) throw err;
  console.log(`Server listening at ${address}`);
});

NestJS Example

For NestJS fans:

// src/metrics/metrics.controller.ts
import { Controller, Get, Header } from '@nestjs/common';
import { register } from './metrics';

@Controller()
export class MetricsController {
  @Get('metrics')
  @Header('Content-Type', 'text/plain')
  async getMetrics(): Promise<string> {
    return register.metrics();
  }
}

Instrumenting HTTP Requests

Now let's track actual HTTP traffic. This is the most important metric for any API.

Complete HTTP Metrics Middleware

// src/metrics/http-metrics.ts
import { Counter, Histogram, Registry } from 'prom-client';

export const register = new Registry();

// Counter for total requests
export const httpRequestsTotal = new Counter({
  name: 'http_requests_total',
  help: 'Total number of HTTP requests',
  labelNames: ['method', 'route', 'status_code'] as const,
  registers: [register]
});

// Histogram for request duration
export const httpRequestDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of HTTP requests in seconds',
  labelNames: ['method', 'route', 'status_code'] as const,
  buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
  registers: [register]
});

// Histogram for request size
export const httpRequestSizeBytes = new Histogram({
  name: 'http_request_size_bytes',
  help: 'Size of HTTP requests in bytes',
  labelNames: ['method', 'route'] as const,
  buckets: [100, 1000, 5000, 10000, 50000, 100000, 500000, 1000000],
  registers: [register]
});

// Histogram for response size
export const httpResponseSizeBytes = new Histogram({
  name: 'http_response_size_bytes',
  help: 'Size of HTTP responses in bytes',
  labelNames: ['method', 'route', 'status_code'] as const,
  buckets: [100, 1000, 5000, 10000, 50000, 100000, 500000, 1000000],
  registers: [register]
});

// src/middleware/metrics.middleware.ts
import { Request, Response, NextFunction } from 'express';
import {
  httpRequestsTotal,
  httpRequestDuration,
  httpRequestSizeBytes,
  httpResponseSizeBytes
} from '../metrics/http-metrics';

export function metricsMiddleware(req: Request, res: Response, next: NextFunction) {
  const start = Date.now();
  
  // Capture request size
  const requestSize = parseInt(req.headers['content-length'] || '0', 10);
  
  // Track response
  res.on('finish', () => {
    const duration = (Date.now() - start) / 1000; // Convert to seconds
    const route = req.route?.path || req.path || 'unknown';
    const method = req.method;
    const statusCode = res.statusCode.toString();
    
    // Record metrics
    httpRequestsTotal.inc({
      method,
      route,
      status_code: statusCode
    });
    
    httpRequestDuration.observe(
      {
        method,
        route,
        status_code: statusCode
      },
      duration
    );
    
    // Request size
    if (requestSize > 0) {
      httpRequestSizeBytes.observe({ method, route }, requestSize);
    }
    
    // Response size
    const responseSize = parseInt(res.getHeader('content-length') as string || '0', 10);
    if (responseSize > 0) {
      httpResponseSizeBytes.observe(
        { method, route, status_code: statusCode },
        responseSize
      );
    }
  });
  
  next();
}

// src/server.ts
import express from 'express';
import { metricsMiddleware } from './middleware/metrics.middleware';
import { register } from './metrics/http-metrics';

const app = express();

// Apply metrics middleware before routes
app.use(metricsMiddleware);

// Your routes
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

app.post('/api/users', (req, res) => {
  res.status(201).json({ id: 1 });
});

// Metrics endpoint
app.get('/metrics', async (req, res) => {
  res.setHeader('Content-Type', register.contentType);
  res.send(await register.metrics());
});

app.listen(3000);

Database Metrics

Tracking database performance is critical. Here's how I instrument database queries.

PostgreSQL with pg Library

// src/metrics/database-metrics.ts
import { Histogram, Gauge, Counter } from 'prom-client';
import { register } from './http-metrics';

export const dbQueryDuration = new Histogram({
  name: 'db_query_duration_seconds',
  help: 'Duration of database queries in seconds',
  labelNames: ['operation', 'table', 'status'] as const,
  buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5],
  registers: [register]
});

export const dbConnectionsActive = new Gauge({
  name: 'db_connections_active',
  help: 'Number of active database connections',
  registers: [register]
});

export const dbConnectionsIdle = new Gauge({
  name: 'db_connections_idle',
  help: 'Number of idle database connections',
  registers: [register]
});

export const dbQueryErrorsTotal = new Counter({
  name: 'db_query_errors_total',
  help: 'Total number of database query errors',
  labelNames: ['operation', 'table'] as const,
  registers: [register]
});

// src/database/pool.ts
import { Pool } from 'pg';
import {
  dbConnectionsActive,
  dbConnectionsIdle,
  dbQueryDuration,
  dbQueryErrorsTotal
} from '../metrics/database-metrics';

const pool = new Pool({
  host: 'localhost',
  database: 'mydb',
  max: 20
});

// Update connection pool metrics every 5 seconds
setInterval(() => {
  dbConnectionsActive.set(pool.totalCount - pool.idleCount);
  dbConnectionsIdle.set(pool.idleCount);
}, 5000);

// Wrapper for instrumented queries
export async function query<T>(
  sql: string,
  params: any[] = [],
  options: { operation?: string; table?: string } = {}
): Promise<T> {
  const start = Date.now();
  const operation = options.operation || 'query';
  const table = options.table || 'unknown';
  
  try {
    const result = await pool.query(sql, params);
    
    const duration = (Date.now() - start) / 1000;
    dbQueryDuration.observe(
      { operation, table, status: 'success' },
      duration
    );
    
    return result.rows as T;
  } catch (error) {
    const duration = (Date.now() - start) / 1000;
    dbQueryDuration.observe(
      { operation, table, status: 'error' },
      duration
    );
    dbQueryErrorsTotal.inc({ operation, table });
    
    throw error;
  }
}

// Usage example
import { query } from './database/pool';

async function getUsers() {
  return query(
    'SELECT * FROM users WHERE active = $1',
    [true],
    { operation: 'select', table: 'users' }
  );
}

async function createUser(name: string, email: string) {
  return query(
    'INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *',
    [name, email],
    { operation: 'insert', table: 'users' }
  );
}

Prisma ORM

If you use Prisma:

// src/database/prisma-client.ts
import { PrismaClient } from '@prisma/client';
import { dbQueryDuration, dbQueryErrorsTotal } from '../metrics/database-metrics';

const prisma = new PrismaClient();

// Middleware to track query metrics
prisma.$use(async (params, next) => {
  const start = Date.now();
  const { model, action } = params;
  
  try {
    const result = await next(params);
    
    const duration = (Date.now() - start) / 1000;
    dbQueryDuration.observe(
      {
        operation: action,
        table: model || 'unknown',
        status: 'success'
      },
      duration
    );
    
    return result;
  } catch (error) {
    const duration = (Date.now() - start) / 1000;
    dbQueryDuration.observe(
      {
        operation: action,
        table: model || 'unknown',
        status: 'error'
      },
      duration
    );
    dbQueryErrorsTotal.inc({
      operation: action,
      table: model || 'unknown'
    });
    
    throw error;
  }
});

export default prisma;

Business Metrics

Beyond technical metrics, track business metrics that matter.

// src/metrics/business-metrics.ts
import { Counter, Gauge } from 'prom-client';
import { register } from './http-metrics';

// User registrations
export const userRegistrationsTotal = new Counter({
  name: 'user_registrations_total',
  help: 'Total number of user registrations',
  labelNames: ['source'] as const,
  registers: [register]
});

// Active users
export const activeUsers = new Gauge({
  name: 'users_active',
  help: 'Number of currently active users',
  registers: [register]
});

// Purchases
export const purchasesTotal = new Counter({
  name: 'purchases_total',
  help: 'Total number of purchases',
  labelNames: ['product_type'] as const,
  registers: [register]
});

// Revenue
export const revenueTotal = new Counter({
  name: 'revenue_total_cents',
  help: 'Total revenue in cents',
  labelNames: ['currency', 'product_type'] as const,
  registers: [register]
});

// Usage example
import {
  userRegistrationsTotal,
  purchasesTotal,
  revenueTotal
} from './metrics/business-metrics';

async function registerUser(email: string, source: string) {
  // ... registration logic
  
  userRegistrationsTotal.inc({ source });
}

async function processPurchase(amount: number, productType: string) {
  // ... purchase logic
  
  purchasesTotal.inc({ product_type: productType });
  revenueTotal.inc(
    { currency: 'USD', product_type: productType },
    amount * 100 // Convert to cents
  );
}

Custom Metrics for Specific Scenarios

Queue Processing

// src/metrics/queue-metrics.ts
import { Gauge, Counter, Histogram } from 'prom-client';
import { register } from './http-metrics';

export const queueSize = new Gauge({
  name: 'queue_size',
  help: 'Number of items in the queue',
  labelNames: ['queue_name'] as const,
  registers: [register]
});

export const queueProcessingDuration = new Histogram({
  name: 'queue_processing_duration_seconds',
  help: 'Duration of queue item processing',
  labelNames: ['queue_name', 'status'] as const,
  buckets: [0.1, 0.5, 1, 2, 5, 10, 30, 60],
  registers: [register]
});

export const queueItemsProcessedTotal = new Counter({
  name: 'queue_items_processed_total',
  help: 'Total number of queue items processed',
  labelNames: ['queue_name', 'status'] as const,
  registers: [register]
});

// Usage
import Bull from 'bull';
import { queueSize, queueProcessingDuration, queueItemsProcessedTotal } from './metrics/queue-metrics';

const emailQueue = new Bull('email', 'redis://localhost:6379');

// Update queue size periodically
setInterval(async () => {
  const [waiting, active, delayed] = await Promise.all([
    emailQueue.getWaitingCount(),
    emailQueue.getActiveCount(),
    emailQueue.getDelayedCount()
  ]);
  
  queueSize.set({ queue_name: 'email' }, waiting + active + delayed);
}, 5000);

// Process with metrics
emailQueue.process(async (job) => {
  const end = queueProcessingDuration.startTimer({
    queue_name: 'email',
    status: 'success'
  });
  
  try {
    await sendEmail(job.data);
    queueItemsProcessedTotal.inc({
      queue_name: 'email',
      status: 'success'
    });
    end();
  } catch (error) {
    end({ status: 'error' });
    queueItemsProcessedTotal.inc({
      queue_name: 'email',
      status: 'error'
    });
    throw error;
  }
});

Cache Hit/Miss Rates

// src/metrics/cache-metrics.ts
import { Counter } from 'prom-client';
import { register } from './http-metrics';

export const cacheOperations = new Counter({
  name: 'cache_operations_total',
  help: 'Total number of cache operations',
  labelNames: ['operation', 'cache_name', 'status'] as const,
  registers: [register]
});

// src/services/cache.service.ts
import Redis from 'ioredis';
import { cacheOperations } from '../metrics/cache-metrics';

const redis = new Redis();

export async function getCached<T>(key: string, cacheName = 'default'): Promise<T | null> {
  try {
    const value = await redis.get(key);
    
    if (value) {
      cacheOperations.inc({
        operation: 'get',
        cache_name: cacheName,
        status: 'hit'
      });
      return JSON.parse(value) as T;
    } else {
      cacheOperations.inc({
        operation: 'get',
        cache_name: cacheName,
        status: 'miss'
      });
      return null;
    }
  } catch (error) {
    cacheOperations.inc({
      operation: 'get',
      cache_name: cacheName,
      status: 'error'
    });
    throw error;
  }
}

export async function setCached(key: string, value: any, ttl = 3600, cacheName = 'default'): Promise<void> {
  try {
    await redis.setex(key, ttl, JSON.stringify(value));
    cacheOperations.inc({
      operation: 'set',
      cache_name: cacheName,
      status: 'success'
    });
  } catch (error) {
    cacheOperations.inc({
      operation: 'set',
      cache_name: cacheName,
      status: 'error'
    });
    throw error;
  }
}

Production-Ready Metrics Setup

Here's my complete, production-ready metrics setup:

// src/metrics/index.ts
import {
  Registry,
  Counter,
  Histogram,
  Gauge,
  collectDefaultMetrics
} from 'prom-client';

// Create registry
export const register = new Registry();

// Collect default metrics
collectDefaultMetrics({
  register,
  prefix: 'nodejs_',
  gcDurationBuckets: [0.001, 0.01, 0.1, 1, 2, 5]
});

// HTTP metrics
export const httpMetrics = {
  requestsTotal: new Counter({
    name: 'http_requests_total',
    help: 'Total HTTP requests',
    labelNames: ['method', 'route', 'status_code'] as const,
    registers: [register]
  }),
  
  requestDuration: new Histogram({
    name: 'http_request_duration_seconds',
    help: 'HTTP request duration',
    labelNames: ['method', 'route', 'status_code'] as const,
    buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
    registers: [register]
  })
};

// Database metrics
export const dbMetrics = {
  queryDuration: new Histogram({
    name: 'db_query_duration_seconds',
    help: 'Database query duration',
    labelNames: ['operation', 'table', 'status'] as const,
    buckets: [0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1],
    registers: [register]
  }),
  
  connectionsActive: new Gauge({
    name: 'db_connections_active',
    help: 'Active database connections',
    registers: [register]
  }),
  
  errorsTotal: new Counter({
    name: 'db_errors_total',
    help: 'Total database errors',
    labelNames: ['operation', 'table'] as const,
    registers: [register]
  })
};

// Business metrics
export const businessMetrics = {
  signupsTotal: new Counter({
    name: 'user_signups_total',
    help: 'Total user signups',
    labelNames: ['source'] as const,
    registers: [register]
  }),
  
  activeUsers: new Gauge({
    name: 'users_active',
    help: 'Currently active users',
    registers: [register]
  })
};

export default register;

Testing Your Metrics

Before deploying, test that your metrics work:

// src/__tests__/metrics.test.ts
import request from 'supertest';
import { app } from '../server';
import { register, httpMetrics } from '../metrics';

describe('Metrics', () => {
  beforeEach(() => {
    // Reset metrics between tests
    register.resetMetrics();
  });
  
  it('should expose /metrics endpoint', async () => {
    const response = await request(app).get('/metrics');
    
    expect(response.status).toBe(200);
    expect(response.text).toContain('http_requests_total');
    expect(response.headers['content-type']).toContain('text/plain');
  });
  
  it('should track HTTP requests', async () => {
    await request(app).get('/api/users');
    
    const metrics = await register.metrics();
    expect(metrics).toContain('http_requests_total');
    expect(metrics).toContain('method="GET"');
    expect(metrics).toContain('route="/api/users"');
  });
});

Performance Considerations

Q: Does instrumentation slow down my app?

In my experience, the performance impact is negligible:

• Incrementing a counter: ~0.001ms

• Observing a histogram: ~0.01ms

• Total overhead: typically <1% of request time

Q: How many metrics is too many?

Keep total time series under control:

• 1,000-10,000 series: perfectly fine

• 10,000-100,000 series: manageable

• 100,000+ series: need optimization

Key Takeaways

1. Start simple - /metrics endpoint with default metrics

2. Instrument HTTP layer - Request count, duration, status codes

3. Track database queries - Query duration and connection pool

4. Add business metrics - Signups, purchases, etc.

5. Use TypeScript - Type safety prevents label typos

6. Test your metrics - Ensure they're exposed correctly

7. Keep cardinality low - Avoid high-cardinality labels

In the next article, we'll learn PromQL to query all these metrics effectively.

---

Previous: Prometheus Architecture Next: PromQL Basics