Розгортання Sig

Конфігурація SigNoz та застосунків

Після успішного встановлення SigNoz необхідно налаштувати до нього доступ та почати надсилати дані з ваших застосунків. Ми також забезпечимо безпечне з'єднання з UI SigNoz через HTTPS.

1. Початковий доступ до UI SigNoz

За замовчуванням UI SigNoz доступний за адресою http://ВАША_IP_АДРЕСА:3301. Відкрийте його у браузері. При першому вході вам буде запропоновано створити обліковий запис адміністратора. Задайте ім'я користувача та надійний пароль.

2. Налаштування HTTPS за допомогою Caddy

Використання HTTP для доступу до панелі моніторингу вкрай небажано. Ми налаштуємо Caddy — простий у використанні веб-сервер з автоматичною видачею та оновленням TLS-сертифікатів Let's Encrypt — для забезпечення HTTPS-доступу.

Попередні кроки:

1. Переконайтеся, що ваш домен (наприклад, signoz.yourdomain.com) вказує на IP-адресу вашого VPS.
2. Переконайтеся, що порти 80 (HTTP) та 443 (HTTPS) відкриті у вашому UFW (ми вже відкрили їх у розділі "Підготовка сервера").

Встановлення Caddy:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y # Встановлення Caddy

Конфігурація Caddyfile:

Створіть або відредагуйте файл /etc/caddy/Caddyfile. Замініть signoz.yourdomain.com на ваш реальний домен.

# /etc/caddy/Caddyfile
signoz.yourdomain.com {
    # Автоматична видача та оновлення TLS-сертифікатів
    tls {
        # Використовуйте ваш email для сповіщень Let's Encrypt
        email [email protected]
    }

    # Проксіювання всіх запитів до SigNoz Frontend
    reverse_proxy localhost:3301 {
        # Додавання необхідних заголовків для коректної роботи
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
    }

    # Увімкнення стиснення (опціонально, але рекомендується)
    encode gzip zstd

    # Логування доступу (опціонально)
    log {
        output file /var/log/caddy/access.log
        format json
    }
}

Створіть директорію для логів Caddy:

sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

Перезапуск Caddy:

sudo caddy validate -adapter caddyfile --config /etc/caddy/Caddyfile # Перевірка конфігурації
sudo systemctl reload caddy # Перезавантаження Caddy для застосування змін
sudo systemctl enable caddy # Переконатися, що Caddy запускається при старті системи

Тепер ви можете отримати доступ до SigNoz за адресою https://signoz.yourdomain.com.

3. Надсилання даних до SigNoz за допомогою OpenTelemetry

SigNoz активно використовує OpenTelemetry (OTel) — відкритий стандарт для збору телеметрії. Для надсилання логів, метрик та трасувань з ваших застосунків вам потрібно буде інтегрувати OTel SDK у ваш код або використовувати OTel Collector.

Приклад для Node.js застосунку (базове трасування):

Встановіть необхідні пакети OpenTelemetry:

npm install @opentelemetry/sdk-node @opentelemetry/api @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-otlp-proto-http @opentelemetry/sdk-trace-node

Створіть файл tracing.js:

// tracing.js
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-otlp-proto-http');

const traceExporter = new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces', // Адреса SigNoz OpenTelemetry Collector
});

const sdk = new opentelemetry.NodeSDK({
  serviceName: 'my-node-app',
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start()
  .then(() => console.log('Tracing initialized'))
  .catch((error) => console.error('Error initializing tracing', error));

process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.error('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

Запустіть ваш Node.js застосунок з цим файлом:

node -r ./tracing.js your-app.js

Для інших мов програмування та для надсилання метрик/логів, процес аналогічний: використовуйте відповідні OTel SDK та експортери. OpenTelemetry Collector у SigNoz за замовчуванням слухає порти 4317 (gRPC) та 4318 (HTTP) для трасувань, а також 4317/4318 для метрик та 4317 для логів. При надсиланні даних із застосунку вказуйте адресу localhost:4318 або localhost:4317, оскільки OTel Collector працює в тому ж Docker Compose стеку, що й сам застосунок SigNoz.

Для збору логів з хоста або з інших контейнерів можна налаштувати окремий OpenTelemetry Collector або використовувати Docker log driver, що надсилає логи до SigNoz.

4. Перевірка працездатності

Після налаштування застосунків та надсилання даних, зайдіть в UI SigNoz (https://signoz.yourdomain.com). Перейдіть до розділу "Traces", "Metrics" або "Logs". Ви повинні побачити дані, що надходять. Якщо даних немає, перевірте:

• Логи контейнерів SigNoz: docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs
• Логи Caddy: sudo journalctl -u caddy.service
• Правильність налаштування OTel SDK у вашому застосунку.
• Доступність портів між застосунком та SigNoz OTel Collector.

Усунення несправностей + FAQ

У процесі розгортання та експлуатації SigNoz можуть виникнути різні проблеми. Нижче наведені типові питання та способи їх вирішення.

1. SigNoz UI недоступний за IP-адресою або доменом.

Що перевірити:

• Статус Docker-контейнерів: Переконайтеся, що всі контейнери SigNoz запущені.

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml ps

  Усі сервіси повинні бути у стані running. Якщо ні, перевірте логи проблемного контейнера:

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs signoz-frontend

• Фаєрвол (UFW): Переконайтеся, що порти 80, 443 (для Caddy) та 3301 (для прямого доступу до SigNoz UI) відкриті.

  sudo ufw status verbose

• Caddy: Якщо використовуєте Caddy, перевірте його статус та логи.

  sudo systemctl status caddy

  sudo journalctl -u caddy.service

  Переконайтеся, що ваш домен коректно розв'язується в IP-адресу сервера.
• Конфлікти портів: Перевірте, чи не займають інші сервіси порти 80, 443 або 3301.

  sudo netstat -tulpn | grep -E "80|443|3301"

Як виправити: Перезапустіть проблемні сервіси Docker або Caddy. Відкрийте необхідні порти в UFW. Виправте DNS-запис для домену.

2. До SigNoz не надходять логи, метрики або трасування.

Що перевірити:

• Налаштування OpenTelemetry Collector: Переконайтеся, що OTel Collector в SigNoz запущений і слухає потрібні порти.

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs signoz-otel-collector

• Налаштування програми: Перевірте, що ваша програма коректно налаштована для надсилання даних до OTel Collector SigNoz (зазвичай http://localhost:4318 або http://localhost:4317 з інших контейнерів у тій же мережі Docker Compose).

  curl -v -X POST http://localhost:4318/v1/traces -d '{"resourceSpans":[]}'

  Це простий тест на доступність кінцевої точки OTLP.
• Мережева доступність: Якщо програма знаходиться на іншому хості, переконайтеся, що її мережа може дістатися до портів OTel Collector на вашому VPS.
• Помилки в логах програми: Перевірте логи програми, яка повинна надсилати телеметрію, на наявність помилок експорту OTel.

Як виправити: Виправте конфігурацію програми або OTel Collector. Перевірте мережеву зв'язність між компонентами.

3. SigNoz працює повільно або споживає багато ресурсів.

Що перевірити:

• Ресурси сервера: Перевірте завантаження CPU, використання RAM та швидкість диска на вашому VPS.

  htop

  df -h

  iostat -x 1 10

• ClickHouse: ClickHouse є основним споживачем ресурсів. Перевірте його логи на наявність помилок або попереджень.

  docker compose -f ~/signoz/signoz/deploy/docker-compose.yaml logs signoz-clickhouse

• Обсяг даних: Оцініть обсяг даних, що надходять. Можливо, ваш VPS просто не справляється з поточним навантаженням.

Як виправити: Збільшіть ресурси VPS (CPU, RAM, NVMe SSD). Оптимізуйте програми для зменшення обсягу телеметрії, що надсилається (наприклад, семплювання трасувань). Налаштуйте політику зберігання даних у SigNoz для автоматичного видалення старих даних.

4. Який VPS-конфіг мінімально підійде?

Для тестових цілей або дуже невеликих проєктів (1-2 програми, низький обсяг даних) можна почати з 2 CPU, 4 ГБ ОЗУ та 100 ГБ NVMe SSD. Однак для будь-якої серйозної експлуатації, навіть для невеликих команд, рекомендується мінімум 4 CPU, 8-16 ГБ ОЗУ та 200 ГБ NVMe SSD для стабільної роботи та можливості зберігання даних за кілька тижнів.

5. Що обрати — VPS чи dedicated для цього завдання?

Вибір між VPS та виділеним сервером залежить від масштабу та вимог до продуктивності. VPS підходить для більшості середніх проєктів (до 10-20 сервісів, кілька сотень GB даних на місяць) завдяки своїй гнучкості та вартості. Виділений сервер необхідний для великих інсталяцій, де обробляються терабайти даних, потрібна максимальна продуктивність ClickHouse, тривале зберігання або суворі вимоги до ізоляції ресурсів. Якщо ви сумніваєтеся, почніть з VPS і масштабуйтеся до виділеного сервера в міру зростання потреб.

6. Як оновити SigNoz до нової версії?

Для оновлення SigNoz виконайте наступні команди в директорії ~/signoz/signoz/deploy/:

git pull                       # Получить последние изменения из репозитория SigNoz
docker compose -f docker-compose.yaml pull # Загрузить новые версии образов Docker
docker compose -f docker-compose.yaml up -d # Пересоздать контейнеры с новыми образами
docker image prune -f          # Очистить неиспользуемые старые образы Docker

Завжди перевіряйте офіційну документацію SigNoz щодо специфічних інструкцій з оновлення для конкретної версії, оскільки іноді можуть знадобитися додаткові кроки.