light-telemetry 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+light_telemetry/__init__.py,sha256=Udt4dIN-PPqsUG86t0gCeXL_mXUYPrzXthJdWjS2u2g,396
+light_telemetry/client.py,sha256=keS4HWiTlsJzKJRgPdoM7aOhzpcVgUhcT-F-_rWSlbg,6601
+light_telemetry/config.py,sha256=dZPKr7C6yPGdHj5nxviiCKl9lzKnemP6Nl284vgkPrU,2002
+light_telemetry/handler.py,sha256=Yp151DO38wT8PEpMjhkwRGZSzvbpbENoAtsIdwbUqIo,1641
+light_telemetry/serialize.py,sha256=byDRsP0FzcfqV5YV3oQkW3pxBOWIb2nVzaUs_Obkcmo,1048
+light_telemetry-0.1.0.dist-info/METADATA,sha256=pE9WtEbd7ikEXy5CzlfdlPfEAH3ZF7cVOllhqrX47Bc,176
+light_telemetry-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+light_telemetry-0.1.0.dist-info/RECORD,,

light_telemetry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any