$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 ~~~~~~~~~~~~~~~~~~~ Файл содержит блок определений ... с определеними для отправки отчета по электронной почте. Названия директив соответствуют полям протокола 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.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.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 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 Пример демонстрирует использование секции конфигурации в качестве источника данных для выполнения запросов. Помимо этого в секцию можно добавлять данные необходимые для агента, кукесов и дополнительных заголовков. checkit ~~~~~~~ Это один из сложнейших обработчиков системы, но в тоже время один из самых простых для понимания пользователем. Обработчик пробегается по списку счетчиков и проверяет их. Счетчики всегда возвращают данные либо OK либо ERROR и ничего лишнего. В качестве источника данных может быть база данных или результат на простой запрос HTTP. Помимо этого поддерживаются счетчики выполняющие SHELL команду. monm checkit Пример позволяет выполнить работу над всеми найденными счетчиками. monm checkit www.example.com Этот же пример показывает как можно отработать только один счетчик с именем www.example.com По изменению статуса любого счетчика срабатывают триггеры, например, отправка сообщения E-Mail или SMS. Также есть возможность выполнить любую команду в текущей системе (там, где установлен пакет App::MonM). Ниже пример описыающий самый простой счетчик и триггеры: Enable yes URL http://www.example.com Target code IsTrue 200 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" 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 для передачи от конечных источников данных агенту. +5m OK|ERROR ... Формат XML для передачи от агента серверу. ALERTGRID_NAME Wed, 05 Mar 2014 09:50:04 GMT Wed, 05 Mar 2014 09:50:14 GMT [25059] {TimeStamp: +0.9428 sec} OK|ERROR ... Имя формируется так: :::: Например: 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__