Skip to content

Commit 1327528

Browse files
jorikfonjorikfon
committed
Update README with full metrics, REST API v3, trunk LLD and storage monitoring
1 parent 8a0709a commit 1327528

1 file changed

Lines changed: 182 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 182 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,189 @@
1-
## ModuleZabbixAgent5
1+
# ModuleZabbixAgent5
22

3-
This module provides integration with Zabbix Agent 5 for monitoring your MikoPBX system. It allows you to configure and control the Zabbix agent, enabling you to collect and send various metrics about your PBX to a Zabbix server for monitoring and analysis.
3+
Module for integrating Zabbix Agent with MikoPBX. Collects and sends PBX metrics to a Zabbix server for monitoring.
44

5-
### Inputs
5+
## Features
66

7-
The main input for this module is the Zabbix agent configuration file, which can be modified through the web interface. This file dictates how the agent operates, including which metrics to collect, how often to collect them, and where to send the data. The module includes a default configuration file that can be used as a starting point. It is recommended to familiarize yourself with the Zabbix agent configuration options to customize the monitoring to your specific needs. The module also provides several pre-defined user parameters that can be used to collect specific metrics from Asterisk, such as the number of active calls, processed calls, active channels, and status information about SIP peers and trunks. These parameters can be used directly in your Zabbix templates.
7+
- Zabbix Agent 6.0 LTS (v6.0.44), statically linked (no external dependencies)
8+
- Supports x86_64 and ARM64 (aarch64) architectures
9+
- Web interface for editing `zabbix_agentd.conf`
10+
- Real-time service status display (running state, PID, version, port, server)
11+
- Download Zabbix template button for easy import into Zabbix server
12+
- REST API v3 with auto-discovery (PHP 8 attributes, Processor + Actions pattern)
13+
- Automatic service management (start/stop/restart)
14+
- Firewall rule for Zabbix port (default 10050)
15+
- Cron-based health check every 5 minutes
816

9-
### Outputs
17+
## Monitored metrics
1018

11-
The module outputs various metrics about your MikoPBX system to the configured Zabbix server. These metrics can include:
19+
All metrics are accessed via `asterisk[<function>]` UserParameter key.
1220

13-
* Number of active calls
14-
* Number of processed calls
15-
* Number of active channels
16-
* Status of SIP peers (active/inactive)
17-
* Status of SIP trunks (active/inactive)
18-
* Asterisk uptime
19-
* Asterisk last reload time
20-
* Asterisk version
21+
### Asterisk metrics
2122

22-
These metrics can be used to create graphs, alerts, and dashboards in your Zabbix server to monitor the health and performance of your MikoPBX system. You can leverage the pre-defined Zabbix templates provided to quickly set up basic monitoring for your PBX. Additionally, you can use the low-level discovery features of Zabbix to automatically discover and monitor new SIP peers and trunks as they are added to your system.
23-
=======
23+
| Metric | Zabbix item key |
24+
|---|---|
25+
| Active calls (Asterisk CLI) | `asterisk[callsActive]` |
26+
| Processed calls | `asterisk[callsProcessed]` |
27+
| Active channels | `asterisk[channelsActive]` |
28+
| Incoming calls (via API) | `asterisk[countInCalls]` |
29+
| Outgoing calls (via API) | `asterisk[countOutCalls]` |
30+
| Internal calls (via API) | `asterisk[countInnerCalls]` |
31+
| SIP peers (total) | `asterisk[countSipPeers]` |
32+
| SIP peers (online) | `asterisk[CountActivePeers]` |
33+
| SIP trunks (online) | `asterisk[CountActiveProviders]` |
34+
| SIP trunks (offline) | `asterisk[CountNonActiveProviders]` |
35+
| Asterisk uptime | `asterisk[statusUptime]` |
36+
| Last reload time | `asterisk[statusReload]` |
37+
| Asterisk version | `asterisk[version]` |
38+
| Asterisk status (1/0) | `asterisk[status]` |
39+
40+
### SIP trunk discovery (LLD)
41+
42+
| Metric | Zabbix item key |
43+
|---|---|
44+
| Trunk registration status | `asterisk[trunkStatus,{#TRUNKID}]` |
45+
| Incoming calls per hour | `asterisk[trunkCalls,{#TRUNKID},hour,incoming,totalCalls]` |
46+
| Outgoing calls per hour | `asterisk[trunkCalls,{#TRUNKID},hour,outgoing,totalCalls]` |
47+
| Incoming calls per day | `asterisk[trunkCalls,{#TRUNKID},day,incoming,totalCalls]` |
48+
| Outgoing calls per day | `asterisk[trunkCalls,{#TRUNKID},day,outgoing,totalCalls]` |
49+
| Answered incoming per hour | `asterisk[trunkCalls,{#TRUNKID},hour,incoming,answeredCalls]` |
50+
| Answered outgoing per hour | `asterisk[trunkCalls,{#TRUNKID},hour,outgoing,answeredCalls]` |
51+
52+
### Storage disk monitoring
53+
54+
| Metric | Zabbix item key |
55+
|---|---|
56+
| Total size | `vfs.fs.size[/storage,total]` |
57+
| Used space | `vfs.fs.size[/storage,used]` |
58+
| Free space | `vfs.fs.size[/storage,free]` |
59+
| Free space (%) | `vfs.fs.size[/storage,pfree]` |
60+
61+
## REST API
62+
63+
REST API v3 endpoints (auto-discovered via PHP 8 attributes):
64+
65+
| Method | Endpoint | Description |
66+
|---|---|---|
67+
| GET | `/pbxcore/api/v3/module-zabbix-agent5/status:getStatus` | Service status (running, pid, version, port, server) |
68+
| GET | `/pbxcore/api/v3/module-zabbix-agent5/status:downloadTemplate` | Download Zabbix template YAML |
69+
70+
## Zabbix template
71+
72+
Included template (`bin/zbx_export_templates.yaml`) provides:
73+
- All Asterisk metric items
74+
- SIP trunk LLD with per-trunk status and call statistics
75+
- Storage disk monitoring items with triggers (WARNING <10%, HIGH <5%)
76+
- Graphs: Calls overview, SIP endpoints, Trunk calls per hour, Storage usage
77+
- Triggers: Asterisk not running, non-active trunks, no SIP peers, no data from agent
78+
79+
## Build
80+
81+
Binaries are built automatically in GitHub Actions:
82+
- **AMD64**: native Alpine Linux build with musl (static linking)
83+
- **ARM64**: cross-compile on AMD64 using `aarch64-linux-gnu-gcc`
84+
85+
Both produce fully statically linked binaries with OpenSSL support.
86+
87+
## Requirements
88+
89+
- MikoPBX 2025.1.1+
90+
91+
## License
92+
93+
GPL-3.0-or-later
94+
95+
---
96+
97+
# ModuleZabbixAgent5 (Русский)
98+
99+
Модуль интеграции Zabbix Agent с MikoPBX. Собирает и отправляет метрики АТС на сервер Zabbix для мониторинга.
100+
101+
## Возможности
102+
103+
- Zabbix Agent 6.0 LTS (v6.0.44), статически слинкован (без внешних зависимостей)
104+
- Поддержка архитектур x86_64 и ARM64 (aarch64)
105+
- Веб-интерфейс для редактирования `zabbix_agentd.conf`
106+
- Отображение статуса сервиса в реальном времени (состояние, PID, версия, порт, сервер)
107+
- Кнопка скачивания шаблона Zabbix для импорта на сервер Zabbix
108+
- REST API v3 с автообнаружением (PHP 8 атрибуты, паттерн Processor + Actions)
109+
- Автоматическое управление сервисом (старт/стоп/рестарт)
110+
- Правило файрвола для порта Zabbix (по умолчанию 10050)
111+
- Проверка состояния сервиса по cron каждые 5 минут
112+
113+
## Метрики мониторинга
114+
115+
Все метрики доступны через UserParameter ключ `asterisk[<функция>]`.
116+
117+
### Метрики Asterisk
118+
119+
| Метрика | Ключ Zabbix |
120+
|---|---|
121+
| Активные вызовы (Asterisk CLI) | `asterisk[callsActive]` |
122+
| Обработанные вызовы | `asterisk[callsProcessed]` |
123+
| Активные каналы | `asterisk[channelsActive]` |
124+
| Входящие вызовы (через API) | `asterisk[countInCalls]` |
125+
| Исходящие вызовы (через API) | `asterisk[countOutCalls]` |
126+
| Внутренние вызовы (через API) | `asterisk[countInnerCalls]` |
127+
| SIP-пиры (всего) | `asterisk[countSipPeers]` |
128+
| SIP-пиры (онлайн) | `asterisk[CountActivePeers]` |
129+
| SIP-транки (онлайн) | `asterisk[CountActiveProviders]` |
130+
| SIP-транки (офлайн) | `asterisk[CountNonActiveProviders]` |
131+
| Аптайм Asterisk | `asterisk[statusUptime]` |
132+
| Время последнего reload | `asterisk[statusReload]` |
133+
| Версия Asterisk | `asterisk[version]` |
134+
| Статус Asterisk (1/0) | `asterisk[status]` |
135+
136+
### Обнаружение SIP-транков (LLD)
137+
138+
| Метрика | Ключ Zabbix |
139+
|---|---|
140+
| Статус регистрации транка | `asterisk[trunkStatus,{#TRUNKID}]` |
141+
| Входящие звонки за час | `asterisk[trunkCalls,{#TRUNKID},hour,incoming,totalCalls]` |
142+
| Исходящие звонки за час | `asterisk[trunkCalls,{#TRUNKID},hour,outgoing,totalCalls]` |
143+
| Входящие звонки за сутки | `asterisk[trunkCalls,{#TRUNKID},day,incoming,totalCalls]` |
144+
| Исходящие звонки за сутки | `asterisk[trunkCalls,{#TRUNKID},day,outgoing,totalCalls]` |
145+
| Отвеченные входящие за час | `asterisk[trunkCalls,{#TRUNKID},hour,incoming,answeredCalls]` |
146+
| Отвеченные исходящие за час | `asterisk[trunkCalls,{#TRUNKID},hour,outgoing,answeredCalls]` |
147+
148+
### Мониторинг диска /storage
149+
150+
| Метрика | Ключ Zabbix |
151+
|---|---|
152+
| Общий размер | `vfs.fs.size[/storage,total]` |
153+
| Занято | `vfs.fs.size[/storage,used]` |
154+
| Свободно | `vfs.fs.size[/storage,free]` |
155+
| Свободно (%) | `vfs.fs.size[/storage,pfree]` |
156+
157+
## REST API
158+
159+
REST API v3 эндпоинты (автообнаружение через PHP 8 атрибуты):
160+
161+
| Метод | Эндпоинт | Описание |
162+
|---|---|---|
163+
| GET | `/pbxcore/api/v3/module-zabbix-agent5/status:getStatus` | Статус сервиса (запущен, PID, версия, порт, сервер) |
164+
| GET | `/pbxcore/api/v3/module-zabbix-agent5/status:downloadTemplate` | Скачать шаблон Zabbix в формате YAML |
165+
166+
## Шаблон Zabbix
167+
168+
Включённый шаблон (`bin/zbx_export_templates.yaml`) содержит:
169+
- Все элементы данных Asterisk
170+
- LLD SIP-транков со статусом и статистикой звонков по каждому транку
171+
- Мониторинг диска /storage с триггерами (WARNING <10%, HIGH <5%)
172+
- Графики: обзор звонков, SIP-эндпоинты, звонки по транкам за час, использование хранилища
173+
- Триггеры: Asterisk не запущен, неактивные транки, нет SIP-пиров, нет данных от агента
174+
175+
## Сборка
176+
177+
Бинарники собираются автоматически в GitHub Actions:
178+
- **AMD64**: нативная сборка на Alpine Linux с musl (статическая линковка)
179+
- **ARM64**: кросс-компиляция на AMD64 с помощью `aarch64-linux-gnu-gcc`
180+
181+
Оба варианта — полностью статически слинкованные бинарники с поддержкой OpenSSL.
182+
183+
## Требования
184+
185+
- MikoPBX 2025.1.1+
186+
187+
## Лицензия
188+
189+
GPL-3.0-or-later

0 commit comments

Comments
 (0)