Custom metrics

Фреймворк Fresh предоставляет встроенные возможности для работы с метриками и мониторингом, но часто возникает необходимость создания кастомных метрик, чтобы отслеживать специфические показатели приложения. Custom metrics позволяют получать более детальную информацию о работе системы, производительности и поведении пользователей.

Основы Custom Metrics

Метрики в Fresh строятся на концепции наблюдаемых данных, которые можно собирать и агрегировать. Каждая метрика состоит из имени, типа и значений, которые обновляются при определённых событиях приложения.

Типы метрик:

  • Counter — счётчик, увеличивающийся на фиксированное значение при каждом событии. Используется для подсчёта числа посещений, ошибок или запросов к API.
  • Gauge — метрика, которая может как увеличиваться, так и уменьшаться. Применяется для измерения текущей загрузки, числа активных сессий или состояния очередей.
  • Histogram — распределение значений. Используется для измерения времени отклика, размера payload или других величин с разбросом значений.
  • Summary — похожа на гистограмму, но агрегирует данные в квантили. Позволяет оценивать 95-й и 99-й процентиль времени отклика.

Создание кастомной метрики

Для создания кастомной метрики необходимо использовать модуль fresh/metrics. Пример определения счётчика:

import { Counter } from "fresh/metrics";

const requestCounter = new Counter({
  name: "http_requests_total",
  description: "Общее количество HTTP-запросов",
  labels: ["method", "status"]
});

function trackRequest(method, status) {
  requestCounter.inc({ method, status });
}

Ключевые моменты:

  • name — уникальное имя метрики. Рекомендуется использовать snake_case.
  • description — краткое описание метрики для документации.
  • labels — набор тегов для фильтрации и агрегирования данных.

Метрика Counter обновляется вызовом метода inc(), который принимает объект с метками.

Gauge и динамическое отслеживание

Gauge полезна для отслеживания состояния, которое меняется во времени:

import { Gauge } from "fresh/metrics";

const activeUsers = new Gauge({
  name: "active_users",
  description: "Текущее количество активных пользователей"
});

function userLoggedIn() {
  activeUsers.inc();
}

function userLoggedOut() {
  activeUsers.dec();
}

Методы inc() и dec() позволяют изменять текущее значение метрики. Можно также использовать set(value) для явного задания значения.

Histogram и Summary

Для анализа времени выполнения операций используют Histogram или Summary:

import { Histogram } from "fresh/metrics";

const responseTime = new Histogram({
  name: "response_time_seconds",
  description: "Время ответа сервера в секундах",
  buckets: [0.1, 0.3, 0.5, 1, 2, 5]
});

function trackResponseTime(duration) {
  responseTime.observe(duration);
}
  • buckets задаёт интервалы для распределения значений.
  • Метод observe(value) добавляет новое значение в распределение.

Summary позволяет получать процентильные показатели:

import { Summary } from "fresh/metrics";

const apiLatency = new Summary({
  name: "api_latency_seconds",
  description: "Латентность API в секундах",
  percentiles: [0.5, 0.95, 0.99]
});

function recordLatency(ms) {
  apiLatency.observe(ms / 1000);
}

Интеграция с обработчиками Fresh

Custom metrics можно интегрировать в middleware или в хендлеры маршрутов. Пример middleware, отслеживающего все HTTP-запросы:

export async function handler(req, ctx) {
  const start = performance.now();
  const resp = await ctx.next();
  const duration = (performance.now() - start) / 1000;

  requestCounter.inc({ method: req.method, status: resp.status });
  responseTime.observe(duration);

  return resp;
}

Такой подход позволяет собирать полную статистику по каждому запросу, включая метод, статус и время обработки.

Метки и фильтрация

Использование labels позволяет группировать метрики по различным измерениям. Например, можно отслеживать ошибки по типу или региону:

errorCounter.inc({ type: "database", region: "eu" });

С помощью агрегаторов и панелей мониторинга эти метки используются для построения дашбордов и отчетов.

Практические советы

  • Метрики должны быть легковесными, чтобы не перегружать приложение.
  • Для высокочастотных событий использовать сэмплинг или Histogram вместо Counter.
  • Всегда документировать описание метрики и единицы измерения.
  • Разделять метрики на функциональные блоки для удобства поддержки и визуализации.

Custom metrics в Fresh предоставляют мощный инструмент для мониторинга и анализа приложения, позволяя создавать точные и детализированные отчёты о работе системы, оптимизировать производительность и выявлять узкие места.

Оглавление