Сбор метрик
###########

Данная инструкция описывает способ сбора метрик **Space Station 14**, таких как
текущий онлайн игроков или нагрузка Сети с использованием програмного стека
**Grafana** и **Prometheus**.

.. note::
  - Предполагается, что читатель имеет базовые навыки работы с **Linux** системами;
  - Предполагается, что читатель умеет подключаться к удалённому серверу через **SSH**;
  - В качестве удалённой операционной системы будет использоваться **Debian 12**.

Prometheus
**********

Для сбора метрик, нам понадобится установить **Prometheus**.

**Prometheus** - это бесплатное программное обеспечение, используемое для
мониторинга и оповещения о событиях.

Принцип его работы достаточно прост: раз в 15 секунд (по-умолчанию), "прометей"
опрашивает указанные в настройках точки интереса и собирает по ним данные в свою
встроенную базу данных.


Установка и настройка
=====================

1. Открываем |link_prometheus|

2. Выбираем операционную систему **Linux**

3. Скачиваем архив с отметкой LTS *(Long term support, Долгосрочная поддержка)*
   на удалённый сервер

   .. code-block:: bash
    
    cd /root
    wget 'https://github.com/prometheus/prometheus/releases/download/v2.45.5/prometheus-2.45.5.linux-amd64.tar.gz'

4. Распаковываем полученный архив

  .. code-block:: bash

    mkdir /root/prometheus
    tar -xf /root/prometheus-2.45.5.linux-amd64.tar.gz -C /root/prometheus --strip-component=1
    mkdir /root/prometheus/data

5. Открываем файл ``/root/prometheus/prometheus.yml`` и заменяем всё его
   содержимое на следующее

  .. code-block:: yaml

    global:
      scrape_interval: 15s
      evaluation_interval: 15s

    scrape_configs:
      - job_name: 'ss14'
        static_configs:
          - targets: ['127.0.0.1:9001']

6. Создаём новый файл ``/etc/systemd/system/prometheus.service`` и записываем
   туда следующее

  .. code-block::

    [Unit]
    Description=Prometheus Service
    After=syslog.target network.target

    [Service]
    Type=simple
    WorkingDirectory=/root/prometheus
    ExecStart=/root/prometheus/prometheus \
                    --config.file=/root/prometheus/prometheus.yml \
                    --storage.tsdb.path=/root/prometheus/data \
                    --storage.tsdb.retention.time=14d \
                    --web.listen-address="0.0.0.0:9000"
    Restart=on-failure

    [Install]
    WantedBy=multi-user.target

  .. warning::
    | Т.к. **Prometheus** не предназначен для долговременного хранения метрик,
      крайне не рекомендуется указывать срок хранения данных более 14 дней
    | (параметр ``--storage.tsdb.retention.time``).

  .. warning::
    | **Обратите внимание:**
    | Мы указали в параметре ``--web.listen-address`` широковещательный адрес
      ``0.0.0.0``. В инструкции это сделано намеренно для удобной проверки
      правильной настройки всех систем.
    | На своём сервере, после всех проверок, вы **ОБЯЗАНЫ** заменить адрес
      ``0.0.0.0`` на ``127.0.0.1``!

7. Выполняем повторное считываение сервисов и запускаем сервис **Prometheus**

  .. code-block:: bash

    systemctl daemon-reload
    systemctl start prometheus

Если всё сделано правильно, по адресу ``http://ip-вашего-сервера:9000/``
будет отображаться интерфейс "прометея".

.. image:: _static/prometheus.png
    :alt: Панель управления Prometheus


Настройка игрового сервера
==========================

Открываем на редактирование конфигурационный файл игрового сервера
``server_config.toml`` и добавляем туда следующую секцию

.. code-block:: toml

  [metrics]
  enabled = true
  host = "127.0.0.1"
  port = 9001
  runtime = false

.. note::
  Если игровой сервер был запущен, то перезапустите его для применения новых
  настроек

Если всё сделано правильно, то в панеле "прометея", в разделе "Startus" -> "Targets"
будет отображаться "зелёным" наша точка интереса.

.. image:: _static/prometheus_targets.png
  :alt: Успешно настроенная точка сбора метрик


Мы так же можем проверить собранные данные, перейдя в панеле "прометея" в раздел
"Graph" и выбрав любую метрику. Например, ``robust_server_uptime`` показывает
сколько времени (в секундах) "живёт" игровой сервер

.. image:: _static/prometheus_uptime.png
  :alt: График "жизни" игрового сервера


Grafana
*******

Смотреть метрики через интерфейс **Prometheus** можно, но не удобно. Удобнее
будет следить за метриками через другое бесплатное програмное обеспечение
**Grafana**.


База данных
===========

Начнём с настройки доступов к базе данных **Postgres**.

1. Подключаемся к интерактивной postgres-консоли

  .. code-block:: bash

    sudo -u postgres psql

  Дальнейшие команды будут выполняться в ней.

2. Создаём базу данных

  .. code-block:: sql

    CREATE DATABASE grafana;

3. Добавляем к новосозданной БД пользователя, указываем ему пароль
   и предоставляем все права на базу:

  .. code-block:: sql

    CREATE USER grafana_user WITH encrypted password 'ChangeMePlease';
    GRANT ALL PRIVILEGES ON DATABASE grafana TO grafana_user;
    ALTER DATABASE grafana OWNER TO grafana_user;

4. Выходим из интерактивной postgres-консоли

  .. code-block::

    \q


Установка
=========

1. Открываем |link_grafana|

2. В поле "Edition" **обязательно** указываем значение "OSS"

3. Нас интересует строчка загрузки из раздела "Standalone Linux Binaries"

  .. image:: _static/grafana_link.png
    :alt: Строка загрузки Grafana

4. Скачиваем архив на удалённом сервере

  .. code-block:: bash

    cd /root
    wget 'https://dl.grafana.com/oss/release/grafana-11.0.0.linux-amd64.tar.gz'

5. Распаковываем архив

  .. code-block:: bash

    tar -xf /root/grafana-11.0.0.linux-amd64.tar.gz -C /root
    mv /root/grafana-v11.0.0 /root/grafana

6. Подготавливаем папки

  .. code-block:: bash

    mkdir -p /root/grafana/data/log
    mkdir -p /root/grafana/data/plugins

7. Копируем "дефолтный" файл конфигурации

  .. code-block:: bash

    cp /root/grafana/conf/defaults.ini /root/grafana/conf/grafana.ini

8. Открываем на редактирование новый конфигурационный файл
   ``/root/grafana/conf/grafana.ini``

  1. В секции ``[paths]`` указываем абсолютные пути к данным, логам и прочему

    .. code-block:: ini

      [paths]
      data = /root/grafana/data
      logs = /root/grafana/data/log
      plugins = /root/grafana/data/plugins
      provisioning = /root/grafana/conf/provisioning

  2. В секции ``[database]`` указываем данные подключения к БД Postgres

    .. code-block:: ini
      
      [database]
      type = postgres
      host = 127.0.0.1:5432
      name = grafana
      user = grafana_user
      password = """ChangeMePlease"""

  3. В секции ``[security]`` указываем логин и пароль администратора
     по-умолчанию

    .. code-block:: ini

      [security]
      admin_user = Voomra
      admin_password = ChangeMePlease

9. Создаём новый файл ``/etc/systemd/system/grafana.service`` и записываем туда
   следующее

  .. code-block::

    [Unit]
    Description=Grafana Service
    After=syslog.target network.target
    After=postgresql.service

    [Service]
    Type=simple
    WorkingDirectory=/root/grafana
    ExecStart=/root/grafana/bin/grafana-server --config=/root/grafana/conf/grafana.ini
    Restart=on-failure

    [Install]
    WantedBy=multi-user.target

10. Выполняем повторное считываение сервисов и запускаем сервис **Grafana**

  .. code-block:: bash

    systemctl daemon-reload
    systemctl start grafana

Если всё сделано было правильно, то по адресу ``http://ip-вашего-сервера:3000/``
будет отображаться форма входа в панель управления **Grafana**

.. image:: _static/grafana_login.png
  :alt: Форма входа в панель управления Grafana


Настройка
=========

Добалвение источника данных
---------------------------

1. Перейти в "Connection" -> "Data sources"

  .. image:: _static/grafana_add_source1.png
    :alt: Меню добавление нового источника данных

2. Нажимаем на кнопку "Add data source"

3. Выбираем "Prometheus"

  .. image:: _static/grafana_add_source2.png
    :alt: Источник данных "Prometheus"

4. В поле "Connection" указываем адрес **Prometheus** ``http://127.0.0.1:9000``

  .. image:: _static/grafana_add_source3.png
    :alt: Адрес Prometheus

5. | Внизу страницы нажимаем на кнопку "Save & test".
   | Если появилась "зелёное" оповещение, значит всё хорошо.
   
  .. image:: _static/grafana_add_source4.png
    :alt: Проверка источника данных


Исследование в источнике данных
-------------------------------

После того как был добавлен источник данных, с ним уже можно работать. Для этого
переходим в окно "Explore"

.. image:: _static/grapana_explore1.png
  :alt: Explore

Дальше, в поле "Metrics" вбиваем нужную метрику, например
``robust_server_uptime`` и жмем на синюю кнопку обновления в правом верхнем углу

.. image:: _static/grapana_explore2.png
  :alt: Выбор метрики

После этого внизу отобразиться график с данными

.. image:: _static/grapana_explore3.png
  :alt: График метрики


Добавляем Dashboard
-------------------

Вручную помнить все метрики и тем более вручную их искать в источнике данных
совсем не удобное занятие. Гораздо удобнее будет настроить панель с необходимым
набором графиков.

.. note::
  Объяснение типов метрик, видов графиков и прочей информации, что поможет
  вам самостоятельно создавать панели "с нуля" выходит за рамки данной статьи.
  А потому здесь будет только предоставлена готовая панель с уже минимальным
  набором игровых метрик.

1. Переходим в "Dashboards"

  .. image:: _static/grafana_dashboard1.png

2. Выбираем "New" -> "Import"

  .. image:: _static/grafana_dashboard2.png

3. | Загружаем готовую панельку
   | :download:`ss14.grafana.json <_static/ss14.grafana.json>`

  .. image:: _static/grafana_dashboard3.png

4. Указываем источник данных

  .. image:: _static/grafana_dashboard4.png

5. Нажимаем кнопку "Import"

В итоге получаем готовую панель со следующими метриками:

- Uptime игрового сервера
- TPS (Tick per second)
- Онлайн игроков
- Длительность раунда
- Сетевой трафик

.. image:: _static/grafana_dashboard5.png
  :alt: Панель метрик Space Station 14

.. -----------------------------------------------------------------------------

.. |link_prometheus| raw:: html
  
  <a href="https://prometheus.io/download/" target="_blank">страницу загрузки</a>

.. |link_grafana| raw:: html
  
  <a href="https://grafana.com/grafana/download?edition=oss" target="_blank">страницу загрузки</a>
