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

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

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

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

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


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

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

PMM-Server рекомендуется устанавливать на отдельном сервере. Для его работы требуется 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


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

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


Мониторинг 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
~~~~~~~~~~~~~~~~~~~~~~~~

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

.. code-block:: bash 

    JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:/opt/synergy/jboss/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-2.0.9.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"


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

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

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

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

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

* testserver-jboss - название инстанса. Так как аналогичный экспортер используется и для Cassandra, нужно указать название явно, чтобы метрики JBoss и 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, нужно указать явно название инстанса
(в данном случае testserver-cassandra), чтобы метрики JBoss и Cassandra не смешивались на графиках.

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

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

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

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

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