Prometheus метрики в TypeScript: полное руководство по client.js

Prometheus метрики в TypeScript: практическое руководство

Prometheus — это мощная система мониторинга и оповещения с открытым исходным кодом. Для интеграции с TypeScript-приложениями используется библиотека prom-client (Prometheus Client). Она позволяет собирать, агрегировать и экспортировать метрики в формате, понятном серверу Prometheus. В этой статье мы подробно разберём, как работать с Prometheus метриками в TypeScript, включая типы метрик, примеры кода и лучшие практики.

Установка и настройка

Для начала установите пакет через npm:

npm install prom-client

Для TypeScript потребуется также установить типы:

npm install @types/prom-client --save-dev

После установки создайте файл metrics.ts для инициализации клиента:

import client from 'prom-client';

// Включаем сбор дефолтных метрик (GC, память, процессор)
const collectDefaultMetrics = client.collectDefaultMetrics;
collectDefaultMetrics({ timeout: 5000 });

// Создаём регистр для хранения метрик
const register = client.register;

export { client, register };

Основные типы метрик Prometheus

Prometheus поддерживает четыре основных типа метрик. Рассмотрим каждый с примерами на TypeScript.

1. Counter (Счётчик)

Используется для подсчёта событий, которые только увеличиваются (запросы, ошибки).

import { Counter } from 'prom-client';

const httpRequestsTotal = new Counter({
  name: 'http_requests_total',
  help: 'Total number of HTTP requests',
  labelNames: ['method', 'path', 'status_code'],
});

// Инкрементируем счётчик при запросе
httpRequestsTotal.inc({ method: 'GET', path: '/api', status_code: 200 });
httpRequestsTotal.inc({ method: 'POST', path: '/users', status_code: 201 }, 2); // +2

2. Gauge (Датчик)

Может увеличиваться и уменьшаться. Используется для текущих значений (память, очередь).

import { Gauge } from 'prom-client';

const memoryUsageGauge = new Gauge({
  name: 'memory_usage_bytes',
  help: 'Current memory usage in bytes',
});

// Устанавливаем значение
memoryUsageGauge.set(process.memoryUsage().heapUsed);

// Изменяем на дельту
memoryUsageGauge.inc(1024); // +1KB
memoryUsageGauge.dec(512);  // -512B

3. Histogram (Гистограмма)

Измеряет распределение значений (например, время ответа).

import { Histogram } from 'prom-client';

const httpRequestDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of HTTP requests in seconds',
  labelNames: ['method', 'route'],
  buckets: [0.1, 0.3, 0.5, 1, 2, 5], // границы сегментов
});

// Наблюдаем значение
const start = Date.now();
// ... обработка запроса ...
httpRequestDuration.observe(
  { method: 'GET', route: '/api' },
  (Date.now() - start) / 1000
);

4. Summary (Сводка)

Похожа на гистограмму, но вычисляет квантили на стороне клиента.

import { Summary } from 'prom-client';

const responseTimeSummary = new Summary({
  name: 'response_time_summary_seconds',
  help: 'Response time summary in seconds',
  percentiles: [0.5, 0.9, 0.99], // квантили
});

responseTimeSummary.observe(0.42);
responseTimeSummary.observe(0.35);

Экспорт метрик для Prometheus

Создайте эндпоинт /metrics, который будет отдавать метрики в текстовом формате:

import express from 'express';
import { register } from './metrics';

const app = express();

app.get('/metrics', async (req, res) => {
  try {
    res.set('Content-Type', register.contentType);
    res.end(await register.metrics());
  } catch (err) {
    res.status(500).end(err);
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

Теперь при GET-запросе к /metrics вы получите:

# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",path="/api",status_code="200"} 1
# HELP memory_usage_bytes Current memory usage in bytes
# TYPE memory_usage_bytes gauge
memory_usage_bytes 52428800

Интеграция с Express и middleware

Создайте middleware для автоматического сбора метрик по каждому запросу:

import { Counter, Histogram } from 'prom-client';

const requestCounter = new Counter({
  name: 'app_requests_total',
  help: 'Total app requests',
  labelNames: ['method', 'path', 'status'],
});

const requestDuration = new Histogram({