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

Для мониторинга платформы ARTA Synergy используется пакет ``arta-synergy-health-monitoring``, 
разработанный на основе ``pmm-client``, в сочетании с PMM-Server. 
``arta-synergy-health-monitoring`` предназначен для мониторинга основных
сервисов и инструментов, используемых Synergy: MySQL, JBoss/Wildfly, nginx, Cassandra, Elasticsearch, 
а также операционной системы сервера.

Данный пакет содержит набор экспортеров метрик, характеризующих состояние вышеперечисленных
сервисов, а также консольный инструмент pmm-admin, позволяющий настроить отправку
метрик на сервер мониторинга. Собранные метрики сохраняются в Prometheus, затем при помощи Grafana
строятся графики состояний, которые можно просматривать в браузере.

.. figure:: ../_static/img/shm_scheme.png

	Архитектура мониторинга Arta Synergy


Установка PMM-Server
--------------------

PMM-Server рекомендуется устанавливать на отдельном сервере, операционная система которого поддерживает Docker. Для каждого отслеживаемого узла требуется примерно 1 ГБ памяти на диске при сроке хранения данных, равном одной неделе. Согласно `официальной документации <https://www.percona.com/doc/percona-monitoring-and-management/faq.html#what-are-the-minimum-system-requirements-for-pmm>`_, требуемый минимальный объем памяти составляет 2 ГБ для одного отслеживаемого узла, но, когда вы добавляете больше узлов, необходимый объём памяти возрастает нелинейно. Например, данные с 20 узлов должны легко обрабатываться с 16 ГБ памяти.

Установка Docker
~~~~~~~~~~~~~~~~

Предварительно следует установить некоторые дополнительные пакеты:

``aptitude install apt-transport-https ca-certificates curl software-properties-common``

Далее добавить ключ для хранилища Docker:

``wget https://download.docker.com/linux/debian/gpg`` 

``apt-key add gpg``

Затем подключить репозиторий Docker:

``echo "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/docker.list``

Обновить список пакетов и установить Docker:

``aptitude update``

``aptitude install docker-ce``

После установки запустить и включить Docker для запуска при загрузке:

``systemctl start docker``

``systemctl enable docker``


Создание контейнеров PMM-Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Для установки собственно PMM-Server'а нужно получить его образ с Docker Hub:

``docker pull percona/pmm-server:latest``

Затем создать контейнер для обновляемых данных мониторинга:

.. code-block:: bash

    docker create \
    -v /opt/prometheus/data \
    -v /opt/consul-data \
    -v /var/lib/mysql \
    -v /var/lib/grafana \
    --name pmm-data \
    percona/pmm-server:latest /bin/true


Данная команда делает следующее:

* ``docker create`` создаёт контейнер на основе указанного образа;

* опция -v инициализирует тома для хранения данных в контейнере;

* опция ``--name`` задаёт имя для контейнера, в данном случае ``pmm-data``;

* ``percona/pmm-server:latest`` указывает название и версию образа, на основе которого создаётся контейнер.

.. note:: Этот контейнер запускать не нужно, он существует для сохранения данных мониторинга в случае, например, обновления 
   образа PMM-Server. Не удаляйте и не пересоздавайте контейнер, если вы не намереваетесь начать мониторинг сначала, 
   обнулив данные.

Следующая команда создаёт и запускает контейнер PMM-Server:

.. code-block:: bash

    docker run -d \
    -p 8080:80 \
    --volumes-from pmm-data \
    --name pmm-server \
    --restart always \
    percona/pmm-server:latest


* опция -d запускает контейнер в фоновом режиме;

* опция -p определяет порт для доступа к PMM-Server через браузер, в примере это порт 8080;

* опция ``--volumes-from`` примонтирует тома из ранее созданного контейнера ``pmm-data``;

* опция ``--name`` задаёт имя для контейнера, в данном случае ``pmm-server``;

* опция ``--restart`` определяет политику перезапуска контейнера; ``always`` означает, что Docker запустит контейнер при запуске и в случае отключения контейнера.

* ``percona/pmm-server:latest`` указывает название и версию образа, на основе которого создаётся контейнер.


После этого в браузере по адресу ``http://host:8080`` должна быть доступна стартовая страница 
Percona Monitoring and Management:

.. figure:: ../_static/img/server_start.png

	Стартовая страница PMM

Более подробные инструкции по работе с PMM-Server можно найти на `официальном сайте Percona <https://www.percona.com/doc/percona-monitoring-and-management/deploy/server/docker.html>`_.

В коробочную версию PMM-Server нужно импортировать необходимые дашборды для мониторинга: JBoss_,
nginx_, Cassandra_, Elasticsearch_.


.. _JBoss: ../_static/JBoss.json
.. _nginx: ../_static/Nginx.json
.. _Cassandra: ../_static/Cassandra.json
.. _Elasticsearch: ../_static/ElasticSearch.json

Для импорта нужно нажать название текущего дашборда в левом верхнем углу и выбрать пункт Import dashboard:

.. figure:: ../_static/img/import_dashboard.png

	Импорт дашборда

В открывшемся окне нажать Upload .json File, выбрать нужный дашборд и указать источником данных Prometheus, 
затем нажать ``Import``:

.. figure:: ../_static/img/import_json.png

	Выбор json-файла


Установка клиента на сервер Synergy
-----------------------------------

Для установки пакета arta-synergy-health-monitoring нужно добавить в ``/etc/apt/sources.list`` следующую строку:

``deb [allow-insecure=yes] http://deb.arta.kz/tengri          shm         main contrib non-free``

Затем обновить список пакетов и установить нужный пакет:

``aptitude update``

``aptitude install arta-synergy-health-monitoring``


Настройка мониторинга на сервере Synergy
----------------------------------------

PMM-Server должен быть доступен с сервера Synergy, это можно проверить, например, командой ``ping``.

В первую очередь нужно установить соединение между сервером Synergy и PMM-Server.
Для этого используется консольная команда: 

``pmm-admin config --server=server[:port]``

Если соединение успешно установилось, в консоли должен появиться подобный вывод:

.. code-block:: bash 

    root@client:~# pmm-admin config --server=192.168.2.234:8080
    OK, PMM server is alive.
    
    PMM Server      | 192.168.2.234:8080 
    Client Name     | client
    Client Address  | 192.168.2.84


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

Основные команды pmm-admin
~~~~~~~~~~~~~~~~~~~~~~~~~~

Возможные команды, настройки и флаги pmm-admin можно посмотреть, выполнив в терминале ``pmm-admin --help``.

Для просмотра списка и состояния наблюдаемых сервисов используется команда ``pmm-admin list``.

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

``pmm-admin add external:services job_name [instance] --service-port=port [flags]``, 
где нужно указать имя задания для Prometheus, порт, используемый экспортером, и при необходимости название инстанса.

Инстанс нужно указывать, если настраивается мониторинг одновременно JBoss/ Wildfly и Cassandra, а также при добавлении нескольких нод одного сервиса, собранных в кластер.

Кроме того, можно добавить инстанс к уже существующему заданию Prometheus. Если, к примеру, позже была подключена ещё одна нода какого-либо сервиса и для неё также установлен пакет SHM, используется следующая команда:

``pmm-admin add external:instances job_name [host1:port1[=instance1]] [host2:port2[=instance2]] ... [flags]``

Например, настроен мониторинг одного экземпляра Elasticsearch:

.. code-block:: bash

    root@hamming:~# pmm-admin list
    pmm-admin 1.17.1

    PMM Server      | 192.168.2.234:8080 
    Client Name     | hamming
    . . . . .                                                                                   
    Job name  Scrape interval  Scrape timeout  Metrics path  Scheme  Target              Labels              Health
    elastic   1m0s             10s             /metrics      http    192.168.2.198:9114  instance="node1"    UP

Команда для добавления ноды может выглядеть так:

``pmm-admin add external:instances elastic 192.168.2.181:9114=node2``

Добавленная нода в списке:

.. code-block:: bash

    root@hamming:~# pmm-admin list
    pmm-admin 1.17.1

    PMM Server      | 192.168.2.234:8080 
    Client Name     | hamming
    . . . . .                                                                                   
    Job name  Scrape interval  Scrape timeout  Metrics path  Scheme  Target              Labels              Health
    elastic   1m0s             10s             /metrics      http    192.168.2.198:9114  instance="node1"    UP
    elastic   1m0s             10s             /metrics      http    192.168.2.181:9114  instance="node2"    UP

На соответствующем дашборде можно будет выбрать нужную ноду в параметре ``Instance``:

.. figure:: ../_static/img/nodes.png

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

``pmm-admin remove external:service job_name --service-port=port [flags]``

Например, для Elasticsearch:

``pmm-admin remove external:service elastic --service-port=9114``

Для удаления отдельного инстанса:

``pmm-admin remove external:instances job_name [host1:port1] [host2:port2] ... [flags]``

.. note::
   Удаляются только задания для инстанса, на котором выполнена команда. Чтобы удалить задания для других инстансов, нужно выполнять аналогичные команды на них.

Мониторинг Linux и MySQL
~~~~~~~~~~~~~~~~~~~~~~~~

Для мониторинга операционной системы и MySQL в консоли нужно выполнить команду, используя 
логин и пароль пользователя для mysql:

``pmm-admin add mysql --user root --password root``

Если мониторинг этих сервисов успешно добавился, команда ``pmm-admin list`` должна показать подобный список:

.. code-block:: bash

    root@client:~# pmm-admin list
    pmm-admin 1.17.1
    
    PMM Server      | 192.168.2.234:8080 
    Client Name     | client
    Client Address  | 192.168.2.84 
    Service Manager | linux-systemd
    
    -------------- ------- ----------- -------- ------------------------------------------- --------------------------------------------------------------------------------------
    SERVICE TYPE   NAME    LOCAL PORT  RUNNING  DATA SOURCE                                 OPTIONS                                                                               
    -------------- ------- ----------- -------- ------------------------------------------- --------------------------------------------------------------------------------------
    mysql:queries  client  -           YES      root:***@unix(/var/run/mysqld/mysqld.sock)  query_source=slowlog, query_examples=true, slow_log_rotation=true, retain_slow_logs=1 
    linux:metrics  client  42000       YES      -                                                                                                                                 
    mysql:metrics  client  42002       YES      root:***@unix(/var/run/mysqld/mysqld.sock)
    

Мониторинг JBoss/Wildfly
~~~~~~~~~~~~~~~~~~~~~~~~

Для мониторинга JBoss/Wildfly нужно добавить следующие строки в ``/opt/synergy/jboss/bin/standalone.conf``:

.. code-block:: bash 

    JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:/opt/synergy/jboss/modules/system/layers/base/org/wildfly/common/main/wildfly-common-1.4.0.Final.jar"
    JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:/opt/synergy/jboss/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-2.1.4.Final.jar"
    JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,org.jboss.logmanager"
    JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
    JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/synergy/jboss/standalone/lib/ext/jmx_prometheus_javaagent.jar=58080:/opt/synergy/jboss/standalone/configuration/jboss.yaml"


Затем сделать доступной статистику источников данных, добавив ``statistics-enabled="true"`` 
для ``SynergyDS`` и ``StorageDS`` в ``/opt/synergy/jboss/standalone/configuration/standalone-onesynergy.xml``:


.. code-block:: xml 

                <xa-datasource jndi-name="java:/SynergyDS" pool-name="synergy_ds" enabled="true" use-ccm="false" statistics-enabled="true">
                    <xa-datasource-property name="URL">
                        jdbc:mysql://127.0.0.1:3306/synergy?useUnicode=true&amp;characterEncoding=utf8
                    . . . . . .
                </xa-datasource>


...

.. code-block:: xml 

                <xa-datasource jndi-name="java:/StorageDS" pool-name="storage_ds" enabled="true" use-ccm="false" statistics-enabled="true">
                    <xa-datasource-property name="URL">
                        jdbc:mysql://127.0.0.1:3306/storage?useUnicode=true&amp;characterEncoding=utf8
                    . . . . . .
                </xa-datasource>


После этого нужно перезапустить JBoss/Wildfly.

По умолчанию конфигурационный файл ``jboss.yaml`` и экспортер метрик ``jmx_prometheus_javaagent.jar`` 
находятся в вышеуказанном расположении. Если вы перемещаете их, укажите новый путь в ``standalone.conf``. 
Здесь также можно указать другой порт для передачи метрик.

Собираемые метрики доступны для просмотра в браузере по адресу ``http://server:58080/metrics``. Если в ``standalone.conf`` 
используется другой порт, в адресной строке нужно указывать его.

Далее следует добавить мониторинг JBoss/Wildfly в PMM-Server, в общем случае команда выглядит так:

``pmm-admin add external:service --service-port=58080 jboss testserver-jboss``, где

* jboss - имя задания для Prometheus;

* testserver-jboss - название инстанса. Так как аналогичный экспортер используется и для Cassandra, нужно указать название явно, чтобы метрики JBoss/Wildfly и Cassandra не смешивались на графиках. Кроме того, нужно указывать инстансы в случаях, когда используется несколько экземпляров.


Мониторинг nginx
~~~~~~~~~~~~~~~~

Для мониторинга nginx нужно добавить следующие строки в ``/etc/nginx/nginx.conf`` в секцию ``Logging settings``:

.. code-block:: bash 

	log_format shm '$remote_addr - $remote_user [$time_local] '
                                '"$request" $status $body_bytes_sent '
                                '"$http_referer" "$http_user_agent" '
                                '$request_time $hostname';


Далее в файле ``/etc/nginx/sites-enabled/synergy-base`` в разделе ``location /Synergy`` добавить 
в описание лога ``synergy.access.log`` определённый шагом ранее формат, в данном случае ``shm``:


.. code-block:: bash 

    location /Synergy {
        proxy_pass              http://127.0.0.1:8080/Synergy;
	...
        access_log /var/log/nginx/synergy.access.log shm;
    }


Чтобы изменения вступили в силу, нужно перезапустить nginx:

``/etc/init.d/nginx restart``

В конфигурационном файле ``/etc/prometheus-nginxlog-exporter.hcl`` нужно указать параметры ``app`` и
``instance``, также можно назначить другой порт (по умолчанию 4040):

.. code-block:: bash

    listen {
      port = 4040
      address = "0.0.0.0"
    }
    
    namespace "synergy" {
      format = "$remote_addr - $remote_user [$time_local] \"$request\" $status $body_bytes_sent \"$http_referer\" \"$http_user_agent\" $request_time $hostname"
      source_files = [
        "/var/log/nginx/synergy.access.log"
      ]
      labels {
        app = "nginx284"
        instance = "testserver-nginx"
        }
    
      histogram_buckets = [.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10]
    }


Запустить мониторинг запросов nginx:

``systemctl start prometheus-nginxlog-exporter.service``

Собираемые метрики доступны для просмотра в браузере по адресу ``http://server:4040/metrics``. 

Далее следует добавить мониторинг nginx в PMM-Server, в общем случае команда выглядит так:

``pmm-admin add external:service --service-port=4040 nginx testserver-nginx --interval 10s``

Параметр ``--interval`` указывает интервал сбора метрик в PMM-Server, для экспортера nginx лучше 
указать интервал меньше, чем интервал по умолчанию, который равен 1 минуте.


Мониторинг Cassandra
~~~~~~~~~~~~~~~~~~~~

Для мониторинга Cassandra нужно добавить в ``/etc/cassandra/cassandra-env.sh`` строку:

``JVM_OPTS="$JVM_OPTS -javaagent:/usr/share/cassandra/lib/jmx_prometheus_javaagent.jar=7070:/etc/cassandra.yaml"``

Затем закомментировать в ``/etc/init.d/cassandra`` строки:

.. code-block:: bash 

    # Read Cassandra environment file.
    #. /etc/cassandra/cassandra-env.sh
    
    #if [ -z "$JVM_OPTS" ]; then
    #    echo "Initialization failed; \$JVM_OPTS not set!" >&2
    #    exit 3
    #fi


Выполнить обновление конфигов ``systemd``:

``systemctl daemon-reload``

Перезапустить Cassandra:

``/etc/init.d/cassandra restart``

По умолчанию конфигурационный файл ``cassandra.yaml`` и экспортер метрик ``jmx_prometheus_javaagent.jar`` 
находятся в вышеуказанном расположении. Если вы перемещаете их, укажите новый путь в ``cassandra-env.sh``. 
Здесь также можно указать другой порт для мониторинга.

Собираемые метрики доступны для просмотра в браузере по адресу ``http://server:7070/metrics``. Если в ``cassandra-env.sh`` 
используется другой порт, в адресной строке нужно указывать его.

Далее следует добавить мониторинг Cassandra в PMM-Server, в общем случае команда выглядит так:

``pmm-admin add external:service --service-port=7070 cassandra testserver-cassandra``

Так как аналогичный экспортер используется и для JBoss/Wildfly, нужно указать явно название инстанса
(в данном случае testserver-cassandra), чтобы метрики JBoss/Wildfly и Cassandra не смешивались на графиках.
Кроме того, нужно указывать инстансы в случаях, когда используется кластер из нескольких нод Cassandra.

Мониторинг Elasticsearch
~~~~~~~~~~~~~~~~~~~~~~~~

Запуск сбора метрик Elasticsearch осуществляется с помощью команды:

``systemctl start prometheus-elasticsearch-exporter.service``

Добавление мониторинга в PMM-Server:

``pmm-admin add external:service --service-port=9114 elastic``
