observium-telemetry

Project Context / Контекст проекта:

🇬🇧 This project was developed as part of a learning journey, evolving gradually through the course. The architecture evolved alongside gaining new knowledge, making some architectural decisions potentially suboptimal or requiring revision. The project's main value lies in demonstrating practical application of various technologies like Go, gRPC, Echo, PostgreSQL, and others. My current expertise with these technologies has significantly grown since working on this project. For more mature architectural approaches, please check: Aegis Vault Keeper

🇷🇺 Этот проект был создан в рамках учебного курса и развивался поэтапно по мере обучения. Архитектура проекта эволюционировала вместе с получением новых знаний, поэтому некоторые архитектурные решения могут быть неоптимальными или требовать переработки. Основная ценность проекта - демонстрация практического применения различных технологий, таких как Go, gRPC, Echo, PostgreSQL и других. Мой текущий уровень владения этими технологиями значительно вырос с момента работы над проектом. Более зрелые подходы к архитектуре можно найти в проекте: Aegis Vault Keeper

Observium Telemetry

English version | Русская версия

Contents

• Project Description
• Key Technologies
• Technology Stack
  • Languages and Protocols
  • Libraries
  • Development Tools
  • Monitoring
  • Security
  • Logging
  • Data Formats
  • Configuration and Infrastructure
• Implementation Approaches
• Installation
  • Requirements
  • Configuration
    • Server
    • Agent
• Makefile Commands
• Project Structure
• Possible Improvements

Project Description

Observium Telemetry is a distributed metrics collection and monitoring system developed in Go. The project implements a client-server architecture with the following main components:

1. Agent - client application for metrics collection. Includes:

   • Metrics Collection:
     • GopsStats - CPU and memory metrics via gopsutil
     • MemStats - Go memory metrics via runtime.ReadMemStats
     • CollectStrategy interface for adding new strategies
     • System metadata collection
   • Metrics Processing:
     • Stream collection via StreamCollector
     • Data compression via compress
     • Request building and validation
     • Sending via StreamSender
   • Infrastructure:
     • Environment variable configuration
     • Entity data models
     • Configurable collection intervals
     • Profiling capability

2. Server - application for receiving and storing metrics. Includes:

   • API:
     • HTTP server using Echo
     • gRPC server
     • Handlers for update, updates, and value
     • Main page and ping
   • Middleware:
     • Authentication and request signing
     • gzip compression
     • Request logging
     • Cryptographic protection
   • Data Storage:
     • In-memory storage
     • File storage
     • Prepared structure for PostgreSQL
     • SQL migrations
   • Internal Structure:
     • Metrics controller
     • Data models
     • HTML template rendering
     • Environment configuration

Key Technologies

API and Communications

• gRPC: unary RPC calls, protobuf contracts
• REST API: Echo framework, middleware, HTTP server
• Network: HTTP client, rate limiting, data compression

Data and Storage

• SQL: PostgreSQL, migrations, DB interfaces
• File system operations
• In-memory caching

Reliability and Security

• Graceful shutdown
• Retry mechanisms
• Cryptography: RSA, data signing
• Middleware: authentication, compression, logging

Monitoring and Logging

• System metrics collection
• Structured logging via zap
• Profiling via pprof

Tools

• Static code analysis
• Unit testing
• Makefile build system

Technology Stack

Languages and Protocols

• Go
• Protocol Buffers
• REST API
• HTML

Libraries

• Echo framework for HTTP server
• gRPC for API
• pgx for PostgreSQL
• golang-migrate for migrations
• gopsutil for system metrics
• resty for HTTP client
• testify for tests
• uber-go/zap for logging

Development Tools

• golangci-lint
• go-critic
• errcheck
• fieldalignment
• goimports
• golines
• jq

Monitoring

• Basic profiling
• CPU and memory metrics
• runtime.MemStats usage
• Scheduled metrics collection

Security

• Request signing
• RSA key generation
• Signature verification
• Request rate limiting

Logging

• uber-go/zap
• Basic logging levels
• Component-based logging
• HTTP and gRPC request logging

Data Formats

• JSON
• Protocol Buffers
• gzip
• HTML templates

Configuration and Infrastructure

• Environment variables
• Command line flags
• Optional JSON configuration
• Graceful shutdown
• Error retries
• In-memory and file storage
• SQL migrations

Implementation Approaches

1. Code Analysis

   • Analysis based on golang.org/x/tools/go/analysis
   • os.Exit usage verification
   • Error checking
   • Basic code formatting
   • Struct field alignment

2. Project Structure

   • Functionality-based package separation
   • Constructor-based initialization
   • Interface usage

3. Tests

   • Basic unit tests
   • Subtest grouping
   • testify checks
   • Database mocks
   • Disabled logging in tests
   • Data-driven tests
   • Edge case tests

4. Data Protection

   • Metrics signing
   • Signature verification
   • Basic security measures

Installation

Requirements

1. Go version from go.mod
2. Make
3. golangci-lint (for development)
4. goimports (for development)
5. golines (for development)
6. fieldalignment (for development)

Configuration

Server

Configuration via environment variables or flags:

• SERVER_ADDRESS - HTTP server address (default: localhost:8080)
• GRPC_SERVER_ADDRESS - gRPC server address (default: :3200)
• STORE_INTERVAL - metrics storage interval (default: 300s)
• FILE_STORAGE_PATH - storage file path
• RESTORE - restore data on startup (default: true)
• DATABASE_DSN - PostgreSQL connection string
• CRYPTO_KEY - public key path for signature verification
• CONFIG - configuration file path (optional, JSON)

Agent

Configuration via environment variables or flags:

• ADDRESS - server address (default: localhost:8080)
• POLL_INTERVAL - metrics collection interval (default: 2s)
• REPORT_INTERVAL - metrics sending interval (default: 10s)
• CRYPTO_KEY - private key path for signing
• RATE_LIMIT - request rate limit (default: 3)
• CONFIG - configuration file path (optional, JSON)

Starting the Server

make run-server

Starting the Agent

make run-agent

Makefile Commands

• make help - show available commands
• make run-agent - run agent
• make run-server - run server
• make keys - generate keys
• make deps - update dependencies
• make test - run tests with coverage analysis
• make lint - run linter and format code
• make run-staticlint - run static analyzer

Project Structure

.
├── cmd/                    # Entry points
│   ├── agent/             # Metrics collection agent
│   ├── keycli/            # Key generation utility
│   ├── server/            # Metrics server
│   └── staticlint/        # Custom linter
├── internal/              # Internal logic
│   ├── agent/            # Agent logic
│   ├── server/           # Server logic
│   └── staticlint/       # Code analyzers
├── pkg/                   # Reusable packages
│   ├── convert/          # Type conversion
│   ├── logging/          # Logging utilities
│   ├── retry/            # Retry mechanisms
│   └── sign/             # Signing utilities
├── proto/                # Protobuf definitions
└── web/                  # Web resources

Possible Improvements

1. New metric types
2. Additional storage options
3. Alerting
4. Metrics visualization
5. Integration with other monitoring systems
6. Metrics aggregation
7. Distributed storage

License

LICENSE

Observium Telemetry (ru)

English version | Русская версия

Содержание

• Описание проекта
• Ключевые технологии
• Технологический стек
  • Языки и протоколы
  • Библиотеки
  • Инструменты разработки
  • Мониторинг
  • Безопасность
  • Логирование
  • Форматы данных
  • Конфигурация и инфраструктура
• Реализованные подходы
• Установка
  • Требования
  • Конфигурация
    • Сервер
    • Агент
• Makefile команды
• Структура проекта
• Возможные улучшения

Описание проекта

Observium Telemetry - это распределенная система сбора и мониторинга метрик, разработанная на Go. Проект реализует клиент-серверную архитектуру со следующими основными компонентами:

1. Agent - клиентское приложение для сбора метрик. Включает:

   • Сбор метрик:
     • GopsStats - метрики CPU и памяти через gopsutil
     • MemStats - метрики памяти Go через runtime.ReadMemStats
     • Интерфейс CollectStrategy для добавления новых стратегий
     • Сбор метаданных о системе
   • Работа с метриками:
     • Потоковый сбор через StreamCollector
     • Сжатие данных через compress
     • Построение и валидация запросов
     • Отправка через StreamSender
   • Инфраструктура:
     • Конфигурация через переменные окружения
     • Модели данных в entity
     • Настраиваемые интервалы сбора
     • Возможность профилирования

2. Server - приложение для приема и хранения метрик. Включает:

   • API:
     • HTTP сервер на Echo
     • gRPC сервер для стриминга метрик
     • Обработчики для update, updates и value
     • Главная страница и пинг
   • Middleware:
     • Аутентификация и подпись запросов
     • Сжатие gzip
     • Логирование запросов
     • Криптографическая защита
   • Хранение данных:
     • In-memory хранилище
     • Файловое хранилище
     • Подготовлена структура для PostgreSQL
     • SQL миграции
   • Внутренняя структура:
     • Контроллер метрик
     • Модели данных
     • Рендеринг HTML шаблонов
     • Конфигурация через env

Ключевые технологии

API и коммуникации

• gRPC: унарные RPC вызовы, protobuf контракты
• REST API: Echo framework, middleware, HTTP сервер
• Работа с сетью: HTTP клиент, rate limiting, сжатие данных

Данные и хранение

• SQL: PostgreSQL, миграции, работа с БД через интерфейсы
• Работа с файловой системой
• In-memory кеширование

Надежность и безопасность

• Graceful shutdown
• Retry механизмы
• Криптография: RSA, подпись данных
• Middleware: аутентификация, сжатие, логирование

Мониторинг и логирование

• Сбор системных метрик
• Структурированное логирование через zap
• Профилирование через pprof

Инструментарий

• Статический анализ кода
• Unit-тестирование
• Сборка через Makefile

Технологический стек

Языки и протоколы

• Go
• Protocol Buffers
• REST API
• HTML

Библиотеки

• Echo framework для HTTP сервера
• gRPC для API
• pgx для PostgreSQL
• golang-migrate для миграций
• gopsutil для системных метрик
• resty для HTTP клиента
• testify для тестов
• uber-go/zap для логирования

Инструменты разработки

• golangci-lint
• go-critic
• errcheck
• fieldalignment
• goimports
• golines
• jq

Мониторинг

• Базовое профилирование через pprof
• Сбор метрик CPU и памяти
• Использование runtime.MemStats
• Сбор системных метрик по расписанию

Безопасность

• Подпись запросов
• Генерация RSA ключей
• Проверка подписи
• Ограничение частоты запросов

Логирование

• uber-go/zap
• Базовые уровни логирования
• Логирование по компонентам
• Логирование HTTP и gRPC запросов

Форматы данных

• JSON
• Protocol Buffers
• gzip
• HTML шаблоны

Конфигурация и инфраструктура

• Конфигурация через переменные окружения
• Параметры командной строки
• Опциональная JSON конфигурация
• Корректное завершение работы
• Повторные попытки при ошибках
• In-memory и файловое хранение данных
• SQL миграции

Реализованные подходы

1. Анализ кода

   • Анализатор на базе golang.org/x/tools/go/analysis
   • Проверка использования os.Exit
   • Проверка обработки ошибок через errcheck
   • Форматирование кода
   • Выравнивание полей структур

2. Структура проекта

   • Разделение на пакеты
   • Инициализация через конструкторы
   • Использование интерфейсов

3. Тесты

   • Unit-тесты пакетов
   • Группировка через subtests
   • Проверки через testify/assert
   • Моки для тестов с БД
   • Отключение логов в тестах
   • Тесты с наборами данных
   • Проверка пограничных случаев
   • Замер покрытия кода

4. Защита данных

   • Подпись метрик
   • Проверка подписи
   • Базовые меры безопасности

Установка

Требования

1. Go версии из go.mod
2. Make
3. golangci-lint (для разработки)
4. goimports (для разработки)
5. golines (для разработки)
6. fieldalignment (для разработки)

Конфигурация

Сервер

Конфигурация через переменные окружения или флаги:

• SERVER_ADDRESS - адрес HTTP сервера (default: localhost:8080)
• GRPC_SERVER_ADDRESS - адрес gRPC сервера (default: :3200)
• STORE_INTERVAL - интервал сохранения метрик (default: 300s)
• FILE_STORAGE_PATH - путь к файлу хранилища
• RESTORE - восстанавливать ли данные при старте (default: true)
• DATABASE_DSN - строка подключения к PostgreSQL
• CRYPTO_KEY - путь к публичному ключу для проверки подписи
• CONFIG - путь к файлу конфигурации (опционально, JSON)

Агент

Конфигурация через переменные окружения или флаги:

• ADDRESS - адрес сервера (default: localhost:8080)
• POLL_INTERVAL - интервал сбора метрик (default: 2s)
• REPORT_INTERVAL - интервал отправки метрик (default: 10s)
• CRYPTO_KEY - путь к приватному ключу для подписи
• RATE_LIMIT - ограничение количества запросов (default: 3)
• CONFIG - путь к файлу конфигурации (опционально, JSON)

Запуск сервера

make run-server

Запуск агента

make run-agent

Makefile команды

• make help - показать список доступных команд
• make run-agent - запустить агент
• make run-server - запустить сервер
• make keys - сгенерировать ключи
• make deps - обновить зависимости
• make test - запустить тесты с анализом покрытия
• make lint - запустить линтер и форматирование кода
• make run-staticlint - запустить статический анализатор

Структура проекта

.
├── cmd/                    # Точки входа приложений
│   ├── agent/             # Агент сбора метрик
│   ├── keycli/            # Утилита генерации ключей
│   ├── server/            # Сервер приема метрик
│   └── staticlint/        # Кастомный линтер
├── internal/              # Внутренняя логика
│   ├── agent/            # Логика агента
│   ├── server/           # Логика сервера
│   └── staticlint/       # Анализаторы кода
├── pkg/                   # Переиспользуемые пакеты
│   ├── convert/          # Конвертация типов
│   ├── logging/          # Работа с логами
│   ├── retry/            # Механизм повторных попыток
│   └── sign/             # Работа с подписью
├── proto/                # Protobuf описания
└── web/                  # Веб-ресурсы

Возможные улучшения

Проект может быть расширен:

1. Новые типы собираемых метрик
2. Дополнительные варианты хранения данных
3. Добавление алертинга
4. Визуализация метрик
5. Интеграция с другими системами мониторинга
6. Агрегация метрик
7. Распределенное хранение

Лицензия

LICENSE