$Id: README 52 2015-06-30 12:03:13Z abalama $
App::MonM v1.05 and later  
This document written in cp-866 (OEM) charset
=============================================

КОРОТКО О ПРОЕКТЕ
-----------------

App::MonM - набор инструментов для простого мониторинга работы основных WEB-сервисов (сайтов, баз 
данных, интерфейсов и т.д.).

ВОЗМОЖНОСТИ
-----------

    - Проверка доступности веб-сайтов (checkit http)
    - Проверка работоспособности различных баз данных (checkit dbi)
    - Проверка внешних счетчиков посредством выполнения системных команд (checkit command)
    - Проверка доступности серверов SMTP, POP3, FTP, SSH и др. (checkers)
    - Выполнение отладочных запросов SQL (dbi)
    - Выполнение отладочных запросов HTTP (http)
    - Интерфейс для SMS информинга (sendalertsms)
    - Механизм сбора и хранения статистических данных от различных источников (alertgrid)
    - Отрисовка (построение) графиков по данным собранным с помощью AlertGrid (rrd)
    - Быстрая настройка путем простого редактирования конфигурационных файлов
    - Установка проекта средствами CPAN или в ручном режиме через make install
    - Возможность интегрирования проекта в WEB интерфейсы

ЗАВИСИМОСТИ
-----------

Перед началом установки, Вам необходимо проверить наличие следующих пакетов, установленных в Вашей
системе где будет "работать" App::MonM:

    - gcc последней версии
    - perl v5.10 или выше (рекомендуется не ниже v5.12)
    - libwww (p5-libwww / perl-libwww)
    - libnet

Помимо этого, некоторые компоненты App::MonM требуют наличие WEB сервера Apache 2.2
или выше. Сервер должен быть настроен на выполнение CGI (perl) скриптов. Также должны быть
установлены пакеты:

    - Net-SNMP (net-snmp + net-snmp-perl)
    - RRDtool (rrdtool + rrdtool-perl)

УСТАНОВКА
---------

Установка выполняется двумя путями. Первый - автоматизированный; второй - ручной.

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

    # cpan install App::MonM

или (для ActivePerl):

    # ppm install App-MonM

В ручном режиме Вам потребуется выполнить следующий набор операций:

    - Скачать дистрибутив с CPAN или официальный релиз с сайта SourceForge:
    
      https://metacpan.org/pod/App::MonM
      http://search.cpan.org/~abalama/
      https://sourceforge.net/projects/app-monm/
    
    - Разархивировать полученный архив, и перейти в извлеченную папку с помощью консоли
    
    - Находясь в извлеченной папке выполнить последовательно следующие команды:
    
      perl Makefile.PL
      make
      make test
      make install
    
В процессе установки система предложит установить необходимые модули (пакеты), зависимых модулей
не так много и большая их часть уже установлена на Вашей системе.

ИНИЦИАЛИЗАЦИЯ
-------------

Процесс инициализации активирует работу приложение monm (далее просто monm). Это приложение
является интерфейсом системной оболочки и предоставляет доступ к функциональным 
возможностям модуля App::MonM.

В процессе инициализации будут созданы необходимые директории и конфигурационные файлы.

Для инициализации следует выполнить следующую команду:

    # monm config

Если Вы желаете устанавливать конфигурационные файлы в свой каталог, то следует запустить 
инициализатор с ключем -c DIRECTORY/monm.conf:

    # monm -c /my/config/files/monm.conf config

Данная инструкция "развернет" конфигурационные файлы в каталоге /my/config/files

КОНФИГУРАЦИЯ
------------

Большое внимание следует уделить конфигурации. Именно правильное настроенное приложение гарантирует
корректную работу всего приложения.

В процессе инициализации Вам был показан на экране консоли путь, по которому расположены
конфигурационные файлы. Этот конфигурационный каталог содержит по умолчанию файлы: 

    conf.d/alertgrid.conf.sample
    conf.d/checkit-foo.conf
    conf.d/checkit-foo.conf.sample
    conf.d/dbi-foo.conf.sample
    conf.d/http-foo.conf.sample
    conf.d/rrd.conf.sample
    extra/sendmail.conf
    extra/checkit.conf
    monm.conf

Главным конфигурационным файлом является файл monm.conf. Он содержит глобальные определения и 
определяет какие дополнительные файлы будут прочитаны и использоваться. Файл extra/sendmail.conf
содержит определения для отправки электронной почты по умолчанию. Файл extra/checkit.conf
служит для определений используемых в своей работе обработчиком checkit. Каталога conf.d
содержит файлы описывающие секции для работы всех обработчиков, например dbi, checkit, http

monm.conf
~~~~~~~~~~~~

Как уже упоминалось выше, файл monm.conf содержит глобальные определения.

    LogEnable   on
    LogEnable   off

Директива позволяет включить или выключить логирование процессов monm. По умолчанию - off

    LogLevel warning

Директива определяет уровень отладки. Существует следующий набор уровней отладки: debug, info, 
notice, warning, error, crit, alert, emerg, fatal, except. По умолчанию используется значение debug

Всю отладочную информацию monm записывает в файл monm.log системного каталога журнальных 
файлов, например: /var/log/monm.log

В случае запуска программы monm с параметром -l помимо файла monm.log будет записываться файл 
системного лога - monm_debug.log. Данный файл нужен для детальной отладки работы зависимых 
компонентов App::MonM.

extra/sendmail.conf
~~~~~~~~~~~~~~~~~~~

Файл содержит блок определений <SendMail>...</SendMail> с определеними для отправки отчета
по электронной почте. Названия директив соответствуют полям протокола SMTP, за исключением 
следующих полей:

    Sendmail   /usr/sbin/sendmail
    Flags      -t

Директива Sendmail определяет альтернативное SMTP приложение, отправлющее письмо. Запуск приложения
проходит с ключом -t, определенного директивной Flags

    SMTP       192.168.0.1
    SMTPuser   user
    SMTPpass   password

Данные директивы определяют параметры соединения с SMTP сервером для отправки сообщения. Параметр
SMTPuser и SMTPpass необязательны.

НАЧАЛО РАБОТЫ
-------------

После успешной работы по установке, инициализации и настройке - переходим к первому запуску программы
monm. Для уточнений синтаксиса всегда можно воспользоваться командой:

    # monm -h

Общий синтаксис команды monm таков:

    # monm [OPTIONS] [COMMANDS [ARGS]]

Существует ряд ключевых опций команды:

    -D DATADIR

Данная опция (ключ) определяет локальную папку, в которую будут помещаться временные файлы, 
необходимые для работы. По умолчанию используется системный каталог временных файлов.

    -c CONFFILE
    --config=CONFFILE

Ключ заставляет программу использовать в качестве конфигурационного файла CONFFILE. По умолчанию 
используется системный путь к файлу monm.conf.

    -v

Ключ позволяет видеть на экране результат работы программы mbutiny. Для более детальной информации
можно воспользоваться дополнительным ключем -d.

КОМАНДЫ И АРГУМЕНТЫ
-------------------

Программа monm поддерживает следующие команды

test
~~~~

Тестирование всех основных компонентов программы. После тестирование возвращается набор данных, 
таких как: переменные окружений, конфигурационные данные, список подключенных директорий библиотек

Данная команда не требует никаких аргументов

void
~~~~

Пустой контекст, программа запускается и ничего не делает. Возвращает "пустой" ответ

Данная команда не требует никаких аргументов

dbi
~~~

Тестирование работы различных баз данных используя интерфейс DBI и выполнение указанной команды. 
Ниже примеры использования

    monm dbi -d -F text -s TEST -u USER -p PASSWORD --sql="select sysdate from dual"

Этот пример демонстрирует то как работает простой запрос (select sysdate from dual) в БД Oracle. Для
соединения используются данные SID (ключ -s), логин и пароль (ключи -u и -p).

    echo select sysdate from dual | monm -d --stdin -F text -s TEST -u USER -p PASSWORD

Этот пример аналогичен предыдущиму за исключением того что в качестве SQL используется не аргумент
командной строки а стандартный ввод.

    monm dbi -d -F text -s TEST -u USER -p PASSWORD

Этот пример аналогичен первому, но в качестве SQL запроса выступает запрос по умолчанию. Для БД
Oracle запрос используется как: SELECT SYSDATE FROM DUAL

    monm dbi -d -F xml -s TEST -u USER -p PASSWORD -o oracle.xml

Этот запрос аналогичен предыдущему только результативный XML документ записывается в файл. Если 
опустить ключ -d и -F то результативный XML документ будет выведен в стандартный вывод, в частности, 
на экран. Примером стандартного XML см. раздел "API"

    monm dbi -d -F yml --sid=TEST -u USER -p PASSWORD -T 10

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

    monm dbi -d foo

Пример основывается на метаопределении foo. Метопределение foo описывается секцией конфигураций 
<DBI foo>. Описание полей см. в конфигурационном файле dbi-foo.conf.sample. Данный подход 
"облегчает" работу с командной строкой вынося большинство необходимых аргументов в конфигурационный 
файл.

    monm dbi -dF text -s TEST -u USER -p PASSWORD 
       --sql="select rownum from dual connect by level <= 5"

Пример позвояющий увидеть простую табличку возвращаемую Oracle

    monm dbi -d -n DBI:mysql:database=MYBASE;host=www.example.com -u LOGIN -p PASSWORD

Тестирование работы указанной базы данных и выполнение указанной команды. Данная команда практически
полностью идентична предыдущим за исключением того что ключ -s (--sid) заменен ключом -n (--dsn) 
куда следует передавать DSN в явном виде.

http
~~~~

Тестирование работы URL запроса. Работа команды основывается на вызове LWP с богатым выбором опций, 
список которых приведен в секции конфигурации <HTTP foo>. 
Описание полей см. в конфигурационном файле http-foo.conf.sample. Данный подход "облегчает" работу 
с командной строкой вынося большинство необходимых аргументов в конфигурационный файл.

Здесь же стоит привести несколько типовых примеров работы с командной строкой.

    monm http -d -q http://www.example.com

Этот пример позволяет получить информацию о запрашиваемом контенте и вывести ее на экран.

    monm http -q http://www.example.com

Этот пример идентичен предыдущему, но на экран выводится информация в формате TXT

    monm http -q http://www.example.com -F xml

Этот пример позволит увидеть на экране и само содержимое ресурса http://www.example.com в секции
XML <result></result>

    monm http -q http://www.example.com -u LOGIN -p PASSWORD
    monm http -q http://LOGIN:PASSWORD@www.example.com

Примеры позволяют получить доступ к ресурсу требующему авторизацию HTTP

    monm http -q http://www.example.com -m POST --request="foo=1&bar=2"

Этот пример демонстрирует как можно передавать данные методом POST

    monm http -q http://www.example.com -f file.txt -T 20

Этот пример показывает как можно помещать "скаченный" контент в файл file.txt. Помимо этого ключ -T 
определяет таймаут запроса

    echo foo=123 | monm http --stdin -m POST -q http://www.example.com

Пример демонстрирует как передать данные для POST запроса с помощью стандартного входного канала

    monm http foo

Пример демонстрирует использование секции конфигурации <HTTP foo> в качестве источника данных для
выполнения запросов. Помимо этого в секцию можно добавлять данные необходимые для агента, кукесов и
дополнительных заголовков.

checkit
~~~~~~~

Это один из сложнейших обработчиков системы, но в тоже время один из самых простых для понимания 
пользователем. Обработчик пробегается по списку счетчиков и проверяет их. Счетчики всегда возвращают
данные либо OK либо ERROR и ничего лишнего. В качестве источника данных может быть база данных или
результат на простой запрос HTTP. Помимо этого поддерживаются счетчики выполняющие SHELL команду.

    monm checkit

Пример позволяет выполнить работу над всеми найденными счетчиками.

    monm checkit www.example.com

Этот же пример показывает как можно отработать только один счетчик с именем www.example.com

По изменению статуса любого счетчика срабатывают триггеры, например, отправка сообщения E-Mail или 
SMS. Также есть возможность выполнить любую команду в текущей системе (там, где установлен 
пакет App::MonM).

Ниже пример описыающий самый простой счетчик и триггеры:

    <Checkit "foo">
        Enable      yes
        URL         http://www.example.com
        Target      code
        IsTrue      200
        
        <Triggers>
            emailalert  foo@example.com
            emailalert  bar@example.com
            emailalert  baz@example.com

            smsalert    11231230001
            smsalert    11231230002
            smsalert    11231230003

            # Список команд, которые будут выполнены по срабатыванию триггера
            # Работают подстановки:
            #   [SUBJECT] -- Тема
            #   [MESSAGE] -- Сообщение
            #command     "mycommand1 "[SUBJECT]" "[MESSAGE]""
            #command     "mycommand2 "[MESSAGE]""
            #command     "mycommand3"
        </Triggers>
    </Checkit>

alertgrid
~~~~~~~~~~

Обработчик создан для предоставления возможности сбора статистических данных состояния работы
всевозможного оборудования и сервисов. Данные собранные от источников сохраняются в плоской
таблице с возможностью их чтения для последующей обработки или отображения в виде итоговой
таблицы.

Обработчик alertgrid в связке с rrd обеспечивают отличный способ наглядного отображения собранных
данных в виде графиков. Более подробно о связке alertgrid и rrd см. в разделе ALERTGRID AND RRD.

Рассмотрим работу основных операций AlertGrid на примерах.

    monm alertgrid init

Команда позволит инициализировать базу данных alertgrid.

    monm alertgrid agent

Команда позволяет пройтись по всем счетчикам и забрать данные сохранив их в базе данных alertgrid

    monm alertgrid export -F xml
    monm alertgrid export -F xml -o index.xml

Команда позволяет выполнить экспорт данных в виде XML документа на стандартный вывод. Когда как
вторая команда выводит данные в файл test.xml. Следует заметить, что при выставлении параметра
конфигурационного файла alertgrid.conf - AlertGrid/Agent/TransferType в значение равное http
данные экспорта будут забираться из указанного URI секции AlertGrid/Agent/HTTP.

    monm alertgrid snapshot
    monm alertgrid snapshot -o index.txt

Данные команды идентичны export за исключением формата вывода. Структура выводимого документа будет
адаптирована для генерации HTML документов или текстовых документов.

    monm alertgrid config

Команда позволяет получить основные конфигурационные данные alertGrid на локальной машине. Данную команду
полезно использовать для связки с другими приложениями

rrd
~~~

Обработчик позволяет выполнять построение графиков по данных собранным с помощью 
AlertGrid (см. выше). Более подробно о связке alertgrid и rrd см. в разделе ALERTGRID AND RRD.

Рассмотрим работу основных операций RRD на примерах.

    monm rrd init

Команда позволит инициализировать базы RRDtool

    monm alertgrid export -F xml | monm rrd update -I

Команда позволяет сделать выгрузку AlertGrid и передать данные механизму RRD для последующего
обновления баз RRD.

    monm alertgrid export -F xml -o alertgrid.xml
    monm rrd update -i alertgrid.xml

Аналогичный пример, отличае состоит в том что используется промежуточный документ alertgrid.xml

    monm rrd graph

Команда позволяет отрисовать данные на графиках - построить их

    monm rrd index

Команда позволяет сформировать индексный файл для отображения построенных
графиков в браузере

ALERTGRID AND RRD
-----------------

Обработчик alertgrid в связке с rrd позволяют строить графики по данным, полученным
от различных источников (счетчиков).

Задача построения графиков сводится к сбору данных, их накоплению и
их отображению в виде графиков. Эти процессы имеют распределенную клиент/сервер 
систему, где одни компьютеры выполняют функцию агентов, другие выполняют функцию 
источников данных, а третьи - функцию сервера. Рассмотрим пример

         +-----+
         | PC2 |
         +--+--+
 +-----+    |    +-----+
 | PC1 +--+ | +--+ PC3 |
 +-----+  | | |  +-----+
          | | |
    inet ~~~~~~~
          | | |
       +--+-+-+--+ 
       | AGENT_1 | 
       +----+----+   +---------+
            | +------+ AGENT_2 |
            | |      +---------+
      inet ~~~~~
            | | 
        +---+-+--+
        | SERVER | 
        +---+----+

Общая схема работы. Сервер (SERVER) принимает собранные данные от агентов (AGENT_1 и AGENT_2). 
AGENT_1 собирает данные от себя самого (если это требуется) и от компьютеров-источников 
(PC1, PC2 и PC3). AGENT_2 собирает данные только от самого себя. Все данные до агента и сервера 
передаются через сеть internet/intranet, это позволяет миновать многие трудности.

PC1, PC2, PC3 - это конечные узлы, источники данных (компьютеры, сервера, маршрутизаторы, 
коммутаторы и др.) на которых установлено соответствующее программное обеспечение для сборки 
данных счетчиков. В качестве такого ПО может выступать Net-SNMP сервер.

AGENT_1 и AGENT_2 - это компьютеры, с установленной системой MonM в связке с ПО призванным
собирать данные от источников. Примером такого ПО может выступать Net-SNMP клиент.
Собранные данные передаются в активном режиме на SERVER. Отправка данных может осуществляться,
например, посредством планировщика задач cron, или его аналогов. Помимо этого могут быть 
использованы и другие способы систематического опроса источников данных.

SERVER - это более мощное оборудование, с установленным WEB-сервером Apache и системой MonM.
Сервер выполняет задачи приема данных от агентов, сохранения их в базе данных, а также 
выполняет функции построения графиков, используя при этом систему RRDtool.

Данные на сервере собираются от агентов в виде единой таблицы SQLite путем их постоянного 
обновления. Затем, все собранные данные запрашиваются и передаются в распределенную 
базу RRD, где для каждого графика свой набор данных собирается в отдельные локальные БД RRDtool. 
В момент обновления данных в RRD базах данных происходит автоматическое построение графиков. 
Более подробно о цикле см. ALERTGRID AND RRD WORK CYCLE и файл monm_agrrd.sh

ALERTGRID AND RRD WORK CYCLE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

while not the end of the universe
    do
      get result of
         monm alertgrid export
      into variable $in

      echo $in | monm rrd update -I -o /dev/null

      # Creating graphs
      monm rrd graph -o /dev/null

      wait for 5 minutes
    done

Typical example of use:

    # Run local agent
    monm alertgrid agent -o /dev/null

    # Export data from alertgrid database into rrd database 
    monm alertgrid export | monm rrd update -I -o /dev/null

    # Creating graphs
    monm rrd graph -o /dev/null

API
---

Общие правила передачи данных между процессами нашли применение и в частных случаях,
таких, например, как передача данных между сабпроцессами обработчиков.

Передача даннх alertgrid
~~~~~~~~~~~~~~~~~~~~~~~~

Формат XML для передачи от конечных источников данных агенту.

<response>
    <count name="COUNT_NAME">
        <expires>+5m</expires>
        <status>OK|ERROR</status>
        <error code="0"><![CDATA[MESSAGE]]></error>
        <value type="DIG|STR|TAB"><![CDATA[VALUE]]></value>
    </count>
    ...
</response>

Формат XML для передачи от агента серверу.

<alertgrid>
    <name>ALERTGRID_NAME</name>
    <count name="COUNT_NAME">
        <pubdate date="123456789">Wed, 05 Mar 2014 09:50:04 GMT</pubdate>
        <expires date="123456799">Wed, 05 Mar 2014 09:50:14 GMT</expires>
        <worktms>[25059] {TimeStamp: +0.9428 sec}</worktms>
        <status>OK|ERROR</status>
        <error code="0"><![CDATA[MESSAGE]]></error>
        <value type="DIG|STR"><![CDATA[VALUE]]></value>
    </count>
    ...
</alertgrid>

Имя формируется так:

    <IP>::<ALERTGRID_NAME>::<COUNT_NAME>

Например:

    127.0.0.1::foo::resources::hdd::used     = ...
    127.0.0.1::bar::SNMPv2-MIB::sysDescr.0   = ...

В таблицу alertgrid данные ложатся в поля по образцу:

 ID | IP | ALERTGID_NAME | COUNT_NAME | TYPE | VALUE | PUBDATE | EXPIRES | STATUS | ERRCODE | ERRMSG
----+----+---------------+------------+------+-------+---------+---------+--------+---------+--------
  1 | 127.0.0.1 |    foo | resources::hdd::used | DIG | 0 | DTS | DTF |        OK |       0 |

Замечания:
 
Если статус == "OK" то error = "" а code = 0. Если статус == "ERROR" то error = "ТЕКСТ_ПРИЧИНЫ_ОШИБКИ"
когда как code = 1 или любое иное отличное от 0. Поле pubdate -- дата публикации результата; 
expires -- дата истечения срока действия результата и в том и другом полях аттрибут date содержит 
время в формате "unix time". Поле value содержит значение счетчика. Даже при статусе ERROR значение 
учитывается.

__END__