npm package: @lggutierrez/monitoring
Description: Prometheus monitoring library for Node.js and Express applications
Author: lggutierrez
Latest version: 1.0.4

# @lggutierrez/monitoring

Librería ligera de monitoreo con Prometheus para aplicaciones Node.js y Express. Configuración simple, uso inmediato.

## Características

✨ **Configuración en 2 líneas** - Importa y usa, sin instancias manuales  
📊 **Métricas completas** - HTTP, sistema, PM2  
🎯 **Zero-config** - Funciona out-of-the-box  
🔧 **Altamente configurable** - Personaliza lo que necesites  
📦 **Ligero** - ~13KB comprimido  
🚀 **TypeScript First** - Tipado completo  

## Instalación

```bash
npm install @lggutierrez/monitoring
# o
pnpm add @lggutierrez/monitoring
```

## Uso Rápido

```typescript
import express from 'express';
import { createMonitoringMiddleware, createMonitoringRouter } from '@lggutierrez/monitoring';

const app = express();

// ¡Eso es todo! Solo 2 líneas
app.use(createMonitoringMiddleware());
app.use(createMonitoringRouter());

app.listen(3000);
// ✅ Métricas en: http://localhost:3000/monitoring/metrics
// ✅ Info en: http://localhost:3000/monitoring/info
```

## Uso Avanzado

### Con Configuración Personalizada

```typescript
import express from 'express';
import { createMonitoringMiddleware, createMonitoringRouter } from '@lggutierrez/monitoring';

const app = express();

// Middleware con configuración
app.use(createMonitoringMiddleware({
  ignoreRoutes: ['/health', '/admin/*'],
  collectDefaultMetrics: true,
  histogramBuckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
}));

// Router con configuración
app.use(createMonitoringRouter({
  basePath: '/metrics',
  defaultFormat: 'json', // o 'text'
}));

app.listen(3000);
```

## Endpoints Expuestos

### `GET /monitoring/metrics`

Métricas de Prometheus. Soporta dos formatos:

**Formato texto (default):**
```bash
curl http://localhost:3000/monitoring/metrics
# o
curl http://localhost:3000/monitoring/metrics?format=text
```

**Formato JSON:**
```bash
curl http://localhost:3000/monitoring/metrics?format=json
```

### `GET /monitoring/info`

Información de la aplicación y host en JSON:
```bash
curl http://localhost:3000/monitoring/info
```

```json
{
  "up": true,
  "application": {
    "name": "my-app",
    "version": "1.0.0",
    "description": "My application"
  },
  "host": {
    "hostname": "server-01",
    "platform": "linux",
    "arch": "x64",
    "ipAddresses": ["192.168.1.100"]
  },
  "pm2": {
    "enabled": true,
    "processId": "0",
    "instanceId": "0"
  },
  "timestamp": "2025-12-04T20:00:00.000Z"
}
```

## API

### `createMonitoringMiddleware(options?)`

Crea el middleware de Express que captura métricas HTTP.

**Parámetros:**
- `options?` - Configuración opcional del servicio de monitoreo

**Opciones disponibles:**
```typescript
interface MonitoringMiddlewareOptions {
  /** Rutas a ignorar. Soporta wildcards (*) */
  ignoreRoutes?: string[];  // Default: ['/monitoring/metrics', '/monitoring/info']
  
  /** Buckets del histograma en segundos */
  histogramBuckets?: number[];  // Default: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
  
  /** Habilitar métricas del sistema (CPU, memoria, GC) */
  collectDefaultMetrics?: boolean;  // Default: true
  
  /** Ruta al package.json */
  packageJsonPath?: string;  // Default: '../../package.json'
}
```

**Ejemplo:**
```typescript
app.use(createMonitoringMiddleware({
  ignoreRoutes: ['/health', '/admin/*'],
  histogramBuckets: [0.1, 0.5, 1, 2, 5],
}));
```

---

### `createMonitoringRouter(options?)`

Crea un router de Express con endpoints de métricas.

**Parámetros:**
- `options?` - Configuración del router y servicio

**Opciones disponibles:**
```typescript
interface MonitoringRouterOptions {
  /** Ruta base para los endpoints */
  basePath?: string;  // Default: '/monitoring'
  
  /** Formato por defecto de las métricas */
  defaultFormat?: 'text' | 'json';  // Default: 'text'
  
  // + todas las opciones de MonitoringMiddlewareOptions
}
```

**Ejemplos:**
```typescript
// Default: /monitoring/metrics y /monitoring/info
app.use(createMonitoringRouter());

// Custom path: /health/metrics y /health/info
app.use(createMonitoringRouter({ basePath: '/health' }));

// Formato JSON por defecto
app.use(createMonitoringRouter({ defaultFormat: 'json' }));
```

## Métricas disponibles

### HTTP Metrics

- `http_request_duration_seconds` - Histograma de duración de requests
- `http_requests_total` - Contador total de requests HTTP
- `http_requests_active` - Gauge de requests activos
- `http_request_errors_total` - Contador de errores HTTP
- `http_requests_time` - Gauge de requests por hora

### Labels

Todas las métricas incluyen labels como:
- `method` - Método HTTP (GET, POST, etc.)
- `route` - Ruta de la petición
- `status_code` - Código de estado HTTP
- `status_class` - Clase de estado (2xx, 3xx, 4xx, 5xx)
- `error_type` - Tipo de error (cuando aplica)

### Métricas por defecto

Cuando `collectDefaultMetrics: true`:
- CPU usage
- Memory usage
- Event loop lag
- Garbage collection
- Process info

## Endpoints recomendados

### `/metrics`
Endpoint en formato Prometheus para scraping
```typescript
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', 'text/plain');
  res.send(await monitoringService.getMetricsAsText());
});
```

### `/app-info`
Información de la aplicación y host
```typescript
app.get('/app-info', (req, res) => {
  res.json(monitoringService.getAppInfo());
});
```

## Configuración de Prometheus

Agregar en `prometheus.yml`:

```yaml
scrape_configs:
  - job_name: 'my-app'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:3000']
    metrics_path: '/metrics'
```

## Soporte PM2

La librería detecta automáticamente si está corriendo bajo PM2 y expone información adicional:
- Process ID
- Instance ID
- Process name

## TypeScript

La librería está completamente tipada y exporta todos los tipos necesarios:

```typescript
import type {
  MonitoringConfig,
  PrometheusMetrics,
  AppInfo,
  MetricLabels,
} from '@your-org/prometheus-monitoring';
```

## Seguridad

### Versiones exactas en producción

Usa versiones exactas en tu `package.json`:
```json
{
  "dependencies": {
    "@your-org/prometheus-monitoring": "1.0.0"
  }
}
```

### Proteger endpoints

Recuerda proteger tus endpoints de métricas en producción:

```typescript
app.get('/metrics', authMiddleware, async (req, res) => {
  res.set('Content-Type', 'text/plain');
  res.send(await monitoringService.getMetricsAsText());
});
```

## License

MIT