ipmg 3.0.0__tar.gz → 3.1.0__tar.gz

{ipmg-3.0.0/src/ipmg.egg-info → ipmg-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 3.0.0
+Version: 3.1.0
 Summary: IP Management & Ping Monitoring CLI Tool
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -558,6 +558,57 @@ your own scripts. The [API guide](https://github.com/sameeralam3127/ipmg/blob/ma
 covers authentication, errors, and worked `curl` examples; the running server
 also serves interactive docs at `http://127.0.0.1:8080/docs`.
 
+### Prometheus metrics
+
+`ipmg web --metrics` serves `/metrics` in the Prometheus text format, so the
+results of every scan, whether run from cron with the CLI or from the browser,
+land in the dashboards and alerts you already have. It reports the latest
+completed scan of each source, and it is off unless you pass the flag:
+
+```bash
+IPMG_WEB_TOKEN=$(cat /etc/ipmg/token) ipmg web --metrics --no-browser
+```
+
+```yaml
+# prometheus.yml: the token is the same one the web UI uses
+scrape_configs:
+  - job_name: ipmg
+    authorization:
+      credentials_file: /etc/prometheus/ipmg-token
+    static_configs:
+      - targets: ["127.0.0.1:8080"]
+
+# an alert rule: a host that stopped answering
+groups:
+  - name: ipmg
+    rules:
+      - alert: HostDown
+        expr: ipmg_host_up == 0
+        for: 10m
+        annotations:
+          summary: "{{ $labels.ip }} ({{ $labels.source }}) is not answering ping"
+```
+
+| Metric | Labels | Meaning |
+| --- | --- | --- |
+| `ipmg_host_up` | `source`, `ip` | 1 if the host answered, else 0 |
+| `ipmg_host_latency_seconds` | `source`, `ip` | Round-trip time, for hosts that answered |
+| `ipmg_host_open_ports` | `source`, `ip` | Open TCP ports, for scans run with `--scan-ports` |
+| `ipmg_host_info` | `source`, `ip`, `hostname` | Always 1; carries the reverse DNS name |
+| `ipmg_scan_hosts` | `source`, `status` | Hosts in the latest scan, by status |
+| `ipmg_scan_duration_seconds` | `source` | How long the latest scan took |
+| `ipmg_scan_timestamp_seconds` | `source` | When the latest scan finished; alert on `time() - this` to catch a stalled cron job |
+| `ipmg_scans_total` | `source` | Completed scans stored for the source |
+| `ipmg_metrics_sources_omitted` | | Sources left out by `--metrics-sources` |
+| `ipmg_build_info` | `version` | Always 1 |
+
+**Cardinality is bounded.** Host series carry only `source` and `ip`, never
+the hostname or status, which change, so a rename does not start a new series.
+Only the `--metrics-sources` most recently scanned sources are exported
+(default 20), and a scan holds at most 65,536 hosts, so the page stays at
+about `sources × hosts × 4` series at most. Give recurring scans a stable
+input (the same file) so each one updates its source rather than adding one.
+
 ### On a server with no browser
 
 On a Linux server with no display (e.g. accessed over plain SSH), IPMG detects

{ipmg-3.0.0 → ipmg-3.1.0}/README.md

@@ -506,6 +506,57 @@ your own scripts. The [API guide](https://github.com/sameeralam3127/ipmg/blob/ma
 covers authentication, errors, and worked `curl` examples; the running server
 also serves interactive docs at `http://127.0.0.1:8080/docs`.
 
+### Prometheus metrics
+
+`ipmg web --metrics` serves `/metrics` in the Prometheus text format, so the
+results of every scan, whether run from cron with the CLI or from the browser,
+land in the dashboards and alerts you already have. It reports the latest
+completed scan of each source, and it is off unless you pass the flag:
+
+```bash
+IPMG_WEB_TOKEN=$(cat /etc/ipmg/token) ipmg web --metrics --no-browser
+```
+
+```yaml
+# prometheus.yml: the token is the same one the web UI uses
+scrape_configs:
+  - job_name: ipmg
+    authorization:
+      credentials_file: /etc/prometheus/ipmg-token
+    static_configs:
+      - targets: ["127.0.0.1:8080"]
+
+# an alert rule: a host that stopped answering
+groups:
+  - name: ipmg
+    rules:
+      - alert: HostDown
+        expr: ipmg_host_up == 0
+        for: 10m
+        annotations:
+          summary: "{{ $labels.ip }} ({{ $labels.source }}) is not answering ping"
+```
+
+| Metric | Labels | Meaning |
+| --- | --- | --- |
+| `ipmg_host_up` | `source`, `ip` | 1 if the host answered, else 0 |
+| `ipmg_host_latency_seconds` | `source`, `ip` | Round-trip time, for hosts that answered |
+| `ipmg_host_open_ports` | `source`, `ip` | Open TCP ports, for scans run with `--scan-ports` |
+| `ipmg_host_info` | `source`, `ip`, `hostname` | Always 1; carries the reverse DNS name |
+| `ipmg_scan_hosts` | `source`, `status` | Hosts in the latest scan, by status |
+| `ipmg_scan_duration_seconds` | `source` | How long the latest scan took |
+| `ipmg_scan_timestamp_seconds` | `source` | When the latest scan finished; alert on `time() - this` to catch a stalled cron job |
+| `ipmg_scans_total` | `source` | Completed scans stored for the source |
+| `ipmg_metrics_sources_omitted` | | Sources left out by `--metrics-sources` |
+| `ipmg_build_info` | `version` | Always 1 |
+
+**Cardinality is bounded.** Host series carry only `source` and `ip`, never
+the hostname or status, which change, so a rename does not start a new series.
+Only the `--metrics-sources` most recently scanned sources are exported
+(default 20), and a scan holds at most 65,536 hosts, so the page stays at
+about `sources × hosts × 4` series at most. Give recurring scans a stable
+input (the same file) so each one updates its source rather than adding one.
+
 ### On a server with no browser
 
 On a Linux server with no display (e.g. accessed over plain SSH), IPMG detects

{ipmg-3.0.0 → ipmg-3.1.0}/pyproject.toml

@@ -13,7 +13,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ipmg"
-version = "3.0.0"  # Managed automatically by semantic-release
+version = "3.1.0"  # Managed automatically by semantic-release
 description = "IP Management & Ping Monitoring CLI Tool"
 readme = "README.md"
 requires-python = ">=3.9"

{ipmg-3.0.0 → ipmg-3.1.0}/src/ipmg/__init__.py

@@ -2,4 +2,4 @@
 ipmg - IP Management & Ping Monitoring Tool
 """
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"

{ipmg-3.0.0 → ipmg-3.1.0}/src/ipmg/cli/commands.py

@@ -82,6 +82,7 @@ def _web_command(argv: List[str]) -> int:
         port=args.port,
         open_browser=not args.no_browser,
         db_path=args.db,
+        metrics_sources=max(args.metrics_sources, 1) if args.metrics else None,
     )
     return EXIT_OK
 

{ipmg-3.0.0 → ipmg-3.1.0}/src/ipmg/cli/parser.py

@@ -27,6 +27,7 @@ from ipmg.infrastructure.notify import (
 )
 from ipmg.reporting.diff_report import DIFF_FORMATS
 from ipmg.reporting.live import DEFAULT_REFRESH_S, MAX_REFRESH_S, MIN_REFRESH_S
+from ipmg.reporting.metrics import DEFAULT_MAX_SOURCES
 
 PROG = "IPMG - IP Management & Ping Monitoring Tool"
 
@@ -458,6 +459,24 @@ def build_web_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Do not open IPMG Web in a browser automatically.",
     )
+    parser.add_argument(
+        "--metrics",
+        action="store_true",
+        help=(
+            "Serve Prometheus metrics at /metrics for the latest completed scan of "
+            "each source (off by default; needs the access token)."
+        ),
+    )
+    parser.add_argument(
+        "--metrics-sources",
+        type=int,
+        default=DEFAULT_MAX_SOURCES,
+        metavar="N",
+        help=(
+            "Export only the N most recently scanned sources, which bounds the "
+            f"number of series (default: {DEFAULT_MAX_SOURCES})."
+        ),
+    )
     _add_database_argument(parser)
     parser.add_argument("--verbose", action="store_true")
     return parser

{ipmg-3.0.0 → ipmg-3.1.0}/src/ipmg/infrastructure/database.py

@@ -13,7 +13,7 @@ import threading
 from contextlib import contextmanager
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Optional, Sequence
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 
 from ipmg.core.diff import HostSnapshot, ScanRef, ip_sort_key
 from ipmg.core.engine import HostResult
@@ -299,6 +299,22 @@ class Database:
         with self._session() as conn:
             return [dict(row) for row in conn.execute(query, params).fetchall()]
 
+    def latest_completed_scans(self, limit: int) -> Tuple[List[Dict[str, Any]], int]:
+        """The newest completed scan of each source, most recent source first.
+
+        Returns at most ``limit`` scans, each with a ``completed_count`` of the
+        completed scans its source has, plus how many sources exist in all, so
+        a caller can say how many it left out.
+        """
+        with self._session() as conn:
+            rows = conn.execute(
+                "SELECT s.*, latest.completed_count FROM scans s JOIN ("
+                "  SELECT source, MAX(id) AS id, COUNT(*) AS completed_count "
+                "  FROM scans WHERE status = 'complete' GROUP BY source"
+                ") latest ON s.id = latest.id ORDER BY s.id DESC"
+            ).fetchall()
+        return [self._scan_dict(row) for row in rows[:limit]], len(rows)
+
     # ------------------------------------------------------- aggregates
 
     def overview(self) -> Dict[str, Any]:

ipmg-3.1.0/src/ipmg/reporting/metrics.py

@@ -0,0 +1,125 @@
+"""Prometheus metrics for the most recent completed scan of each source.
+
+Rendered by hand in the text exposition format (version 0.0.4), so serving
+``/metrics`` adds no dependency. Every per-host series is labelled by
+``source`` and ``ip`` only; the hostname, which changes, lives on a separate
+``ipmg_host_info`` series so a rename does not start a new latency series.
+
+Cardinality is bounded by what is in the history database: one series per
+host per metric for the newest completed scan of each of the ``max_sources``
+most recently scanned sources, and a scan holds at most 65,536 hosts.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Dict, Iterable, List, Optional, Sequence, Tuple
+
+from ipmg import __version__
+from ipmg.core.portscan import decode_ports
+from ipmg.infrastructure.database import Database
+
+CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+#: Sources exported by default: the most recently scanned ones.
+DEFAULT_MAX_SOURCES = 20
+
+Labels = Sequence[Tuple[str, str]]
+
+
+def _escape(value: str) -> str:
+    """Escape a label value as the exposition format requires."""
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+def _number(value: float) -> str:
+    return repr(float(value)) if not float(value).is_integer() else str(int(value))
+
+
+class _Exposition:
+    """Collects samples per metric, then writes each family under one header."""
+
+    def __init__(self) -> None:
+        self._families: Dict[str, Tuple[str, str, List[str]]] = {}
+
+    def declare(self, name: str, kind: str, help_text: str) -> None:
+        self._families[name] = (kind, help_text, [])
+
+    def sample(self, name: str, labels: Labels, value: float) -> None:
+        rendered = ",".join(f'{key}="{_escape(str(val))}"' for key, val in labels)
+        series = f"{name}{{{rendered}}}" if rendered else name
+        self._families[name][2].append(f"{series} {_number(value)}")
+
+    def render(self) -> str:
+        lines: List[str] = []
+        for name, (kind, help_text, samples) in self._families.items():
+            lines.append(f"# HELP {name} {help_text}")
+            lines.append(f"# TYPE {name} {kind}")
+            lines.extend(samples)
+        return "\n".join(lines) + "\n"
+
+
+_FAMILIES = (
+    ("ipmg_build_info", "gauge", "IPMG version serving these metrics (always 1)."),
+    ("ipmg_host_up", "gauge", "1 if the host answered in its source's latest scan, else 0."),
+    (
+        "ipmg_host_latency_seconds",
+        "gauge",
+        "Round-trip time in the latest scan, hosts that answered.",
+    ),
+    ("ipmg_host_open_ports", "gauge", "Open TCP ports found, for scans that checked ports."),
+    ("ipmg_host_info", "gauge", "The host's reverse DNS name in the latest scan (always 1)."),
+    ("ipmg_scan_hosts", "gauge", "Hosts in the source's latest scan, by status."),
+    ("ipmg_scan_duration_seconds", "gauge", "How long the source's latest scan took."),
+    ("ipmg_scan_timestamp_seconds", "gauge", "When the source's latest scan finished (Unix time)."),
+    ("ipmg_scans_total", "counter", "Completed scans stored for the source."),
+    ("ipmg_metrics_sources_omitted", "gauge", "Sources left out by the --metrics-sources limit."),
+)
+
+
+def _finished_at(scan: Dict) -> Optional[float]:
+    try:
+        return datetime.fromisoformat(scan["finished_at"]).timestamp()
+    except (KeyError, TypeError, ValueError):
+        return None
+
+
+def _host_samples(out: _Exposition, source: str, rows: Iterable[Dict], ports: bool) -> None:
+    for row in rows:
+        labels = (("source", source), ("ip", row["ip"]))
+        out.sample("ipmg_host_up", labels, 1 if row["status"] == "Active" else 0)
+        if row["latency"] is not None:
+            out.sample("ipmg_host_latency_seconds", labels, row["latency"] / 1000)
+        if ports:
+            out.sample("ipmg_host_open_ports", labels, len(decode_ports(row["open_ports"])))
+        if row["hostname"]:
+            out.sample("ipmg_host_info", (*labels, ("hostname", row["hostname"])), 1)
+
+
+def render_metrics(database: Database, max_sources: int = DEFAULT_MAX_SOURCES) -> str:
+    """The metrics page for ``database``, in Prometheus text format."""
+    out = _Exposition()
+    for name, kind, help_text in _FAMILIES:
+        out.declare(name, kind, help_text)
+    out.sample("ipmg_build_info", (("version", __version__),), 1)
+
+    scans, source_count = database.latest_completed_scans(max_sources)
+    for scan in scans:
+        source = scan["source"]
+        rows = database.get_results(scan["id"])
+        _host_samples(out, source, rows, bool(scan["config"].get("scan_ports")))
+
+        counts: Dict[str, int] = {}
+        for row in rows:
+            counts[row["status"]] = counts.get(row["status"], 0) + 1
+        for status, count in sorted(counts.items()):
+            out.sample("ipmg_scan_hosts", (("source", source), ("status", status)), count)
+
+        out.sample("ipmg_scan_duration_seconds", (("source", source),), scan["duration_s"] or 0)
+        finished = _finished_at(scan)
+        if finished is not None:
+            out.sample("ipmg_scan_timestamp_seconds", (("source", source),), finished)
+        out.sample("ipmg_scans_total", (("source", source),), scan["completed_count"])
+
+    out.sample("ipmg_metrics_sources_omitted", (), max(source_count - len(scans), 0))
+    return out.render()

{ipmg-3.0.0 → ipmg-3.1.0}/src/ipmg/web/app.py

@@ -568,8 +568,31 @@ def _install_openapi(app: FastAPI) -> None:
     app.openapi = openapi  # type: ignore[method-assign]
 
 
-def create_app(db: Optional[Database] = None, token: Optional[str] = None) -> FastAPI:
-    """Build the app. ``token`` guards every API route; a random one is made if omitted."""
+def _register_metrics_route(app: FastAPI, database: Database, token: str, max_sources: int) -> None:
+    # Outside /api/v1 because /metrics is where Prometheus looks, but behind
+    # the same token: a scrape config sends it as a Bearer credential.
+    # Imported here: the renderer is only needed when --metrics turns it on.
+    from ipmg.reporting.metrics import CONTENT_TYPE as METRICS_CONTENT_TYPE, render_metrics
+
+    @app.get(
+        "/metrics",
+        dependencies=[Depends(_require_token(token))],
+        include_in_schema=False,
+    )
+    def metrics() -> Response:
+        return Response(render_metrics(database, max_sources), media_type=METRICS_CONTENT_TYPE)
+
+
+def create_app(
+    db: Optional[Database] = None,
+    token: Optional[str] = None,
+    metrics_sources: Optional[int] = None,
+) -> FastAPI:
+    """Build the app. ``token`` guards every API route; a random one is made if omitted.
+
+    ``metrics_sources`` turns on ``/metrics`` for that many of the most
+    recently scanned sources; left as None, the endpoint does not exist.
+    """
     database = db if db is not None else Database(DEFAULT_DB_PATH)
     token = token or secrets.token_urlsafe(32)
     manager = ScanManager(database)
@@ -601,6 +624,8 @@ def create_app(db: Optional[Database] = None, token: Optional[str] = None) -> Fa
     app.include_router(api)
 
     _register_websocket(app, manager, token)
+    if metrics_sources is not None:
+        _register_metrics_route(app, database, token, metrics_sources)
     _register_error_handlers(app)
     _install_openapi(app)
 

{ipmg-3.0.0 → ipmg-3.1.0}/src/ipmg/web/server.py

@@ -69,10 +69,11 @@ def run_dashboard(
     port: int = 8080,
     open_browser: bool = True,
     db_path: Optional[str] = None,
+    metrics_sources: Optional[int] = None,
 ) -> None:
     database = Database(Path(db_path) if db_path else DEFAULT_DB_PATH)
     token = _access_token()
-    app = create_app(database, token)
+    app = create_app(database, token, metrics_sources=metrics_sources)
     # The token goes in the fragment, which browsers never send to the server,
     # so it stays out of access logs and proxies.
     url = f"http://{_display_host(host)}:{port}/#token={token}"
@@ -94,6 +95,11 @@ def run_dashboard(
         threading.Timer(1.0, webbrowser.open, args=(url,)).start()
 
     ui.note("The link carries this session's access token; the API refuses requests without it.")
+    if metrics_sources is not None:
+        ui.note(
+            f"Prometheus metrics at http://{_display_host(host)}:{port}/metrics "
+            "(send the token as a Bearer credential; pin it with IPMG_WEB_TOKEN)."
+        )
     if _is_loopback(host):
         ui.note(
             f"Remote access: ssh -L {port}:127.0.0.1:{port} user@this-host, then open the link."

{ipmg-3.0.0 → ipmg-3.1.0/src/ipmg.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipmg
-Version: 3.0.0
+Version: 3.1.0
 Summary: IP Management & Ping Monitoring CLI Tool
 Author: Sameer Alam
 Maintainer-email: Sameer Alam <sameeralam3127@gmail.com>
@@ -558,6 +558,57 @@ your own scripts. The [API guide](https://github.com/sameeralam3127/ipmg/blob/ma
 covers authentication, errors, and worked `curl` examples; the running server
 also serves interactive docs at `http://127.0.0.1:8080/docs`.
 
+### Prometheus metrics
+
+`ipmg web --metrics` serves `/metrics` in the Prometheus text format, so the
+results of every scan, whether run from cron with the CLI or from the browser,
+land in the dashboards and alerts you already have. It reports the latest
+completed scan of each source, and it is off unless you pass the flag:
+
+```bash
+IPMG_WEB_TOKEN=$(cat /etc/ipmg/token) ipmg web --metrics --no-browser
+```
+
+```yaml
+# prometheus.yml: the token is the same one the web UI uses
+scrape_configs:
+  - job_name: ipmg
+    authorization:
+      credentials_file: /etc/prometheus/ipmg-token
+    static_configs:
+      - targets: ["127.0.0.1:8080"]
+
+# an alert rule: a host that stopped answering
+groups:
+  - name: ipmg
+    rules:
+      - alert: HostDown
+        expr: ipmg_host_up == 0
+        for: 10m
+        annotations:
+          summary: "{{ $labels.ip }} ({{ $labels.source }}) is not answering ping"
+```
+
+| Metric | Labels | Meaning |
+| --- | --- | --- |
+| `ipmg_host_up` | `source`, `ip` | 1 if the host answered, else 0 |
+| `ipmg_host_latency_seconds` | `source`, `ip` | Round-trip time, for hosts that answered |
+| `ipmg_host_open_ports` | `source`, `ip` | Open TCP ports, for scans run with `--scan-ports` |
+| `ipmg_host_info` | `source`, `ip`, `hostname` | Always 1; carries the reverse DNS name |
+| `ipmg_scan_hosts` | `source`, `status` | Hosts in the latest scan, by status |
+| `ipmg_scan_duration_seconds` | `source` | How long the latest scan took |
+| `ipmg_scan_timestamp_seconds` | `source` | When the latest scan finished; alert on `time() - this` to catch a stalled cron job |
+| `ipmg_scans_total` | `source` | Completed scans stored for the source |
+| `ipmg_metrics_sources_omitted` | | Sources left out by `--metrics-sources` |
+| `ipmg_build_info` | `version` | Always 1 |
+
+**Cardinality is bounded.** Host series carry only `source` and `ip`, never
+the hostname or status, which change, so a rename does not start a new series.
+Only the `--metrics-sources` most recently scanned sources are exported
+(default 20), and a scan holds at most 65,536 hosts, so the page stays at
+about `sources × hosts × 4` series at most. Give recurring scans a stable
+input (the same file) so each one updates its source rather than adding one.
+
 ### On a server with no browser
 
 On a Linux server with no display (e.g. accessed over plain SSH), IPMG detects

{ipmg-3.0.0 → ipmg-3.1.0}/src/ipmg.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ src/ipmg/reporting/diff_report.py
 src/ipmg/reporting/frames.py
 src/ipmg/reporting/live.py
 src/ipmg/reporting/machine.py
+src/ipmg/reporting/metrics.py
 src/ipmg/reporting/summary.py
 src/ipmg/reporting/ui.py
 src/ipmg/services/__init__.py
@@ -67,6 +68,7 @@ tests/test_incremental.py
 tests/test_ipv6.py
 tests/test_live.py
 tests/test_machine_output.py
+tests/test_metrics.py
 tests/test_notify.py
 tests/test_parser.py
 tests/test_ping.py

{ipmg-3.0.0 → ipmg-3.1.0}/tests/test_commands.py

@@ -208,7 +208,15 @@ def test_both_spellings_of_web_start_it(argv, monkeypatch):
     calls = web_calls(monkeypatch)
 
     assert commands.run(argv) == commands.EXIT_OK
-    assert calls == [{"host": "127.0.0.1", "port": 8080, "open_browser": True, "db_path": None}]
+    assert calls == [
+        {
+            "host": "127.0.0.1",
+            "port": 8080,
+            "open_browser": True,
+            "db_path": None,
+            "metrics_sources": None,
+        }
+    ]
 
 
 def test_web_flag_still_takes_the_web_options(monkeypatch):

ipmg-3.1.0/tests/test_metrics.py

@@ -0,0 +1,162 @@
+"""The Prometheus /metrics endpoint and the text it serves."""
+
+import re
+
+import pytest
+from fastapi.testclient import TestClient
+
+from ipmg import __version__
+from ipmg.cli.parser import build_web_parser
+from ipmg.core.engine import HostResult, ScanConfig
+from ipmg.infrastructure.database import Database
+from ipmg.reporting.metrics import CONTENT_TYPE, render_metrics
+from ipmg.services.history_service import HistoryService
+from ipmg.web.app import create_app
+
+
+@pytest.fixture()
+def database(tmp_path):
+    return Database(tmp_path / "metrics.db")
+
+
+def record(database, source, results, scan_ports=False, duration=2.5):
+    return HistoryService(database).record_scan(
+        source=source,
+        results=results,
+        config=ScanConfig(scan_ports=scan_ports),
+        duration_s=duration,
+    )
+
+
+def samples(text):
+    """{series: value} for every sample line, ignoring HELP and TYPE."""
+    found = {}
+    for line in text.splitlines():
+        if line and not line.startswith("#"):
+            series, value = line.rsplit(" ", 1)
+            found[series] = float(value)
+    return found
+
+
+# ------------------------------------------------------------------ content
+
+
+def test_hosts_are_reported_from_the_latest_scan_of_each_source(database):
+    record(database, "targets.txt", [HostResult("10.0.0.1", "Timeout", None)])
+    record(
+        database,
+        "targets.txt",
+        [HostResult("10.0.0.1", "Active", 12.5, "gw.lan"), HostResult("10.0.0.2", "Timeout", None)],
+        duration=4.0,
+    )
+
+    metrics = samples(render_metrics(database))
+
+    assert metrics['ipmg_host_up{source="targets.txt",ip="10.0.0.1"}'] == 1
+    assert metrics['ipmg_host_up{source="targets.txt",ip="10.0.0.2"}'] == 0
+    assert metrics['ipmg_host_latency_seconds{source="targets.txt",ip="10.0.0.1"}'] == 0.0125
+    assert 'ipmg_host_latency_seconds{source="targets.txt",ip="10.0.0.2"}' not in metrics
+    assert metrics['ipmg_host_info{source="targets.txt",ip="10.0.0.1",hostname="gw.lan"}'] == 1
+    assert metrics['ipmg_scan_hosts{source="targets.txt",status="Active"}'] == 1
+    assert metrics['ipmg_scan_hosts{source="targets.txt",status="Timeout"}'] == 1
+    assert metrics['ipmg_scan_duration_seconds{source="targets.txt"}'] == 4.0
+    assert metrics['ipmg_scans_total{source="targets.txt"}'] == 2
+    assert metrics['ipmg_scan_timestamp_seconds{source="targets.txt"}'] > 1.7e9
+    assert metrics[f'ipmg_build_info{{version="{__version__}"}}'] == 1
+
+
+def test_each_source_keeps_its_own_latest_scan(database):
+    record(database, "office.txt", [HostResult("10.0.0.1", "Active", 1.0)])
+    record(database, "lab.txt", [HostResult("10.0.0.1", "Timeout", None)])
+
+    metrics = samples(render_metrics(database))
+
+    assert metrics['ipmg_host_up{source="office.txt",ip="10.0.0.1"}'] == 1
+    assert metrics['ipmg_host_up{source="lab.txt",ip="10.0.0.1"}'] == 0
+
+
+def test_open_ports_only_appear_for_scans_that_checked_ports(database):
+    record(
+        database, "ports.txt", [HostResult("10.0.0.1", "Active", 1.0, open_ports=(22, 443))], True
+    )
+    record(database, "plain.txt", [HostResult("10.0.0.2", "Active", 1.0)])
+
+    metrics = samples(render_metrics(database))
+
+    assert metrics['ipmg_host_open_ports{source="ports.txt",ip="10.0.0.1"}'] == 2
+    assert not any(key.startswith('ipmg_host_open_ports{source="plain.txt"') for key in metrics)
+
+
+def test_running_and_failed_scans_are_not_reported(database):
+    running = database.create_scan("live.txt", 1, {})
+    database.add_result(running, HostResult("10.0.0.1", "Active", 1.0))
+
+    assert "live.txt" not in render_metrics(database)
+
+
+def test_the_source_limit_bounds_the_series_and_says_what_it_left_out(database):
+    for name in ("a.txt", "b.txt", "c.txt"):
+        record(database, name, [HostResult("10.0.0.1", "Active", 1.0)])
+
+    text = render_metrics(database, max_sources=2)
+
+    assert 'source="c.txt"' in text and 'source="b.txt"' in text  # the newest two
+    assert 'source="a.txt"' not in text
+    assert samples(text)["ipmg_metrics_sources_omitted"] == 1
+
+
+def test_label_values_are_escaped(database):
+    record(database, 'odd "name"\\path\nnext', [HostResult("10.0.0.1", "Active", 1.0)])
+
+    assert 'source="odd \\"name\\"\\\\path\\nnext"' in render_metrics(database)
+
+
+def test_every_family_is_declared_once_even_when_empty(database):
+    text = render_metrics(database)
+
+    assert len(re.findall(r"^# TYPE ipmg_host_up gauge$", text, re.MULTILINE)) == 1
+    assert "# TYPE ipmg_scans_total counter" in text
+    assert text.endswith("\n")
+    assert samples(text)["ipmg_metrics_sources_omitted"] == 0
+
+
+def test_ipv6_hosts_are_labelled_as_written(database):
+    record(database, "v6.txt", [HostResult("fe80::1%eth0", "Active", 1.0)])
+
+    assert 'ipmg_host_up{source="v6.txt",ip="fe80::1%eth0"} 1' in render_metrics(database)
+
+
+# ------------------------------------------------------------------ endpoint
+
+
+def test_metrics_are_off_unless_asked_for(database):
+    with TestClient(create_app(database, token="t" * 20)) as client:
+        response = client.get("/metrics", headers={"Authorization": "Bearer " + "t" * 20})
+
+    assert response.status_code == 404
+
+
+def test_the_endpoint_serves_prometheus_text_with_the_token(database):
+    record(database, "targets.txt", [HostResult("10.0.0.1", "Active", 1.0)])
+    app = create_app(database, token="t" * 20, metrics_sources=5)
+
+    with TestClient(app) as client:
+        anonymous = client.get("/metrics")
+        scraped = client.get("/metrics", headers={"Authorization": "Bearer " + "t" * 20})
+
+    assert anonymous.status_code == 401
+    assert scraped.status_code == 200
+    assert scraped.headers["content-type"] == CONTENT_TYPE
+    assert 'ipmg_host_up{source="targets.txt",ip="10.0.0.1"} 1' in scraped.text
+
+
+def test_the_endpoint_stays_out_of_the_api_schema(database):
+    app = create_app(database, token="t" * 20, metrics_sources=5)
+
+    assert "/metrics" not in app.openapi()["paths"]
+
+
+def test_web_parser_metrics_flags():
+    assert build_web_parser().parse_args([]).metrics is False
+    args = build_web_parser().parse_args(["--metrics", "--metrics-sources", "3"])
+    assert (args.metrics, args.metrics_sources) == (True, 3)