TypeScript API with Complete Observability

Modern REST API built with TypeScript, Express, and OpenTelemetry. Demonstrates observability best practices including metrics collection, structured logging, and distributed tracing.

Technology Stack

• TypeScript - Primary development language
• Express.js - Web application framework
• OpenTelemetry - Observability instrumentation
• Prometheus - Metrics collection and storage
• Winston - Structured logging library
• Swagger/OpenAPI - API documentation
• Jest - Testing framework
• Docker - Containerization platform

Features

• Complete REST API with CRUD operations
• Automatic Prometheus metrics collection
• Distributed tracing with OpenTelemetry
• Structured JSON logging
• Advanced health checks
• Interactive Swagger documentation
• Request validation middleware
• Rate limiting protection
• CORS configuration
• Graceful shutdown handling

Prerequisites

• Node.js 18+
• Docker & Docker Compose
• TypeScript compiler

Quick Start

1. Instalar dependências

npm install

2. Executar em modo desenvolvimento

npm run dev

3. Executar com Docker

docker-compose up -d

4. Executar stack completa (API + Observabilidade)

make start-full-stack

API Endpoints

Core Endpoints

• GET / - Root endpoint
• GET /health - Detailed health check
• GET /metrics - Prometheus metrics
• GET /docs - Swagger documentation

Users API

• GET /api/users - List all users
• GET /api/users/:id - Get specific user
• POST /api/users - Create new user
• PUT /api/users/:id - Update existing user
• DELETE /api/users/:id - Delete user

Debug Endpoints

• GET /api/slow - Simulate slow endpoint
• GET /api/error - Simulate 500 error
• GET /api/load/:seconds - Simulate load for X seconds

Observability Features

Available Metrics

• HTTP request count and duration
• Active connection monitoring
• Memory usage tracking
• CPU utilization metrics
• Custom business metrics

Distributed Tracing

• Complete HTTP request traces
• Database query tracing (simulated)
• External API call tracking
• Custom spans for business logic

Structured Logging

• JSON-formatted log output
• Request and response logging
• Error tracking and reporting
• Performance monitoring

Testing

# Run all tests
npm test

# Run with coverage report
npm run test:coverage

# Run in watch mode
npm run test:watch

Build and Deployment

# Build for production
npm run build

# Run production build
npm start

# Build Docker image
docker build -t typescript-api-observability .

Configuration

Available environment variables:

PORT=3000
NODE_ENV=development
LOG_LEVEL=info
ENABLE_TRACING=true
PROMETHEUS_ENABLED=true
API_RATE_LIMIT=100

Monitoring Access

API endpoints:

• API Documentation: http://localhost:3000/docs
• Metrics Endpoint: http://localhost:3000/metrics
• Health Check: http://localhost:3000/health

Full stack access (when running complete setup):

• Grafana: http://localhost:3000 (admin/admin)
• Prometheus: http://localhost:9090
• Jaeger: http://localhost:16686

Architecture

src/
├── controllers/     # Controladores da API
├── middleware/      # Middlewares customizados
├── models/          # Modelos de dados
├── routes/          # Definição das rotas
├── services/        # Lógica de negócio
├── telemetry/       # Configuração de observabilidade
├── types/           # Definições de tipos TypeScript
└── utils/           # Utilitários

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE file for details.