nanotelemetry 0.2.0__py3-none-any.whl

nanotelemetry/__init__.py

@@ -0,0 +1,36 @@
+"""nanotelemetry — a tiny, dependency-free telemetry library.
+
+Record events, counters, gauges, and timing spans, then ship them to one or
+more exporters (console, in-memory, or your own).
+
+Basic usage::
+
+    from nanotelemetry import Telemetry, ConsoleExporter
+
+    tel = Telemetry(service="my-app", exporters=[ConsoleExporter()])
+    tel.event("user.signup", plan="pro")
+    tel.count("requests", 1, route="/home")
+
+    with tel.span("db.query", table="users"):
+        run_query()
+
+    tel.flush()
+"""
+
+from .client import Telemetry
+from .events import Event, EventKind
+from .exporters import ConsoleExporter, Exporter, MemoryExporter
+from .sysinfo import sysinfo
+
+__all__ = [
+    "Telemetry",
+    "Event",
+    "EventKind",
+    "Exporter",
+    "ConsoleExporter",
+    "MemoryExporter",
+    "sysinfo",
+    "__version__",
+]
+
+__version__ = "0.2.0"

nanotelemetry/client.py

@@ -0,0 +1,154 @@
+"""The Telemetry client — the main entry point of the library."""
+
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence, TypeVar
+
+from .events import Event, EventKind
+from .exporters import Exporter
+from .sysinfo import sysinfo
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Telemetry:
+    """Collects telemetry events and flushes them to exporters.
+
+    The client buffers events in memory and sends them to every configured
+    exporter when the buffer reaches ``batch_size`` or when :meth:`flush` is
+    called. It is safe to share a single instance across threads.
+
+    Args:
+        service: Name of the service emitting telemetry. Added to every event's
+            attributes under ``"service"``.
+        exporters: Where to send events. If omitted, events are buffered until
+            an exporter is added or :meth:`flush` is called (and then dropped).
+        tags: Attributes merged into every event, e.g. ``{"env": "prod"}``.
+        batch_size: Auto-flush once this many events are buffered. Set to 0 to
+            disable auto-flushing (flush manually).
+        include_system_info: If ``True``, collect host/OS/arch/Python/PID once
+            at construction (see :func:`nanotelemetry.sysinfo`) and merge it
+            into ``tags``. Explicit ``tags`` win on any key collision.
+    """
+
+    def __init__(
+        self,
+        service: str,
+        exporters: Optional[Sequence[Exporter]] = None,
+        tags: Optional[Dict[str, Any]] = None,
+        batch_size: int = 100,
+        include_system_info: bool = False,
+    ) -> None:
+        self.service = service
+        self.exporters: List[Exporter] = list(exporters or [])
+        base_tags = sysinfo() if include_system_info else {}
+        base_tags.update(tags or {})
+        self.tags = base_tags
+        self.batch_size = batch_size
+        self._buffer: List[Event] = []
+        self._lock = threading.Lock()
+
+    # -- recording ---------------------------------------------------------
+
+    def record(self, event: Event) -> None:
+        """Buffer a pre-built :class:`Event`, auto-flushing if the batch is full."""
+        with self._lock:
+            self._buffer.append(event)
+            should_flush = (
+                self.batch_size > 0 and len(self._buffer) >= self.batch_size
+            )
+        if should_flush:
+            self.flush()
+
+    def _emit(
+        self,
+        name: str,
+        kind: EventKind,
+        value: float | None,
+        attributes: Dict[str, Any],
+    ) -> None:
+        merged = {**self.tags, "service": self.service, **attributes}
+        self.record(Event(name=name, kind=kind, value=value, attributes=merged))
+
+    def event(self, name: str, **attributes: Any) -> None:
+        """Record a discrete event with optional attributes."""
+        self._emit(name, EventKind.EVENT, None, attributes)
+
+    def count(self, name: str, value: float = 1, **attributes: Any) -> None:
+        """Record a counter increment (defaults to 1)."""
+        self._emit(name, EventKind.COUNT, value, attributes)
+
+    def gauge(self, name: str, value: float, **attributes: Any) -> None:
+        """Record a point-in-time measurement."""
+        self._emit(name, EventKind.GAUGE, value, attributes)
+
+    # -- timing ------------------------------------------------------------
+
+    @contextmanager
+    def span(self, name: str, **attributes: Any) -> Iterator[Dict[str, Any]]:
+        """Time a block of code and record its duration in seconds.
+
+        Yields the span's attribute dict so you can attach more metadata while
+        the block runs::
+
+            with tel.span("http.request") as attrs:
+                resp = do_request()
+                attrs["status"] = resp.status
+        """
+        start = time.perf_counter()
+        span_attrs = dict(attributes)
+        try:
+            yield span_attrs
+        finally:
+            duration = time.perf_counter() - start
+            self._emit(name, EventKind.SPAN, duration, span_attrs)
+
+    def timed(self, name: Optional[str] = None, **attributes: Any) -> Callable[[F], F]:
+        """Decorator that records how long the wrapped function takes.
+
+        Defaults the span name to ``"module.qualname"`` of the function::
+
+            @tel.timed()
+            def load_data():
+                ...
+        """
+
+        def decorator(func: F) -> F:
+            span_name = name or f"{func.__module__}.{func.__qualname__}"
+
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with self.span(span_name, **attributes):
+                    return func(*args, **kwargs)
+
+            return wrapper  # type: ignore[return-value]
+
+        return decorator
+
+    # -- lifecycle ---------------------------------------------------------
+
+    def flush(self) -> None:
+        """Send all buffered events to every exporter and clear the buffer."""
+        with self._lock:
+            if not self._buffer:
+                return
+            batch = self._buffer
+            self._buffer = []
+        for exporter in self.exporters:
+            exporter.export(batch)
+
+    def close(self) -> None:
+        """Flush remaining events and close every exporter."""
+        self.flush()
+        for exporter in self.exporters:
+            exporter.close()
+
+    def __enter__(self) -> "Telemetry":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

nanotelemetry/events.py

@@ -0,0 +1,48 @@
+"""Event data model."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict
+
+
+class EventKind(str, Enum):
+    """The category of a telemetry event."""
+
+    EVENT = "event"
+    COUNT = "count"
+    GAUGE = "gauge"
+    SPAN = "span"
+
+
+@dataclass
+class Event:
+    """A single telemetry record.
+
+    Attributes:
+        name: Dotted event name, e.g. ``"user.signup"``.
+        kind: The :class:`EventKind` of this record.
+        value: Numeric payload — the increment for counts, the reading for
+            gauges, or the duration in seconds for spans. ``None`` for plain
+            events.
+        attributes: Arbitrary key/value metadata attached to the event.
+        timestamp: Unix epoch seconds when the event was created.
+    """
+
+    name: str
+    kind: EventKind = EventKind.EVENT
+    value: float | None = None
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return a JSON-serializable representation of the event."""
+        return {
+            "name": self.name,
+            "kind": self.kind.value,
+            "value": self.value,
+            "attributes": self.attributes,
+            "timestamp": self.timestamp,
+        }

nanotelemetry/exporters.py

@@ -0,0 +1,50 @@
+"""Exporters decide where telemetry events end up."""
+
+from __future__ import annotations
+
+import json
+import sys
+from abc import ABC, abstractmethod
+from typing import List, TextIO
+
+from .events import Event
+
+
+class Exporter(ABC):
+    """Base class for all exporters.
+
+    Subclass this and implement :meth:`export` to send events anywhere —
+    an HTTP endpoint, a log file, a message queue, and so on.
+    """
+
+    @abstractmethod
+    def export(self, events: List[Event]) -> None:
+        """Ship a batch of events. Called by ``Telemetry.flush()``."""
+
+    def close(self) -> None:
+        """Release any resources. Called by ``Telemetry.close()``."""
+
+
+class ConsoleExporter(Exporter):
+    """Write each event as a line of JSON to a stream (stdout by default)."""
+
+    def __init__(self, stream: TextIO | None = None) -> None:
+        self._stream = stream if stream is not None else sys.stdout
+
+    def export(self, events: List[Event]) -> None:
+        for event in events:
+            self._stream.write(json.dumps(event.to_dict()) + "\n")
+        self._stream.flush()
+
+
+class MemoryExporter(Exporter):
+    """Collect events in a list. Handy for tests and debugging."""
+
+    def __init__(self) -> None:
+        self.events: List[Event] = []
+
+    def export(self, events: List[Event]) -> None:
+        self.events.extend(events)
+
+    def clear(self) -> None:
+        self.events.clear()

nanotelemetry/sysinfo.py

@@ -0,0 +1,51 @@
+"""Collect information about the host the code is running on.
+
+Everything here uses only the standard library so the package stays
+dependency-free. Collection is best-effort: if any probe fails, that key is
+simply omitted rather than raising.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import socket
+from typing import Any, Callable, Dict
+
+
+def _safe(fn: Callable[[], Any]) -> Any | None:
+    """Return ``fn()``, or ``None`` if it raises."""
+    try:
+        return fn()
+    except Exception:
+        return None
+
+
+def sysinfo() -> Dict[str, Any]:
+    """Return a dict describing the current host and Python runtime.
+
+    Keys (any that cannot be determined are left out):
+
+    - ``host``: network hostname
+    - ``os``: operating system name, e.g. ``"Linux"``, ``"Darwin"``, ``"Windows"``
+    - ``os_release``: OS release string
+    - ``arch``: machine architecture, e.g. ``"arm64"``, ``"x86_64"``
+    - ``python``: Python version, e.g. ``"3.12.1"``
+    - ``python_impl``: interpreter implementation, e.g. ``"CPython"``, ``"PyPy"``
+    - ``pid``: current process id
+    """
+    probes: Dict[str, Callable[[], Any]] = {
+        "host": socket.gethostname,
+        "os": platform.system,
+        "os_release": platform.release,
+        "arch": platform.machine,
+        "python": platform.python_version,
+        "python_impl": platform.python_implementation,
+        "pid": os.getpid,
+    }
+    info: Dict[str, Any] = {}
+    for key, probe in probes.items():
+        value = _safe(probe)
+        if value not in (None, ""):
+            info[key] = value
+    return info

nanotelemetry-0.2.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: nanotelemetry
+Version: 0.2.0
+Summary: A tiny, dependency-free telemetry library: events, counters, gauges, and timing spans.
+Author-email: dark.soul.test.1@gmail.com
+License-Expression: MIT
+License-File: LICENSE
+Keywords: instrumentation,metrics,monitoring,observability,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nanotelemetry
+
+A tiny, dependency-free telemetry library for Python. Record events, counters,
+gauges, and timing spans, then flush them to one or more pluggable exporters.
+
+- **Zero dependencies** — pure standard library.
+- **Thread-safe** — share one client across threads.
+- **Pluggable exporters** — console, in-memory, or your own.
+- **Typed** — ships with `py.typed`.
+
+## Install
+
+```bash
+pip install nanotelemetry
+```
+
+## Quickstart
+
+```python
+from nanotelemetry import Telemetry, ConsoleExporter
+
+tel = Telemetry(
+    service="my-app",
+    exporters=[ConsoleExporter()],
+    tags={"env": "prod"},
+)
+
+# Discrete events
+tel.event("user.signup", plan="pro")
+
+# Counters and gauges
+tel.count("requests", 1, route="/home")
+tel.gauge("queue.depth", 42)
+
+# Time a block of code
+with tel.span("db.query", table="users") as attrs:
+    rows = run_query()
+    attrs["rows"] = len(rows)
+
+# ...or a whole function
+@tel.timed("compute")
+def compute():
+    ...
+
+tel.flush()   # send buffered events to exporters
+```
+
+Use it as a context manager to flush and close automatically:
+
+```python
+with Telemetry(service="my-app", exporters=[ConsoleExporter()]) as tel:
+    tel.event("startup")
+```
+
+## Event kinds
+
+| Method              | Kind    | `value` means            |
+| ------------------- | ------- | ------------------------ |
+| `event(name, **kw)` | `event` | (none)                   |
+| `count(name, n)`    | `count` | the increment            |
+| `gauge(name, x)`    | `gauge` | the reading              |
+| `span(name)`        | `span`  | duration in seconds      |
+
+Every event carries the client's `service` name plus any `tags` you configured,
+merged with the per-call attributes.
+
+## System info
+
+Pass `include_system_info=True` to automatically tag every event with details
+about the host it's running on — hostname, OS, architecture, Python version,
+and PID:
+
+```python
+tel = Telemetry(service="my-app", include_system_info=True)
+tel.event("startup")
+# attributes now include: host, os, os_release, arch, python, python_impl, pid
+```
+
+It's collected once at construction and off by default. Any keys you set
+explicitly in `tags` take precedence. You can also call the collector directly:
+
+```python
+from nanotelemetry import sysinfo
+print(sysinfo())
+# {'host': 'laptop', 'os': 'Darwin', 'arch': 'arm64', 'python': '3.12.1', ...}
+```
+
+## Batching
+
+The client buffers events and auto-flushes once `batch_size` (default 100) is
+reached. Set `batch_size=0` to disable auto-flush and call `flush()` yourself.
+
+## Custom exporters
+
+Subclass `Exporter` to send events anywhere:
+
+```python
+import json
+import urllib.request
+from nanotelemetry import Exporter
+
+class HTTPExporter(Exporter):
+    def __init__(self, url):
+        self.url = url
+
+    def export(self, events):
+        payload = json.dumps([e.to_dict() for e in events]).encode()
+        req = urllib.request.Request(
+            self.url, data=payload, headers={"Content-Type": "application/json"}
+        )
+        urllib.request.urlopen(req)
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

nanotelemetry-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nanotelemetry/__init__.py,sha256=Y5W5Itjn8gx9rJTRHYsiJkLqZyL1V5LpcWG_e8QXbNQ,849
+nanotelemetry/client.py,sha256=bV3hs_PMOYSedNu_acc6JpuUObt5nJS8yYnbywQ-6JQ,5531
+nanotelemetry/events.py,sha256=kUt9qMceE_JXjrasQIOw8sFqkzEgortYPi3zMNiEwGQ,1351
+nanotelemetry/exporters.py,sha256=ZGg8KsrGcuhJWniw73lpKtexNjhcRNidMmQjGYXxTkU,1396
+nanotelemetry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nanotelemetry/sysinfo.py,sha256=7B_L74GjIM-GQ9MFb3kw1a_80iCquce9OHAiT0-DscU,1594
+nanotelemetry-0.2.0.dist-info/METADATA,sha256=5mKewjbh5DPbkl25T77ZDcdoXKxGF1FCZ86jDqttcsw,4091
+nanotelemetry-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+nanotelemetry-0.2.0.dist-info/licenses/LICENSE,sha256=L6lI2mYr7FeulAfspovHoWyb1GQmSzl0QgZZvMWDXVU,1083
+nanotelemetry-0.2.0.dist-info/RECORD,,

nanotelemetry-0.2.0.dist-info/WHEEL

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

nanotelemetry-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nanotelemetry contributors
+
+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.