light-telemetry 0.1.0__tar.gz

light_telemetry-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+**/target
+.idea/*
+.idea_modules/
+*.iws
+*.user
+cmake-build-*/
+
+
+IDEA
+!.idea/modules.xml
+!.idea/vcs.xml
+!.idea/misc.xml
+!.idea/encodings.xml
+!.idea/runConfigurations/
+!.idea/codeStyles/
+!.idea/inspectionProfiles/
+!.idea/scopes/
+!*.iml
+!.idea/*.iml
+!.idea/modules/
+
+.idea/runConfigurations/**.local.xml
+.idea/dataSources/
+.idea/dataSources.local.xml

light_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.5
+Name: light-telemetry
+Version: 0.1.0
+Summary: UDP fire-and-forget telemetry client for LightTelemetry
+Requires-Python: >=3.11
+Requires-Dist: msgpack>=1.0

light_telemetry-0.1.0/light_telemetry/__init__.py

@@ -0,0 +1,18 @@
+"""UDP fire-and-forget telemetry client for LightTelemetry."""
+
+from . import config
+from .client import ClientStats, TelemetryClient
+from .handler import TelemetryLogHandler
+from .serialize import MTU_SAFE, encode, now_micros
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MTU_SAFE",
+    "ClientStats",
+    "TelemetryClient",
+    "TelemetryLogHandler",
+    "config",
+    "encode",
+    "now_micros",
+]

light_telemetry-0.1.0/light_telemetry/client.py

@@ -0,0 +1,200 @@
+"""UDP fire-and-forget telemetry client for LightTelemetry.
+
+Design contract (shared with the Rust and Go clients):
+
+- ``emit`` serializes one packet and sends one datagram. No buffering, no
+  retries — telemetry must never block the host.
+- A background thread watches reverse heartbeats from the server. When they
+  stop, ``degraded`` flips and ``emit`` drops before serializing.
+- Oversized packets are truncated (``payload -> {"truncated": true}``).
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import threading
+import time
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import Any, Self
+
+from . import config as _config
+from .serialize import encode, now_micros
+
+
+@dataclass
+class ClientStats:
+    """Client-side counters for diagnostics and tests."""
+
+    encoded: int = 0
+    sent: int = 0
+    dropped: int = 0
+    truncated: int = 0
+    errors: int = 0
+
+
+@dataclass
+class _Watcher:
+    thread: threading.Thread | None = field(default=None)
+    stop: threading.Event = field(default_factory=threading.Event)
+
+
+class TelemetryClient:
+    """One UDP socket plus an optional heartbeat watcher thread."""
+
+    def __init__(
+        self,
+        server_addr: tuple[str, int],
+        host_id: str,
+        host_class: str,
+        *,
+        use_msgpack: bool = False,
+        heartbeat_timeout: float | None = 3.0,
+    ) -> None:
+        """Bind an ephemeral UDP socket toward ``server_addr``.
+
+        ``heartbeat_timeout`` (seconds) is the liveness window for the
+        reverse-heartbeat watcher; ``None`` disables the watcher.
+        """
+        self._server_addr = server_addr
+        self._host_id = host_id
+        self._host_class = host_class
+        self._use_msgpack = use_msgpack
+        self._heartbeat_timeout = heartbeat_timeout
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self._sock.bind(("0.0.0.0", 0))
+        self._degraded = threading.Event()
+        self._watcher = _Watcher()
+        self.stats = ClientStats()
+
+    @classmethod
+    def local(
+        cls,
+        host_id: str,
+        host_class: str,
+        *,
+        config_path: str | None = None,
+        use_msgpack: bool = False,
+    ) -> TelemetryClient:
+        """Localhost default: adopt the server's ``telemetry.toml``.
+
+        Reads ``config_path`` or, absent, ``/etc/telemetry.toml`` then
+        ``$HOME/.config/telemetry.toml`` (first hit wins — same as the
+        daemon). ``udp_bind`` becomes the target with wildcards mapped
+        to loopback; ``heartbeat_ms × 3`` becomes the liveness window.
+        Missing files or keys fall back to ``127.0.0.1:9876`` / 3 s.
+        """
+        srv, _ = _config.load(config_path)
+        host, port = _config.localize(srv.get("udp_bind", "0.0.0.0:9876"))
+        hb_ms = srv.get("heartbeat_ms", _config.DEFAULT_HEARTBEAT_MS)
+        return cls(
+            (host, port),
+            host_id,
+            host_class,
+            use_msgpack=use_msgpack,
+            heartbeat_timeout=hb_ms * 3 / 1000.0,
+        )
+
+    # -- lifecycle ------------------------------------------------------
+
+    def start(self) -> Self:
+        """Spawn the heartbeat watcher (if configured). Idempotent."""
+        if self._heartbeat_timeout is None or self._watcher.thread is not None:
+            return self
+        self._watcher.thread = threading.Thread(
+            target=self._watch,
+            name="light-telemetry-heartbeat",
+            daemon=True,
+        )
+        self._watcher.thread.start()
+        return self
+
+    def stop(self) -> None:
+        """Stop the watcher and release the socket. Safe to call twice."""
+        self._watcher.stop.set()
+        if self._watcher.thread is not None:
+            self._watcher.thread.join(timeout=2.0)
+            self._watcher.thread = None
+        self._sock.close()
+
+    close = stop
+
+    def __enter__(self) -> Self:
+        return self.start()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.stop()
+
+    # -- state ----------------------------------------------------------
+
+    @property
+    def degraded(self) -> bool:
+        """Whether the server is currently considered unreachable."""
+        return self._degraded.is_set()
+
+    @property
+    def local_addr(self) -> tuple[str, int]:
+        """Local socket address."""
+        host, port = self._sock.getsockname()
+        return str(host), int(port)
+
+    # -- emission -------------------------------------------------------
+
+    def emit(self, topic: str, payload: dict[str, Any] | None = None) -> None:
+        """Emit one event. Drops silently when degraded; never raises."""
+        if self.degraded:
+            self.stats.dropped += 1
+            return
+        packet = {
+            "topic": topic,
+            "id": self._host_id,
+            "class": self._host_class,
+            "ts": now_micros(),
+            "payload": payload if payload is not None else {},
+        }
+        self.stats.encoded += 1
+        try:
+            data, truncated = encode(packet, self._use_msgpack)
+            if truncated:
+                self.stats.truncated += 1
+            self._sock.sendto(data, self._server_addr)
+            self.stats.sent += 1
+        except Exception:  # noqa: BLE001 — fire-and-forget: never raise to the caller
+            self.stats.errors += 1
+
+    # -- heartbeat watcher -----------------------------------------------
+
+    def _watch(self) -> None:
+        assert self._heartbeat_timeout is not None
+        timeout = self._heartbeat_timeout
+        read_timeout = min(max(timeout / 4.0, 0.02), 0.2)
+        self._sock.settimeout(read_timeout)
+        last_hb: float | None = None
+        while not self._watcher.stop.is_set():
+            try:
+                data, addr = self._sock.recvfrom(2048)
+            except TimeoutError:
+                data = b""
+                addr = ("", 0)
+            except OSError:
+                break
+            if addr == self._server_addr:
+                try:
+                    msg = json.loads(data)
+                    if isinstance(msg, dict) and msg.get("type") == "hb":
+                        last_hb = time.monotonic()
+                except (ValueError, UnicodeDecodeError):
+                    pass
+            stale = (
+                (time.monotonic() - last_hb) > timeout if last_hb is not None else False
+            )
+            if stale:
+                self._degraded.set()
+            else:
+                self._degraded.clear()

light_telemetry-0.1.0/light_telemetry/config.py

@@ -0,0 +1,71 @@
+"""Discover the server's ``telemetry.toml`` for localhost clients.
+
+Same search order as the server: explicit path, else
+``/etc/telemetry.toml``, else ``$HOME/.config/telemetry.toml``; the first
+existing file wins. Only the keys the client consumes are read —
+server-only keys are ignored.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import TypedDict
+
+ETC_PATH = Path("/etc/telemetry.toml")
+USER_PATH = Path.home() / ".config" / "telemetry.toml"
+
+DEFAULT_BIND = ("0.0.0.0", 9876)
+DEFAULT_HEARTBEAT_MS = 1000
+
+
+class ServerConfig(TypedDict, total=False):
+    """Server keys a client consumes."""
+
+    udp_bind: str
+    heartbeat_ms: int
+
+
+def _default_paths() -> list[Path]:
+    paths = [ETC_PATH]
+    home = os.environ.get("HOME")
+    if home:
+        paths.append(Path(home) / ".config" / "telemetry.toml")
+    return paths
+
+
+def load(path: str | Path | None = None) -> tuple[ServerConfig, Path | None]:
+    """Load the server config.
+
+    ``path`` must exist (``FileNotFoundError`` propagates); without it the
+    first existing default path wins; absent files → empty config.
+    """
+    if path is not None:
+        p = Path(path)
+        return _parse(p), p
+    for cand in _default_paths():
+        if cand.is_file():
+            return _parse(cand), cand
+    return ServerConfig(), None
+
+
+def _parse(p: Path) -> ServerConfig:
+    data = tomllib.loads(p.read_text())
+    cfg: ServerConfig = {}
+    if isinstance(v := data.get("udp_bind"), str):
+        cfg["udp_bind"] = v
+    if isinstance(v := data.get("heartbeat_ms"), int):
+        cfg["heartbeat_ms"] = v
+    return cfg
+
+
+def localize(bind: str) -> tuple[str, int]:
+    """Map a bind address to a send target: wildcard → loopback."""
+    host, _, port = bind.rpartition(":")
+    host = host.strip("[]")
+    if host in ("0.0.0.0", "*"):
+        return "127.0.0.1", int(port)
+    if host in ("::", "::1"):
+        return "::1", int(port)
+    return host or "0.0.0.0", int(port)

light_telemetry-0.1.0/light_telemetry/handler.py

@@ -0,0 +1,46 @@
+"""``logging.Handler`` that forwards records to a ``TelemetryClient``."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from .client import TelemetryClient
+
+#: Attributes present on every LogRecord; everything else is user ``extra``.
+_RESERVED = frozenset(vars(logging.makeLogRecord({}))) | {
+    "taskName",
+    "message",
+    "asctime",
+}
+
+
+class TelemetryLogHandler(logging.Handler):
+    """Emit each ``LogRecord`` as a telemetry packet under ``topic``.
+
+    The payload carries ``level``, ``logger``, ``message``, plus every
+    non-reserved record attribute (``extra={...}`` fields). Handler
+    failures are reported via ``handleError`` — never raised.
+    """
+
+    def __init__(self, client: TelemetryClient, topic: str = "logger") -> None:
+        super().__init__()
+        self._client = client
+        self._topic = topic
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            payload: dict[str, Any] = {
+                "level": record.levelname,
+                "logger": record.name,
+                "message": record.getMessage(),
+            }
+            for key, value in record.__dict__.items():
+                if key not in _RESERVED and not key.startswith("_"):
+                    payload[key] = value
+            if record.exc_info:
+                formatter = self.formatter or logging.Formatter()
+                payload["exc_info"] = formatter.formatException(record.exc_info)
+            self._client.emit(self._topic, payload)
+        except Exception:  # noqa: BLE001 — logging.Handler contract: emit never raises
+            self.handleError(record)

light_telemetry-0.1.0/light_telemetry/serialize.py

@@ -0,0 +1,37 @@
+"""Wire packet encoding (JSON or MessagePack) with MTU truncation."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, cast
+
+import msgpack
+
+#: Maximum wire size before the payload is replaced by a truncation marker.
+MTU_SAFE = 1432
+
+
+def now_micros() -> int:
+    """Current UNIX epoch time in microseconds."""
+    return time.time_ns() // 1000
+
+
+def _dumps(packet: dict[str, Any], use_msgpack: bool) -> bytes:
+    if use_msgpack:
+        packed = msgpack.packb(packet, default=repr)
+        return cast(bytes, packed)
+    return json.dumps(packet, separators=(",", ":"), default=str).encode()
+
+
+def encode(packet: dict[str, Any], use_msgpack: bool) -> tuple[bytes, bool]:
+    """Encode ``packet``; truncate payload over :data:`MTU_SAFE`.
+
+    Returns ``(wire_bytes, was_truncated)``.
+    """
+    data = _dumps(packet, use_msgpack)
+    if len(data) <= MTU_SAFE:
+        return data, False
+    truncated = {**packet, "payload": {"truncated": True}}
+    data = _dumps(truncated, use_msgpack)
+    return data, True

light_telemetry-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "light-telemetry"
+version = "0.1.0"
+description = "UDP fire-and-forget telemetry client for LightTelemetry"
+requires-python = ">=3.11"
+dependencies = ["msgpack>=1.0"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "jsonschema>=4",
+    "ruff>=0.7",
+    "mypy>=1.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["light_telemetry"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+
+[[tool.mypy.overrides]]
+module = "msgpack"
+ignore_missing_imports = true

light_telemetry-0.1.0/tests/test_client.py

@@ -0,0 +1,222 @@
+"""Client and handler tests: live UDP, degradation, handler mapping."""
+
+import json
+import logging
+import socket
+import threading
+import time
+from typing import Any
+
+import msgpack
+
+from light_telemetry import TelemetryClient, TelemetryLogHandler
+
+
+def _recv(sock: socket.socket, timeout: float = 2.0) -> tuple[bytes, Any]:
+    sock.settimeout(timeout)
+    return sock.recvfrom(65535)
+
+
+def _server() -> socket.socket:
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    s.bind(("127.0.0.1", 0))
+    return s
+
+
+def _client(server: socket.socket) -> TelemetryClient:
+    return TelemetryClient(
+        server.getsockname(), "test-host", "test-class", heartbeat_timeout=None
+    )
+
+
+def test_emit_sends_json_datagram() -> None:
+    server = _server()
+    client = _client(server)
+    client.emit("t", {"k": 1})
+    data, _ = _recv(server)
+    v = json.loads(data)
+    assert v["topic"] == "t"
+    assert v["id"] == "test-host"
+    assert v["class"] == "test-class"
+    assert v["ts"] > 0
+    assert v["payload"]["k"] == 1
+    assert client.stats.sent == 1
+    assert client.stats.encoded == 1
+    client.stop()
+
+
+def test_emit_sends_msgpack_when_configured() -> None:
+    server = _server()
+    client = TelemetryClient(
+        server.getsockname(), "h", "c", use_msgpack=True, heartbeat_timeout=None
+    )
+    client.emit("t", {"k": 1})
+    data, _ = _recv(server)
+    assert data[0:1] != b"{"
+    assert msgpack.unpackb(data)["topic"] == "t"
+    client.stop()
+
+
+def test_emit_to_unreachable_server_does_not_raise() -> None:
+    client = TelemetryClient(("127.0.0.1", 9), "h", "c", heartbeat_timeout=None)
+    client.emit("t", {})
+    assert client.stats.sent == 1
+    client.stop()
+
+
+def test_degraded_drops_before_serialization() -> None:
+    server = _server()
+    client = _client(server)
+    client._degraded.set()
+    encoded_before = client.stats.encoded
+    client.emit("t", {"expensive": object()})
+    assert client.stats.encoded == encoded_before
+    assert client.stats.dropped == 1
+    assert client.stats.sent == 0
+    client.stop()
+
+
+def test_socket_error_swallowed() -> None:
+    client = TelemetryClient(("127.0.0.1", 9), "h", "c", heartbeat_timeout=None)
+    client._sock.close()  # force sendto to fail
+    client.emit("t", {})
+    assert client.stats.errors == 1
+
+
+def test_stop_without_start_is_safe() -> None:
+    client = TelemetryClient(("127.0.0.1", 9), "h", "c")
+    client.stop()
+    client.stop()  # idempotent
+
+
+def test_watcher_marks_degraded_when_heartbeats_stop() -> None:
+    server = _server()
+    server_addr = server.getsockname()
+    client = TelemetryClient(server_addr, "h", "c", heartbeat_timeout=0.15).start()
+    try:
+        client_addr = client.local_addr
+        hb = json.dumps({"type": "hb", "srv_ts": 1}).encode()
+
+        # Heartbeats → stays healthy.
+        for _ in range(4):
+            server.sendto(hb, client_addr)
+            time.sleep(0.04)
+        time.sleep(0.08)
+        assert not client.degraded
+
+        # Silence → degraded.
+        time.sleep(0.4)
+        assert client.degraded
+
+        # Resume inside the window → recovers.
+        for _ in range(3):
+            server.sendto(hb, client_addr)
+            time.sleep(0.04)
+        time.sleep(0.06)
+        assert not client.degraded
+    finally:
+        client.stop()
+
+
+def test_watcher_ignores_non_heartbeat_datagrams() -> None:
+    server = _server()
+    client = TelemetryClient(
+        server.getsockname(), "h", "c", heartbeat_timeout=0.15
+    ).start()
+    try:
+        server.sendto(b"random junk", client.local_addr)
+        time.sleep(0.3)
+        assert not client.degraded  # never saw a real hb
+    finally:
+        client.stop()
+
+
+def test_context_manager_lifecycle() -> None:
+    server = _server()
+    with TelemetryClient(
+        server.getsockname(), "h", "c", heartbeat_timeout=None
+    ) as client:
+        client.emit("t", {})
+    assert client.stats.sent == 1
+
+
+# -- handler --------------------------------------------------------------
+
+
+def _logging_capture(server: socket.socket) -> tuple[TelemetryClient, logging.Logger]:
+    client = _client(server)
+    logger = logging.getLogger("telemetry.test.capture")
+    logger.handlers.clear()
+    logger.setLevel(logging.DEBUG)
+    logger.addHandler(TelemetryLogHandler(client, topic="logger"))
+    return client, logger
+
+
+def test_handler_emits_record_with_extra_fields() -> None:
+    server = _server()
+    client, logger = _logging_capture(server)
+    logger.info("login %s", "ok", extra={"user": "alice", "answer": 42})
+    data, _ = _recv(server)
+    v = json.loads(data)
+    assert v["topic"] == "logger"
+    p = v["payload"]
+    assert p["level"] == "INFO"
+    assert p["logger"] == "telemetry.test.capture"
+    assert p["message"] == "login ok"
+    assert p["user"] == "alice"
+    assert p["answer"] == 42
+    client.stop()
+
+
+def test_handler_without_extra() -> None:
+    server = _server()
+    client, logger = _logging_capture(server)
+    logger.warning("plain")
+    data, _ = _recv(server)
+    p = json.loads(data)["payload"]
+    assert p["message"] == "plain"
+    assert p["level"] == "WARNING"
+    client.stop()
+
+
+def test_handler_includes_exc_info() -> None:
+    server = _server()
+    client, logger = _logging_capture(server)
+    try:
+        raise ValueError("boom")
+    except ValueError:
+        logger.exception("op failed")
+    data, _ = _recv(server)
+    p = json.loads(data)["payload"]
+    assert "ValueError: boom" in p["exc_info"]
+    client.stop()
+
+
+def test_handler_survives_unreachable_server() -> None:
+    client = TelemetryClient(("127.0.0.1", 9), "h", "c", heartbeat_timeout=None)
+    logger = logging.getLogger("telemetry.test.dead")
+    logger.handlers.clear()
+    logger.addHandler(TelemetryLogHandler(client))
+    logging.raiseExceptions = False  # simulate production handler behavior
+    try:
+        logger.error("nothing hears this")  # must not raise
+    finally:
+        logging.raiseExceptions = True
+        client.stop()
+
+
+def test_concurrent_emit_is_thread_safe_enough() -> None:
+    server = _server()
+    client = _client(server)
+
+    def worker() -> None:
+        for _ in range(20):
+            client.emit("t", {})
+
+    threads = [threading.Thread(target=worker) for _ in range(4)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+    assert client.stats.encoded == 80
+    client.stop()