Skip to content

Commit a0e3a66

Browse files
vbkuninvbkunin
authored
Create README.md
1 parent 9c3fb52 commit a0e3a66

File tree

1 file changed

+244
-0
lines changed

1 file changed

+244
-0
lines changed

‎README.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Модуль для интеграции iTop с системами мониторинга
2+
3+
Что умеет модуль:
4+
5+
1. создавать инциденты при возникновении аварий, назначать команду и агента;
6+
1. привязывать аварийные конфигурационные единицы к инцидентам;
7+
1. выполнять инциденты при восстановлении и возвращать в работу при повторении аварии;
8+
1. добавлять сообщения в журнал инцидента.
9+
10+
Модуль представляет собой расширение REST API iTop. Логика работы модуля полностью настраиваемая, правила обработки событий определяются в конфигурационном файле. Для различных групп мониторинга можно настроить разные правила обработки событий.
11+
12+
## Общие сведения
13+
14+
Модуль добавляет в [HTTP API iTop](https://www.itophub.io/wiki/page?id=2_6_0%3Aadvancedtopics%3Arest_json) новый метод, с помощью которого можно выполнить несколько действий одним HTTP-запросом из системы мониторинга, например создать инцидент, привязать КЕ, назначить на нужного агента и написать сообщение в журнал.
15+
16+
Основные задачи модуля:
17+
- упростить настройку и поддержку систем мониторинга в части отправки событий в iTop;
18+
- свести к минимуму количество разнообразных скриптов для отправки запросов;
19+
- вернуть все специфичные данные из скриптов обратно в iTop (услуги, команды, агенты и т.п.).
20+
21+
## Установка
22+
23+
Установка выполняется по стандартной процедуре. Модуль не изменяет модель данных iTop и после тестирования может быть удален из системы без негативных последствий.
24+
25+
### Требования
26+
27+
PHP 7, iTop 2.6 и выше (на более ранних версиях iTop работа не проверялась), модули Simple Ticket Management или Incident Management.
28+
29+
## Передача информации о событии мониторинга в iTop
30+
31+
Пример запроса (что нужно передать в параметре `json_data`):
32+
33+
```json
34+
{
35+
"operation": "monitoring/alarm",
36+
"comment": "Наш Zabbix",
37+
"context": "zabbix_servers",
38+
"ci_key": "Server2 (Grenoble)",
39+
"state": true,
40+
"message": "PROBLEM: host Server2 (Grenoble) unavailable",
41+
"output_fields": "ref,title,status,team_id_friendlyname,agent_id_friendlyname,functionalcis_list"
42+
}
43+
```
44+
45+
В зависимости от настроек модуля данный запрос может приводить к различным действиям в iTop.
46+
47+
### Параметры запроса
48+
49+
#### operation
50+
Значение `monitoring/alarm` – единственная доступная в настоящее время операция.
51+
52+
#### comment
53+
Комментарий, который будет указан в истории создаваемого/изменяемого тикета.
54+
55+
#### context
56+
Название контекста обработки события мониторинга, в котором задаются правила обработки (см. параметры модуля).
57+
58+
#### ci_key
59+
Идентификатор, который будет использоваться для поиска соответствующей КЕ в iTop.
60+
61+
#### state
62+
Состояние события мониторинга: `true` или `1` – авария началась, `false` или `0` – авария закончилась.
63+
64+
#### message
65+
Текстовое сообщение события мониторинга.
66+
67+
#### output_fields
68+
Атрибуты тикета, которые нужно вернуть в ответе на HTTP-запрос (см. [описание стандартного API iTop](https://www.itophub.io/wiki/page?id=2_6_0%3Aadvancedtopics%3Arest_json#response)).
69+
70+
## Настройка модуля
71+
72+
При поступлении HTTP-запроса айтоп последовательно:
73+
1. с помощью `ci_oql` ищет КЕ, которая сгенерировала событие мониторинга;
74+
2. с помощью `ticket_oql` ищет тикет, относящийся к данному событию;
75+
3. выполняет определенные действия (создать, назначить, написать в журнал и т.д.).
76+
77+
Блок настроек модуля разбивается на контексты обработки событий. Внутри каждого контекста задаются собственные правила обработки события.
78+
79+
Пример конфигурации модуля с одним контекстом `zabbix_servers`:
80+
81+
```php
82+
'knowitop-monitoring-api' => array(
83+
'zabbix_servers' => array(
84+
'ci_oql' => 'SELECT Server WHERE name = :alarm->ci_key AND status = \'production\'',
85+
'ticket_oql' => 'SELECT UserRequest AS i JOIN lnkFunctionalCIToTicket AS lnk ON lnk.ticket_id = i.id JOIN Server AS ci ON lnk.functionalci_id = ci.id WHERE ci.name = :alarm->ci_key AND i.request_type = \'incident\' AND i.status NOT IN (\'closed\')',
86+
'actions_on_problem' => array(
87+
'create' => array(
88+
'fields' => array(
89+
'org_id' => array('name' => '$ci->org_id->name$'),
90+
'caller_id' => 'SELECT Person WHERE org_id = $ci->org_id$ AND id = 2',
91+
'title' => 'Авария: $alarm->message$',
92+
'description' => 'Авария: $alarm->message$ на КЕ $ci->name$',
93+
'service_id' => 2,
94+
),
95+
),
96+
'assign' => array(
97+
'fields' => array(
98+
'team_id' => 'SELECT Team AS t JOIN lnkContactToFunctionalCI AS lnk1 ON lnk1.contact_id = t.id JOIN Server AS ci ON lnk1.functionalci_id = ci.id WHERE ci.id = $ci->id$',
99+
'agent_id' => 10,
100+
'private_log' => 'Авария: $alarm->message$',
101+
),
102+
),
103+
'reopen',
104+
'write_to_log' => array(
105+
'log_att_code' => 'private_log',
106+
'text' => 'Появилась авария: $alarm->message$',
107+
),
108+
),
109+
'actions_on_ok' => array(
110+
'resolve' => array(
111+
'fields' => array(
112+
'resolution_code' => 'other',
113+
'solution' => 'Работа КЕ $ci->name$ восстановлена.',
114+
),
115+
),
116+
'write_to_log' => array(
117+
'log_att_code' => 'private_log',
118+
'text' => 'Завершилась авария: $alarm->message$',
119+
),
120+
),
121+
),
122+
),
123+
```
124+
125+
### Параметры контекста
126+
127+
#### ci_oql
128+
129+
OQL-запрос для поиска КЕ. Найденная КЕ будет автоматически связана с создаваемым тикетом. В запросе можно использовать следующие параметры: `alarm->ci_key`, `alarm->state`, `alarm->message`.
130+
131+
Пример: `SELECT Server WHERE name = :alarm->ci_key AND status = 'production'`.
132+
133+
#### ci_key_regexp
134+
135+
Регулярное выражение для преобразования переданного в HTTP-запросе параметра `ci_key`. Может быть полезно, если идентификатор КЕ в айтопе и в системе мониторинга совпадают частично. В регулярном выражении должна быть определена скобочная группа, совпадение с которой будет помещено в параметр `alarm->ci_key`.
136+
137+
Пример: `/(Server\\d+)/`. Если из системы мониторинга придет `My super Server2 (Grenoble)`, в `alarm->ci_key` попадёт `Server2`.
138+
139+
#### ticket_oql
140+
141+
OQL-запрос для поиска тикета. Найденный тикет будет считаться относящимся к поступившему событию мониторинга. В запросе можно использовать следующие параметры: `alarm->ci_key`, `alarm->state`, `alarm->message`, `ci->att_code` (где att_code – атрибут найденной КЕ).
142+
143+
Пример: `SELECT Incident AS i JOIN lnkFunctionalCIToTicket AS lnk ON lnk.ticket_id = i.id JOIN Server AS ci ON lnk.functionalci_id = ci.id WHERE ci.name = :alarm->ci_key AND i.status != 'closed'`.
144+
145+
#### actions_on_problem
146+
147+
Список действий, которые будут выполнены над тикетом при поступлении события начала аварии (`"state": 1`). Доступные действия: `create`, `assign`, `reopen`, `write_to_log`. См. описание действий ниже.
148+
149+
#### actions_on_ok
150+
151+
Список действий, которые будут выполнены над тикетом при поступлении события окончания аварии (`"state": 0`). Доступные действия: `resolve`, `write_to_log`. См. описание действий ниже.
152+
153+
### Действия над тикетом
154+
155+
Последовательность выполнения действий фиксированная, если какое-то из определенных действий неприменимо к тикету, оно пропускается. Например, для `actions_on_problem` заданы следующие действия `create`, `assign`, `reopen`, `write_to_log`. Если `ticket_oql` не вернул тикет, айтоп создаст новый тикет, затем назначит его и напишет сообщение в журнал. Действие `reopen` будет проигнорировано. Если `ticket_oql` вернул тикет в статусе _Выполнен_, айтоп вернет тикет в работу и напишет сообщение в журнал. Действия `create` и `assign` в данном случае будут проигнорированы.
156+
157+
#### create
158+
159+
Создать новый тикет, если запрос `ticket_oql` не нашел существующий тикет. В параметре `fields` должны быть переданы атрибуты создаваемого тикета. Внутри значений `fields` можно использовать заменители (плейсхолдеры): `$alarm->ci_key$`, `$alarm->state$`, `$alarm->message$`, `$ci->att_code$` (где att_code – атрибут найденной КЕ).
160+
161+
Пример:
162+
```php
163+
'create' => array(
164+
'fields' => array(
165+
'org_id' => array('name' => '$ci->org_id->name$'),
166+
'caller_id' => 'SELECT Person WHERE org_id = $ci->org_id$ AND id = 2',
167+
'title' => 'Авария: $alarm->message$',
168+
'description' => 'Авария: $alarm->message$ на КЕ $ci->name$',
169+
'service_id' => 2,
170+
),
171+
),
172+
```
173+
174+
#### assign
175+
176+
Назначить созданный или найденный тикет. Параметры аналогичны действию `create`, к упомянутым выше заменителям добавляется `$ticket->att_code$`, где att_code – атрибут назначаемого тикета.
177+
178+
```php
179+
'assign' => array(
180+
'fields' => array(
181+
'team_id' => 'SELECT Team AS t JOIN lnkContactToService AS lnk ON lnk.contact_id = t.id JOIN Service AS s ON lnk.service_id = s.id WHERE s.id = $ticket->service_id$',
182+
'agent_id' => 10,
183+
'private_log' => 'Авария: $alarm->message$',
184+
),
185+
),
186+
```
187+
188+
#### resolve
189+
190+
Выполнить назначенный тикет. Параметры аналогичны действию `assign`.
191+
192+
#### reopen
193+
194+
Вновь открыть выполненный тикет. Параметры аналогичны действию `assign`.
195+
196+
#### write_to_log
197+
198+
Добавить сообщение в журнал тикета. В параметрах указывается атрибут журнала (по умолчанию `private_log`) и тест сообщений (по умолчанию `$alarm->message$`). Все описанные выше заменители также доступны.
199+
200+
Пример:
201+
```php
202+
'write_to_log' => array(
203+
'log_att_code' => 'private_log',
204+
'text' => 'Авария $alarm->message$ на КЕ $ci->name$',
205+
),
206+
```
207+
208+
## Ограничения
209+
- Тикеты только Incident или UserRequest.
210+
- Каждое действие – отдельная операция обновления. Если в процессе выполнения последовательности действий происходит ошибка, откат к начальному состоянию не производится, и выполненные успешно действия не отменяются.
211+
212+
## Примеры конфигов
213+
214+
Пример POST-запроса, который должна отправить система мониторинга при возникновении аварии:
215+
```
216+
POST http://localhost:8000/webservices/rest.php?version=1.4
217+
Authorization: Basic cmVzdDpyZXN0
218+
Content-Type: application/x-www-form-urlencoded
219+
220+
json_data={
221+
"operation": "monitoring/alarm",
222+
"comment": "Monitoring System",
223+
"context": "demo_context",
224+
"ci_key": "Server4",
225+
"state": 1,
226+
"message": "Server4 is down",
227+
"output_fields": "title,status,team_id_friendlyname,agent_id_friendlyname,solution"
228+
}
229+
```
230+
Тот же запрос через cURL:
231+
```
232+
curl -X POST --location "http://localhost:8000/webservices/rest.php?version=1.4" \
233+
-H "Authorization: Basic cmVzdDpyZXN0" \
234+
-H "Content-Type: application/x-www-form-urlencoded" \
235+
-d "json_data={
236+
\"operation\": \"monitoring/alarm\",
237+
\"comment\": \"Monitoring System\",
238+
\"context\": \"demo_context\",
239+
\"ci_key\": \"Server4\",
240+
\"state\": 1,
241+
\"message\": \"Server4 is down\",
242+
\"output_fields\": \"title,status,team_id_friendlyname,agent_id_friendlyname,solution\"
243+
}"
244+
```

0 commit comments

Comments
 (0)