Métricas Prometheus em TypeScript | Guia

Métricas Prometheus em TypeScript: guia prático

Prometheus é um poderoso sistema de monitoramento e alerta de código aberto. Para integração com aplicações TypeScript, utiliza-se a biblioteca prom-client (Prometheus Client). Ela permite coletar, agregar e exportar métricas em um formato compreensível para o servidor Prometheus. Neste artigo, abordaremos detalhadamente como trabalhar com métricas Prometheus em TypeScript, incluindo tipos de métricas, exemplos de código e melhores práticas.

Instalação e configuração

Para começar, instale o pacote via npm:

npm install prom-client

Para TypeScript, também será necessário instalar os tipos:

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

Após a instalação, crie o arquivo metrics.ts para inicializar o cliente:

import client from 'prom-client';

// Ativamos a coleta de métricas padrão (GC, memória, CPU)const collectDefaultMetrics = client.collectDefaultMetrics;collectDefaultMetrics({ timeout: 5000 });

// Criamos um registro para armazenar as métricasconst register = client.register;

export { client, register };

Tipos principais de métricas Prometheus

Prometheus suporta quatro tipos principais de métricas. Vamos analisar cada um com exemplos em TypeScript.

1. Counter (Contador)

Usado para contar eventos que apenas aumentam (requisições, erros).

import { Counter } from 'prom-client';

const httpRequestsTotal = new Counter({  name: 'http_requests_total',  help: 'Número total de requisições HTTP',  labelNames: ['method', 'path', 'status_code'],});

// Incrementamos o contador a cada requisiçãohttpRequestsTotal.inc({ method: 'GET', path: '/api', status_code: 200 });httpRequestsTotal.inc({ method: 'POST', path: '/users', status_code: 201 }, 2); // +2

2. Gauge (Medidor)

Pode aumentar e diminuir. Usado para valores atuais (memória, fila).

import { Gauge } from 'prom-client';

const memoryUsageGauge = new Gauge({  name: 'memory_usage_bytes',  help: 'Uso atual de memória em bytes',});

// Definimos o valormemoryUsageGauge.set(process.memoryUsage().heapUsed);

// Alteramos por deltamemoryUsageGauge.inc(1024); // +1KBmemoryUsageGauge.dec(512);  // -512B

3. Histogram (Histograma)

Mede a distribuição de valores (ex: tempo de resposta).

import { Histogram } from 'prom-client';

const httpRequestDuration = new Histogram({  name: 'http_request_duration_seconds',  help: 'Duração das requisições HTTP em segundos',  labelNames: ['method', 'route'],  buckets: [0.1, 0.3, 0.5, 1, 2, 5], // limites dos segmentos});

// Observamos o valorconst start = Date.now();// ... processamento da requisição ...httpRequestDuration.observe(  { method: 'GET', route: '/api' },  (Date.now() - start) / 1000);

4. Summary (Resumo)

Semelhante ao histograma, mas calcula quantis no lado do cliente.

import { Summary } from 'prom-client';

const responseTimeSummary = new Summary({  name: 'response_time_summary_seconds',  help: 'Resumo do tempo de resposta em segundos',  percentiles: [0.5, 0.9, 0.99], // quantis});

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

Exportação de métricas para Prometheus

Crie um endpoint /metrics que fornecerá as métricas em formato texto:

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('Servidor rodando na porta 3000'));

Agora, ao fazer uma requisição GET