Всем привет! Мы давно и усердно работаем по направлению наблюдаемости и регулярно находим интересные статьи. Например, в этой вы узнаете подробности об устройства популярной системы хранения временных рядов — VictoriaMetrics. Перевод мы сделали специально для телеграм-канала Мониторим ИТ. Подписывайтесь! Там еще больше полезных постов о мониторинге.

Раскрываем возможности VictoriaMetrics: подробное изучение архитектуры, ключевых файлов Go и структуры проекта

VictoriaMetrics — это высокопроизводительная и масштабируемая база данных временных рядов и решение для мониторинга. VictoriaMetrics разработана для сбора, хранения и запроса больших объёмов данных временных рядов, что делает её идеальной для мониторинга инфраструктуры, приложений и IoT-устройств. Она поддерживает модели приёма данных как pull (сбор данных в стиле Prometheus), так и push (различные протоколы).

Перед установкой и использованием предлагаем вам углубиться в структуру проекта и дадим пояснения основных файлов системы, написанной на Go.

Базы данных временных рядов переживают всплеск популярности.

Базы данных временных рядов стремительно развиваются в связи с растущей потребностью в мониторинге инфраструктуры, приложений, устройств Интернета вещей и облачных сред. Такие проекты, как VictoriaMetrics, InfluxDB, Prometheus, OpenTSDB, Druid, Graphite, QuestDB и TimescaleDB, упрощают внедрение и делают его более эффективным.

Структура проекта (упрощенный обзор)

/app
  └─ Compilable binaries (main executables)
/lib
  └─ Golang reusable libraries
/docs/victoriametrics
  └─ Project documentation
/apptest/tests
  └─ Integration tests

VictoriaMetrics содержит гораздо больше директорий, чем просто app, lib, victoriametrics и tests. Указанная структура даёт упрощённое представление и наглядность структуры директорий проекта.

Бэкэнд: Golang (минимум сторонних библиотек)
Фронтенд: React

VictoriaMetrics — это полнофункциональная платформа мониторинга, а не просто база данных. Она включает в себя коллекторы, оповещения, аутентификацию, инструменты резервного копирования и многое другое — каждое со своей кодовой базой и ресурсами.

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

📁 app = основные исполняемые файлы

Содержит компилированные бинарные файлы для всех компонентов VictoriaMetrics.

• Содержит точки входа для создания исполняемых файлов, таких как vmsingle, vmagent, vmalert, vmauth и т. д.

• Каждый подкаталог обычно соответствует определенному компоненту или инструменту.

📁 lib = общие библиотеки Go

Содержит переиспользуемые библиотеки Golang.

• Предоставляет общий код и утилиты, используемые несколькими компонентами.

• Способствует повторному использованию кода и поддерживает DRY (не повторяйся) в кодовой базе.

• Сторонние библиотеки используются редко и представлены здесь.

📁 victoriametrics = документация

Содержит документацию по проекту.

• Предлагает руководства, пояснения по архитектуре, справочники API, логи изменений и учебные гайды.

• Необходим для устранения неполадок и изучения функций и конфигурации.

📁 tests = интеграционные тесты

Содержит интеграционные тесты. VictoriaMetrics использует встроенный фреймворк Go для своих тестов.

• Гарантирует, что различные компоненты функционируют должным образом.

• Проверяет реальные сценарии и поведение на системном уровне.

• Помогает поддерживать надежность и выявлять регрессии до их возникновения.

Бэкенд реализован на Go без интеграций на уровне ядра, таких как eBPF. Проект опирается на эффективный код Go и умеренное использование сторонних библиотек для обеспечения производительности и масштабируемости. Метрики и трассировка обрабатываются с помощью собственных механизмов и интеграций VictoriaMetrics, а не через OpenTelemetry, хотя её можно интегрировать (как мы увидим позже).

Вот типичная структура каталога app в VictoriaMetrics:

/app
  /vmauth        # Authentication proxy component
  /vmagent       # Metrics collection and forwarding agent
  /vmalert       # Alerting and rule evaluation component
  /vmbackup      # Backup utility for metrics data
  /vmrestore     # Restore utility for metrics data
  /vmctl         # Data migration and import/export tool
  /vmsingle      # Single-node time series database
  /vmcluster     # Clustered time series database
  /vmui          # Web UI frontend (React)
  /prometheus-benchmark # Benchmarking tool for Prometheus-compatible endpoints

Вы уже точно заметили, что префикс vm VictoriaMetrics означает «VictoriaMetrics». Он используется для чёткой идентификации и создания пространств имён всех основных компонентов и инструментов, связанных с проектом, таких как vmagent, vmalert, vmauth, vmbackup и других. Такое соглашение об именовании помогает отличать исполняемые файлы и утилиты VictoriaMetrics от исполняемых файлов и утилит другого программного обеспечения, поддерживая единообразие кодовой базы и документации.

Типичная структура каталога lib в VictoriaMetrics:

/lib
  /bytesutil        # Utilities for efficient byte slice manipulation
  /compress         # Compression algorithms and helpers
  /encoding         # Data encoding/decoding utilities
  /errors           # Error handling helpers
  /fs               # Filesystem abstraction and helpers
  /httpserver       # HTTP server utilities
  /logger           # Logging utilities
  /mathutil         # Math-related helpers and optimizations
  /netutil          # Networking utilities
  /storage          # Core storage logic and abstractions
  /syncutil         # Synchronization primitives and helpers
  /timeutil         # Time-related utilities
  /trace            # Lightweight tracing utilities

Каждый подкаталог содержит переиспользуемые библиотеки Go, которые обеспечивают основные функции и оптимизации, используемые в проекте.

Типичная структура каталога docs в VictoriaMetrics:

/docs/victoriametrics
  /changelog           # Changelog and release notes
  /cluster-victoriametrics  # Cluster mode documentation
  /single-server-victoriametrics # Single-node mode documentation
  /vmagent             # Documentation for vmagent
  /vmalert             # Documentation for vmalert
  /vmauth              # Documentation for vmauth
  /vmbackup            # Documentation for vmbackup
  /vmrestore           # Documentation for vmrestore
  /vmctl               # Documentation for vmctl
  /integrations        # Guides for integrations (Grafana, Prometheus, etc.)
  /Quick-Start.md      # Quick start guide
  /README.md           # Main documentation index

Каждый подкаталог или файл содержит руководства, инструкции по использованию, сведения о конфигурации и справочные материалы для соответствующего компонента VictoriaMetrics.

Типичная структура каталога tests в VictoriaMetrics:

/apptest/tests
  /integration      # End-to-end integration tests for VictoriaMetrics components
  /cluster          # Tests specific to cluster mode (vmstorage, vminsert, vmselect)
  /single           # Tests for single-node mode
  /vmagent          # Integration tests for vmagent
  /vmalert          # Integration tests for vmalert
  /vmauth           # Integration tests for vmauth
  /vmbackup         # Integration tests for vmbackup and vmrestore
  /vmctl            # Integration tests for vmctl
  /utils            # Test utilities and helpers

Каждый подкаталог содержит тестовые файлы и ресурсы для проверки интеграции и взаимодействия компонентов VictoriaMetrics в различных сценариях деплоя.

main.go

Файлы main.go для компонентов VictoriaMetrics находятся в соответствующих подкаталогах app.

• /app/vmsingle/main.go — точка входа для одноузловой инсталляции VictoriaMetrics

• /app/vmagent/main.go — точка входа для vmagent

• /app/vmalert/main.go — точка входа для vmalert

• /app/vmauth/main.go — точка входа для vmauth

• /app/vmbackup/main.go — точка входа для vmbackup

Каждый компонент имеет свой собственный файл main.go, который служит точкой входа исполняемого файла.

Централизованного файла для импорта всего нет; каждый компонент или библиотека управляет своими импортами локально в соответствующем каталоге и файлах. Импорты обычно размещаются в начале каждого исходного файла Go, следуя стандартным соглашениям Go.

Скомпилированные бинарные файлы после сборки: 📁 bin

Все скомпилированные бинарные файлы компонентов VictoriaMetrics находятся в каталоге app. После сборки проекта (с помощью make или предоставленных скриптов сборки) полученные бинарные файлы обычно помещаются в каталог bin в корне репозитория.

Установка

Итак, вы можете установить VictoriaMetrics на своё окружение несколькими способами:

1. Загрузите и запустите бинарный файл (Docker не требуется)

Для официальных релизов вы также можете загрузить готовые бинарные файлы со страницы релизов VictoriaMetrics на GitHub . Загрузите соответствующий бинарный файл для вашей ОС (например, victoria-metrics-amd64-vX.Y.Z).

Распакуйте и запустите:

./victoria-metrics-amd64-vX.Y.Z
#By default, this starts the single-node server on port 8428.

Я думаю, что более чистым решением будет использование Docker (рекомендуется для простой настройки)

Загрузите образ:

docker pull victoriametrics/victoria-metrics

Запустите контейнер:

docker run -d -p 8428:8428 victoriametrics/victoria-metrics

Приложение React в VictoriaMetrics связано с компонентом vmui. Компонент vmui представляет собой фронтенд-приложение на React и не имеет точки входа на Go, как другие бэкенд-компоненты. Код, который вы видите в src, написан на чистом React/TypeScript.

Это воркфлоу:

1. Точка входа во фронтенд: src/index.tsx инициализирует приложение React и отображает App.tsx.

2. Структура приложения: App.tsx управляет маршрутизацией и макетом, вызывая различные страницы или компоненты на основе URL.

3. Страницы/Компоненты

• Каждая страница/компонент (например, ActiveQueries) извлекает данные с помощью таких хуков, как useFetchActiveQueries.ts.

4. API-запросы

• Хуки/компоненты отправляют HTTP-запросы (с помощью fetch, axiosи т. д.) к конечным точкам REST. Пример:

const response = await fetch(fetchUrl); // fetchUrl points to a backend API

5. Бэкэнд-сервисы Go

• Фронтенд не вызывает напрямую скрипты Go или файлы main.go.

• Вместо этого он взаимодействует с работающими внутренними службами Go (исполняемыми файлами, созданными из файлов main.go) через HTTP API.

• Каждая внутренняя служба (например, vmsingle, vmagent, vmselect, и т.д.) предоставляет собственные конечные точки HTTP.

Другими словами, каждый файл main.go — это точка входа для бэкенд-сервиса. При запуске бэкенд-файла (например, ./vmsingle) он запускает HTTP-сервер.

VictoriaMetrics запускает свой HTTP-сервер, используя стандартную библиотеку Go net/http.

Реализация базы данных (БД) для VictoriaMetrics в основном расположена в бэкэнд-коде Go, а не в фронтэнде React.

/app/vmsingle/         // Single-node DB entry point (main.go)
/app/vmstorage/        // Cluster storage node entry point (main.go)
/lib/storage/          // Core storage logic, DB engine, indexing, and data management
/lib/encoding/         // Data encoding/decoding utilities for storage
/lib/compress/         // Compression algorithms for efficient DB storage

Фактически ядро ​​СУБД, индексация и управление данными реализованы в хранилище.

Файл /app/vmsingle/main.go запускает серверные процессы базы данных.

Остальная вспомогательная логика работы БД распределена по директориям 📁 encoding и 📁 compress.

Прямая вставка данных в файлы базы данных (например, в хранилище 📁 или в базовые каталоги хранения) — плохая практика . На самом деле, мы не делаем этого ни в одном проекте.

VictoriaMetrics управляет целостностью данных, индексацией, сжатием и согласованностью с помощью своих внутренних служб.

Прямые манипуляции с файлами могут повредить базу данных, нарушить индексы или привести к потере данных.

Для вставки данных всегда используйте официальные эндпоинты HTTP API или поддерживаемые методы приема данных (например, Prometheus remote write, /api/v1/import).

Чтобы изучить внутреннее устройство БД, начните с storage.go .

Основной механизм хранения данных VictoriaMetrics реализован в файле storage.go.

• Основным типом является Storage, который управляет всеми аспектами данных временных рядов: приемом, индексацией, запросами, сохранением и созданием снапшотов.

• Здесь определены ключевые функции, такие как MustOpenStorage, AddRows, SearchMetricNames, DeleteSeries и MustClose.

• Этот файл координируется с другими файлами в хранилище для разделов, индексации и управления метриками.

При добавлении данных VictoriaMetrics не создаёт единый «файл хранилища» в традиционном понимании. Вместо этого система использует специализированный механизм хранения, который организует данные в несколько файлов и каталогов для повышения производительности, надёжности и масштабируемости.

Данные хранятся в структуре каталогов по пути к базе данных (например, /data/vmstorage).

Движок создает и управляет несколькими файлами:

• Индексные файлы: для быстрого поиска и выполнения запросов.

• Файлы данных: для хранения фактических значений временных рядов.

• Кэш-файлы: для ускорения повторяющихся запросов.

• Каталоги Snapshot: для резервного копирования и восстановления.

• Абстракция таблицы: поле tb *table в структуре Storageотносится к основной абстракции таблицы, которая обрабатывает низкоуровневые файловые операции и структуру данных.

Обратите внимание, что данные распределены по нескольким файлам и каталогам, а не по одному «файлу хранения».

Движок периодически ротирует файлы индекса и управляет политикой хранения, удаляя старые файлы данных по мере необходимости.

Файлы, которыми управляет движок хранения в storage.go (и связанные каталоги данных), могут стать очень большими, поэтому важно регулярно отслеживать использование диска и устанавливать соответствующие периоды хранения для автоматического удаления старых данных.

Помимо времени хранения используйте ограничения по частотности данных (MaxHourlySeries, MaxDailySeries), чтобы предотвратить неконтролируемый рост.

Ограничения на количество элементов в VictoriaMetrics помогают контролировать количество уникальных временных рядов (метрик с различными комбинациями меток), которые можно хранить в базе данных. Это предотвращает чрезмерное разрастание файлов базы данных и заполнение всего дискового пространства или памяти.

• MaxHourlySeries: ограничивает количество новых уникальных временных рядов, которые можно создать за один час.

• MaxDailySeries: ограничивает количество новых уникальных временных рядов, которые можно создать за один день.

Зачем они нужны?
Если вы случайно отправите слишком много уникальных метрик (например, с постоянно меняющейся меткой), база данных может бесконтрольно разрастись. Установка этих ограничений защищает вашу систему от подобных ошибок и обеспечивает стабильную работу VictoriaMetrics.

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

cd VictoriaMetrics
make victoria-metrics
./bin/victoria-metrics

Как вы можете заметить, для кластерного режима рекомендуется Docker Compose или Kubernetes.

Спасибо за внимание и подписывайтесь на наш телеграм-канал Мониторим ИТ, там еще больше полезной информации о мониторинге!