zabbixvms 0.1.0__tar.gz

zabbixvms-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Logic Elements s.r.o
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zabbixvms-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: zabbixvms
+Version: 0.1.0
+Summary: Zabbix monitoring agent for Logic Elements VMS deployments
+Author-email: Jan Bartovský <jan.bartovsky@logicelements.cz>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/LogicElements/py-vms-zabbix
+Keywords: logicelements,vibration,vms,zabbix
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mysql-connector-python
+Requires-Dist: jsonpickle
+Requires-Dist: zabbix_utils
+Requires-Dist: pywin32
+Requires-Dist: PyYAML
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# zabbixvms
+
+Zabbix agent pro monitorování instalací VMS od Logic Elements.
+
+Sleduje MySQL databázi (`BVMS`), do které zapisuje serverový software VMS, a odvozené metriky o stavu systému (měřené otáčky, stáří bufferů, konfigurace a časových značek, počty řádků v bufferech) odesílá na Zabbix server jako trapper položky (`vms.speed`, `vms.buf_rows_1`, ...).
+
+Balíček vznikl vyčleněním z projektu [`pyvms`](https://github.com/LogicElements/py-vms); na něm už nezávisí a s databází `BVMS` pracuje sám.
+
+## Dokumentace
+
+- [PRS-zabbixvms.md](doc/PRS-zabbixvms.md) – Product Requirement Specification: účel projektu, use cases a requirementy.
+- [PLAN-zabbixvms.md](doc/PLAN-zabbixvms.md) – plán: rozpad requirementů do etap.
+- [NAVRH-zabbixvms.md](doc/NAVRH-zabbixvms.md) – návrh struktury balíčku: jména, členění modulů a odpovědnosti.
+- [NAVOD-zabbix.md](doc/NAVOD-zabbix.md) – návod k nastavení Zabbixu: založení hostů, import šablony a její přiřazení.
+- [CHYBY-agenta.md](doc/CHYBY-agenta.md) – co agent hlásí, kde chyby vznikají a kde k nim hledat podrobnosti.
+- [BUILD-balicku.md](doc/BUILD-balicku.md) – sestavení balíčku: virtuální prostředí, testy, `build.bat` a publikování.
+
+## Instalace
+
+```bash
+pip install -e .
+```
+
+Běží pouze na Windows (pro integraci s Windows Service se používá `pywin32`).
+
+Python musí být na serveru nainstalovaný **pro celý stroj** (volba „for all users"), ne jen
+pro přihlášeného uživatele. Služba běží pod účtem LocalSystem a hostitelský proces
+`pythonservice.exe` potřebuje najít `python3XX.dll`. U instalace jen pro uživatele leží tahle
+knihovna v `%LOCALAPPDATA%`, LocalSystem ji na své cestě nemá a služba pak nenastartuje –
+ohlásí se jen chyba 1053, protože proces skončí dřív, než stihne odpovědět správci služeb.
+
+## Použití
+
+Instalace vytvoří dva vstupní body:
+
+- `zabbixvms-service` – služba Windows `ZabbixVms`,
+- `zabbixvms-tray` – ikona v systray, spouští se bez konzolového okna.
+
+Konfigurace (přístupové údaje k MySQL a Zabbixu, seznam monitorovaných turbín) je JSON
+v souboru `C:\ProgramData\LogicElements\ZabbixVms\config.json`. Pokud soubor neexistuje,
+vytvoří se při prvním spuštění z výchozí šablony dodané v balíčku; existující soubor
+zůstává beze změny i při aktualizaci balíčku.
+
+## Vývoj
+
+Testy se spouští z kořene repozitáře:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Licence
+
+MIT © Logic Elements s.r.o. — viz [LICENSE](LICENSE).

zabbixvms-0.1.0/README.md

@@ -0,0 +1,55 @@
+# zabbixvms
+
+Zabbix agent pro monitorování instalací VMS od Logic Elements.
+
+Sleduje MySQL databázi (`BVMS`), do které zapisuje serverový software VMS, a odvozené metriky o stavu systému (měřené otáčky, stáří bufferů, konfigurace a časových značek, počty řádků v bufferech) odesílá na Zabbix server jako trapper položky (`vms.speed`, `vms.buf_rows_1`, ...).
+
+Balíček vznikl vyčleněním z projektu [`pyvms`](https://github.com/LogicElements/py-vms); na něm už nezávisí a s databází `BVMS` pracuje sám.
+
+## Dokumentace
+
+- [PRS-zabbixvms.md](doc/PRS-zabbixvms.md) – Product Requirement Specification: účel projektu, use cases a requirementy.
+- [PLAN-zabbixvms.md](doc/PLAN-zabbixvms.md) – plán: rozpad requirementů do etap.
+- [NAVRH-zabbixvms.md](doc/NAVRH-zabbixvms.md) – návrh struktury balíčku: jména, členění modulů a odpovědnosti.
+- [NAVOD-zabbix.md](doc/NAVOD-zabbix.md) – návod k nastavení Zabbixu: založení hostů, import šablony a její přiřazení.
+- [CHYBY-agenta.md](doc/CHYBY-agenta.md) – co agent hlásí, kde chyby vznikají a kde k nim hledat podrobnosti.
+- [BUILD-balicku.md](doc/BUILD-balicku.md) – sestavení balíčku: virtuální prostředí, testy, `build.bat` a publikování.
+
+## Instalace
+
+```bash
+pip install -e .
+```
+
+Běží pouze na Windows (pro integraci s Windows Service se používá `pywin32`).
+
+Python musí být na serveru nainstalovaný **pro celý stroj** (volba „for all users"), ne jen
+pro přihlášeného uživatele. Služba běží pod účtem LocalSystem a hostitelský proces
+`pythonservice.exe` potřebuje najít `python3XX.dll`. U instalace jen pro uživatele leží tahle
+knihovna v `%LOCALAPPDATA%`, LocalSystem ji na své cestě nemá a služba pak nenastartuje –
+ohlásí se jen chyba 1053, protože proces skončí dřív, než stihne odpovědět správci služeb.
+
+## Použití
+
+Instalace vytvoří dva vstupní body:
+
+- `zabbixvms-service` – služba Windows `ZabbixVms`,
+- `zabbixvms-tray` – ikona v systray, spouští se bez konzolového okna.
+
+Konfigurace (přístupové údaje k MySQL a Zabbixu, seznam monitorovaných turbín) je JSON
+v souboru `C:\ProgramData\LogicElements\ZabbixVms\config.json`. Pokud soubor neexistuje,
+vytvoří se při prvním spuštění z výchozí šablony dodané v balíčku; existující soubor
+zůstává beze změny i při aktualizaci balíčku.
+
+## Vývoj
+
+Testy se spouští z kořene repozitáře:
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Licence
+
+MIT © Logic Elements s.r.o. — viz [LICENSE](LICENSE).

zabbixvms-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zabbixvms"
+description = "Zabbix monitoring agent for Logic Elements VMS deployments"
+version = "0.1.0"
+authors = [
+  { name="Jan Bartovský", email="jan.bartovsky@logicelements.cz" },
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: Microsoft :: Windows",
+]
+keywords = ["logicelements", "vibration", "vms", "zabbix"]
+
+requires-python = ">=3.12"
+dependencies = [
+    "mysql-connector-python",
+    "jsonpickle",
+    "zabbix_utils",
+    "pywin32",
+    "PyYAML",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+]
+
+[project.scripts]
+zabbixvms-service = "zabbixvms.service:main"
+
+[project.gui-scripts]
+zabbixvms-tray = "zabbixvms.tray:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+zabbixvms = ["data/*.json", "data/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "db: needs the BVMS test database, skipped when it is not reachable",
+    "gui: builds a real window and systray icon, needs a desktop session",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/LogicElements/py-vms-zabbix"

zabbixvms-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zabbixvms-0.1.0/src/zabbixvms/__init__.py

@@ -0,0 +1,7 @@
+"""Zabbix monitoring agent for Logic Elements VMS deployments.
+
+Nothing is re-exported here: import from the modules directly, for example
+from zabbixvms.config import Config.
+"""
+
+__version__ = "0.1.0"

zabbixvms-0.1.0/src/zabbixvms/agent.py

@@ -0,0 +1,117 @@
+"""The measurement loop: collect the values of every turbine, send them to Zabbix,
+report how the cycle went, wait, repeat.
+
+An error in one cycle must not end the loop. The database is unreachable, Zabbix is
+down, a turbine has no row - the cycle is given up, the state of the agent says so,
+and the next cycle starts five seconds later and picks up again once the cause is
+gone.
+"""
+
+from __future__ import annotations
+
+import time
+
+from zabbixvms.collector import Collector
+from zabbixvms.config import DEFAULT_PERIOD, Config
+from zabbixvms.log import log
+from zabbixvms.sender import TrapperSender
+
+# Delay between the end of one measurement cycle and the start of the next; it comes
+# from the configuration, this is what an agent without one would wait.
+CYCLE_DELAY = DEFAULT_PERIOD
+
+# Values of vms.agent_status.
+OK = 0
+WARNING = 1
+ERROR = 2
+
+# vms.agent_error is a Character item, which holds 255 characters.
+MAX_ERROR_LENGTH = 255
+
+STATUS_KEY = "vms.agent_status"
+ERROR_KEY = "vms.agent_error"
+
+
+class Agent:
+    """Runs the measurement cycle over all turbines of the configuration."""
+
+    def __init__(self, config: Config, collector: Collector | None = None,
+                 sender: TrapperSender | None = None, sleep=time.sleep) -> None:
+        self._config = config
+        self._collector = collector if collector is not None else Collector(config.database)
+        self._sender = sender if sender is not None else TrapperSender(config.zabbix)
+        self._sleep = sleep
+        self._running = False
+        self._warnings: list[str] = []
+        # Error of the last cycle, or None when the last cycle went through.
+        self.last_error: Exception | None = None
+        # What the agent said about itself in the last cycle.
+        self.status = OK
+        self.error_text = ""
+
+    @property
+    def running(self) -> bool:
+        return self._running
+
+    @property
+    def period(self) -> int:
+        """Seconds waited between cycles, as the configuration sets them."""
+        return self._config.zabbix.period
+
+    def cycle(self) -> None:
+        """One measurement cycle: every turbine collected and sent."""
+        self._warnings = []
+        if not self._collector.is_connected:
+            self._collector.connect()
+        for turbine in self._config.turbines:
+            values = self._collector.collect(turbine)
+            self._warnings.extend(self._collector.warnings)
+            self._sender.send(turbine, values)
+
+    def run(self) -> None:
+        """Repeat the cycle until stop() is called."""
+        self._running = True
+        while self._running:
+            try:
+                self.cycle()
+                self.last_error = None
+                status, message = self._state_of_the_cycle()
+            except Exception as err:
+                # The loop outlives the cycle; the database or Zabbix may come back.
+                self.last_error = err
+                status, message = ERROR, str(err)
+                log.error("measurement cycle failed: %s", err)
+                self._collector.close()
+
+            self.status = status
+            self.error_text = message[:MAX_ERROR_LENGTH]
+            self.report_state()
+            self._sleep(self.period)
+
+    def stop(self) -> None:
+        """Ask the loop to finish and release the database connection."""
+        self._running = False
+        self._collector.close()
+
+    def report_state(self) -> None:
+        """Send how the agent is doing to the host of every turbine.
+
+        The state goes out even when the cycle failed, so the operator sees why no
+        values arrived. When Zabbix is the thing that is down, this cannot get
+        through either and is only written to the log.
+        """
+        values = {STATUS_KEY: self.status, ERROR_KEY: self.error_text}
+        for turbine in self._config.turbines:
+            try:
+                self._sender.send(turbine, values)
+            except Exception as err:
+                log.error("state of the agent could not be sent for turbine %s: %s",
+                          turbine.name, err)
+
+    def _state_of_the_cycle(self) -> tuple[int, str]:
+        """Status and text after a cycle that got through without an exception."""
+        if not self._warnings:
+            return OK, ""
+        message = "; ".join(self._warnings)
+        log.warning("measurement cycle finished with a warning: %s", message)
+        return WARNING, message

zabbixvms-0.1.0/src/zabbixvms/collector.py

@@ -0,0 +1,190 @@
+"""Reads the BVMS database and computes the metric values from it.
+
+What each metric is computed from is the source table of UC4 in the PRS. Values of
+the info table are read by column name, never by position, so adding a column or
+reordering the table does not change what is sent.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+import mysql.connector
+
+from zabbixvms.config import DatabaseConfig, Turbine
+
+# Columns of the info table the metrics are computed from. They are enumerated in the
+# query instead of SELECT *, so every value is picked by name.
+INFO_COLUMNS = (
+    "Date",
+    "Phase_Marker",
+    "Date_Timestamp",
+    "Date_Config",
+    "Date_Buffer_1",
+    "Date_Buffer_2",
+    "Time_bulk_1",
+    "Time_bulk_2",
+)
+
+# Ages are reported up to one month; anything older says the same thing, that the data
+# stopped coming long ago. The database keeps 0001-01-01 for "never", which saturates
+# here like any other very old date.
+MAX_AGE = timedelta(days=30)
+MAX_AGE_SECONDS = int(MAX_AGE.total_seconds())
+
+# Metrics of a buffer the turbine does not have configured.
+NO_BUFFER = 0
+
+
+class CollectorError(Exception):
+    """The database does not hold what the agent needs for a turbine."""
+
+
+def speed(phase_marker: int | None) -> float:
+    """Turbine speed in rpm from the phase marker period.
+
+    A standing turbine has no phase marker period, the speed is 0 rpm then.
+    """
+    if not phase_marker:
+        return 0.0
+    return round(1e8 / phase_marker * 60, 4)
+
+
+def age(moment: datetime | None, now: datetime) -> int:
+    """Whole seconds between moment and the measurement time, at most one month.
+
+    A missing value means the data never came, which is as old as it gets and
+    saturates too. A date in the future would be a negative age, which an unsigned
+    item cannot hold, so it reads as zero.
+    """
+    if moment is None:
+        return MAX_AGE_SECONDS
+    elapsed = int((now - moment).total_seconds())
+    return max(0, min(elapsed, MAX_AGE_SECONDS))
+
+
+class Collector:
+    """Reads one turbine's values out of the BVMS database."""
+
+    def __init__(self, database: DatabaseConfig, connect=mysql.connector.connect) -> None:
+        self._database = database
+        self._connect = connect
+        self._connection = None
+        # Things worth telling about that do not stop the collection; filled by
+        # collect() for the turbine it was called with.
+        self.warnings: list[str] = []
+
+    def connect(self) -> None:
+        """Open the connection to MySQL using the values from the configuration."""
+        self._connection = self._connect(
+            host=self._database.host,
+            database=self._database.database,
+            user=self._database.user,
+            password=self._database.password,
+        )
+
+    @property
+    def is_connected(self) -> bool:
+        """Whether the collector currently holds a connection to MySQL."""
+        return self._connection is not None
+
+    def close(self) -> None:
+        """Close the connection; closing a collector that is not connected is fine."""
+        if self._connection is not None:
+            self._connection.close()
+            self._connection = None
+
+    def read_info(self, turbine: Turbine) -> dict:
+        """Row of the info table belonging to the turbine, keyed by column name."""
+        columns = ", ".join(f"`{column}`" for column in INFO_COLUMNS)
+        query = (f"SELECT {columns} FROM `{self._database.info_table}` "
+                 f"WHERE `SystemId` = %s")
+
+        cursor = self._cursor()
+        try:
+            cursor.execute(query, (turbine.system_id,))
+            rows = cursor.fetchall()
+        finally:
+            cursor.close()
+
+        if not rows:
+            raise CollectorError(
+                f"table {self._database.info_table} has no row with SystemId "
+                f"{turbine.system_id} of turbine {turbine.name!r}"
+            )
+        return rows[0]
+
+    def read_buffer_rows(self, turbine: Turbine) -> dict[str, int]:
+        """Row counts of the turbine's buffer tables, keyed by table name."""
+        if not turbine.buffers:
+            return {}
+
+        placeholders = ", ".join(["%s"] * len(turbine.buffers))
+        query = ("SELECT TABLE_NAME, TABLE_ROWS FROM information_schema.TABLES "
+                 f"WHERE TABLE_SCHEMA = %s AND TABLE_NAME IN ({placeholders})")
+
+        cursor = self._cursor()
+        try:
+            cursor.execute(query, (self._database.database, *turbine.buffers))
+            rows = cursor.fetchall()
+        finally:
+            cursor.close()
+
+        return {row["TABLE_NAME"]: row["TABLE_ROWS"] or 0 for row in rows}
+
+    def collect(self, turbine: Turbine, now: datetime | None = None) -> dict[str, float]:
+        """Values of all collected metrics of one turbine, keyed by metric key."""
+        if now is None:
+            now = datetime.now()
+        self.warnings = []
+        info = self.read_info(turbine)
+        buffer_rows = self.read_buffer_rows(turbine)
+        for table in turbine.buffers:
+            if table not in buffer_rows:
+                # Counting zero rows here would look like an empty buffer, which is
+                # something else entirely than a table that is not there.
+                self.warnings.append(
+                    f"buffer table {table!r} of turbine {turbine.name!r} is not in "
+                    f"database {self._database.database}")
+        return self.values(turbine, info, buffer_rows, now)
+
+    @staticmethod
+    def values(turbine: Turbine, info: dict, buffer_rows: dict[str, int],
+               now: datetime) -> dict[str, float]:
+        """Metric values computed from one info row and the buffer row counts.
+
+        Every value of one cycle is computed against the same measurement time.
+        """
+        values = {
+            "vms.speed": speed(info["Phase_Marker"]),
+            "vms.info_age": age(info["Date"], now),
+            "vms.timestamp_age": age(info["Date_Timestamp"], now),
+            "vms.config_age": age(info["Date_Config"], now),
+        }
+
+        # The buffers are summed up into one metric each. Rows and bulk time add up;
+        # the age is the worst of them, because summing two ages gives a number that
+        # is the age of nothing. A buffer the turbine does not have contributes
+        # nothing, so a turbine with one buffer reports exactly that one. Which info
+        # columns a buffer uses follows its position, not the table name in the
+        # configuration.
+        rows = bulk = oldest = NO_BUFFER
+        for index in (1, 2):
+            if len(turbine.buffers) < index:
+                continue
+            table = turbine.buffers[index - 1]
+            oldest = max(oldest, age(info[f"Date_Buffer_{index}"], now))
+            bulk += info[f"Time_bulk_{index}"] or 0
+            rows += buffer_rows.get(table, 0)
+
+        values["vms.buf_rows"] = rows
+        values["vms.buf_age"] = oldest
+        values["vms.buf_bulk"] = bulk
+
+        return values
+
+    def _cursor(self):
+        """Cursor returning rows as dicts, so values are picked by column name."""
+        if self._connection is None:
+            raise CollectorError("collector is not connected to the database")
+        return self._connection.cursor(dictionary=True)