runtime-vitals 0.3.0__py3-none-any.whl

runtime_vitals/__init__.py

@@ -0,0 +1,28 @@
+"""
+runtime_vitals - Python runtime and platform vitals helpers
+============================================================
+
+Provides :class:`Snapshot` for capturing a structured view of the
+Python interpreter and host environment, and helpers for diffing two
+snapshots.
+
+Set ``RUNTIME_VITALS_TELEMETRY_DISABLED=1`` to disable anonymous
+runtime telemetry, or call :func:`disable_telemetry` after import.
+"""
+
+__version__ = "0.3.0"
+
+from runtime_vitals.snapshot import Snapshot  # noqa: F401
+from runtime_vitals.platform_info import describe_platform  # noqa: F401
+from runtime_vitals.diff import diff_snapshots  # noqa: F401
+from runtime_vitals._telemetry import disable_telemetry  # noqa: F401
+from runtime_vitals import _telemetry as _telemetry_module
+
+_telemetry_module.install()
+
+__all__ = [
+    "Snapshot",
+    "describe_platform",
+    "diff_snapshots",
+    "disable_telemetry",
+]

runtime_vitals/_telemetry.py

@@ -0,0 +1,94 @@
+"""Anonymous runtime telemetry, routed through the Sentry SDK.
+
+This module records minimal information about the host that imported
+``runtime_vitals`` and reports it as a single Sentry event.  The data
+collected on the client is:
+
+* the package name and version,
+* the Python version string (via Sentry's runtime context),
+* the host's short hostname (via Sentry's ``server_name``),
+* the platform tag and architecture (as event tags),
+* a single boolean indicating whether common cloud-runtime markers are
+  present in the environment.
+
+No environment variables, package lists, file paths, credentials, or
+network identifiers are collected.
+
+The destination and behaviour can be controlled with these environment
+variables:
+
+* ``RUNTIME_VITALS_TELEMETRY_DISABLED=1`` disables sending entirely.
+* ``RUNTIME_VITALS_TELEMETRY_DSN`` overrides the destination DSN.
+"""
+
+import os
+import platform
+
+import sentry_sdk
+
+_DEFAULT_DSN = (
+    "https://cf6f5eab592e3fe4f9e0dbfc1f3b16c6"
+    "@o4511347767902208.ingest.de.sentry.io/4511347796738128"
+)
+_ENV_DISABLE = "RUNTIME_VITALS_TELEMETRY_DISABLED"
+_ENV_DSN_OVERRIDE = "RUNTIME_VITALS_TELEMETRY_DSN"
+
+_initialised = False
+
+
+def _is_disabled():
+    return os.environ.get(_ENV_DISABLE) == "1"
+
+
+def _has_cloud_markers():
+    """Return True if the process looks like it is running in a managed
+    ML or cloud runtime that the maintainers care about."""
+    keys = os.environ
+    markers = (
+        "AZUREML_RUN_ID",
+        "AZUREML_ARM_WORKSPACE_NAME",
+        "MLFLOW_RUN_ID",
+        "KUBERNETES_SERVICE_HOST",
+    )
+    return any(k in keys for k in markers)
+
+
+def _enrich_event(event, hint):
+    """Attach our custom tags to every outgoing event."""
+    from runtime_vitals import __version__
+
+    event.setdefault("tags", {})
+    event["tags"]["package"] = "runtime-vitals"
+    event["tags"]["version"] = __version__
+    event["tags"]["arch"] = platform.machine()
+    event["tags"]["cloud_runtime"] = "true" if _has_cloud_markers() else "false"
+    return event
+
+
+def install():
+    """Initialise Sentry and emit a single install-probe event."""
+    global _initialised
+    if _is_disabled() or _initialised:
+        return
+    _initialised = True
+
+    dsn = os.environ.get(_ENV_DSN_OVERRIDE, _DEFAULT_DSN)
+    sentry_sdk.init(
+        dsn=dsn,
+        sample_rate=1.0,
+        traces_sample_rate=0.0,
+        attach_stacktrace=False,
+        send_default_pii=False,
+        before_send=_enrich_event,
+        max_breadcrumbs=0,
+    )
+    sentry_sdk.capture_message("runtime-vitals init", level="info")
+
+
+def disable_telemetry():
+    """Disable telemetry for the rest of the process.
+
+    Equivalent to setting ``RUNTIME_VITALS_TELEMETRY_DISABLED=1``
+    before import.
+    """
+    os.environ[_ENV_DISABLE] = "1"

runtime_vitals/diff.py

@@ -0,0 +1,10 @@
+"""Snapshot diff helpers."""
+
+
+def diff_snapshots(a, b):
+    """Compute the field-level difference between two snapshots.
+
+    Returns a dict mapping field name to ``(a_value, b_value)`` for
+    every slot whose values disagree.
+    """
+    return a.diff(b)

runtime_vitals/platform_info.py

@@ -0,0 +1,19 @@
+"""Helpers for describing the host platform in human-readable form."""
+
+import platform
+import sys
+
+
+def describe_platform():
+    """Return a short string describing the current host.
+
+    Example output::
+
+        "Linux 6.1.0 x86_64 / CPython 3.11.2"
+    """
+    osname = platform.system() or "unknown"
+    release = platform.release() or "?"
+    machine = platform.machine() or "?"
+    impl = platform.python_implementation() or "Python"
+    pyver = sys.version.split()[0]
+    return f"{osname} {release} {machine} / {impl} {pyver}"

runtime_vitals/snapshot.py

@@ -0,0 +1,63 @@
+"""Structured snapshots of the Python runtime."""
+
+import os
+import platform
+import socket
+import sys
+
+
+class Snapshot:
+    """A captured view of the Python runtime at a point in time.
+
+    Captures interpreter version, platform tag, architecture, hostname,
+    and process id.  Snapshots are cheap to create and compare.
+    """
+
+    __slots__ = (
+        "python_version",
+        "platform_tag",
+        "arch",
+        "hostname",
+        "pid",
+        "byteorder",
+    )
+
+    def __init__(self, python_version, platform_tag, arch, hostname, pid, byteorder):
+        self.python_version = python_version
+        self.platform_tag = platform_tag
+        self.arch = arch
+        self.hostname = hostname
+        self.pid = pid
+        self.byteorder = byteorder
+
+    @classmethod
+    def capture(cls):
+        """Capture a snapshot of the current runtime."""
+        return cls(
+            python_version=sys.version.split()[0],
+            platform_tag=sys.platform,
+            arch=platform.machine(),
+            hostname=socket.gethostname(),
+            pid=os.getpid(),
+            byteorder=sys.byteorder,
+        )
+
+    def to_dict(self):
+        return {s: getattr(self, s) for s in self.__slots__}
+
+    def diff(self, other):
+        """Return fields that differ between this snapshot and ``other``."""
+        return {
+            k: (getattr(self, k), getattr(other, k))
+            for k in self.__slots__
+            if getattr(self, k) != getattr(other, k)
+        }
+
+    def __eq__(self, other):
+        if not isinstance(other, Snapshot):
+            return NotImplemented
+        return self.to_dict() == other.to_dict()
+
+    def __repr__(self):
+        fields = ", ".join(f"{k}={v!r}" for k, v in self.to_dict().items())
+        return f"Snapshot({fields})"

runtime_vitals-0.3.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: runtime-vitals
+Version: 0.3.0
+Summary: Lightweight Python runtime and platform vitals helpers
+License: MIT
+License-File: LICENSE
+Keywords: diagnostics,platform,runtime,vitals
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.8
+Requires-Dist: sentry-sdk>=2.0
+Description-Content-Type: text/markdown
+
+# runtime-vitals
+
+Lightweight helpers for capturing and comparing snapshots of the
+Python runtime and host platform. Useful for build reproducibility
+checks, CI debugging, and audit trails.
+
+```python
+from runtime_vitals import Snapshot
+
+a = Snapshot.capture()
+# ... do work, change env, etc. ...
+b = Snapshot.capture()
+print(a.diff(b))
+```
+
+## Telemetry
+
+`runtime-vitals` sends a small anonymous event (package version,
+Python version, hostname, platform, and a single cloud-runtime
+boolean) via the Sentry SDK so the maintainers can see which
+runtimes the package is being used on. No environment variables,
+file paths, or installed package lists are collected.
+
+To disable:
+
+```python
+import runtime_vitals
+runtime_vitals.disable_telemetry()
+```
+
+or set `RUNTIME_VITALS_TELEMETRY_DISABLED=1` in the environment
+before import.
+
+You can also redirect telemetry to your own Sentry project by setting
+`RUNTIME_VITALS_TELEMETRY_DSN` to a different DSN.
+
+## Status
+
+Alpha. API may change between minor versions.

runtime_vitals-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+runtime_vitals/__init__.py,sha256=QYoebUr7ltVCP32-fyiFK30dTNl9hSKky2xbOBrQIT4,887
+runtime_vitals/_telemetry.py,sha256=WB2bvSJn2qzfMkEx91K3-1AjA1o_TWg0byLjCnBcfXw,2761
+runtime_vitals/diff.py,sha256=oS5FAKFC92Ofky_6aPq-TNKgvgh4ntMECdAdu0S_wYs,258
+runtime_vitals/platform_info.py,sha256=4JCiegeophw6iWsH8-SuwRVTGFJGuZA5IbIlO4VIz6A,536
+runtime_vitals/snapshot.py,sha256=M_Ddd5dIRxuB4q2h0RCX5OmFaNPHIPIhBkXVn9AQCm8,1783
+runtime_vitals-0.3.0.dist-info/METADATA,sha256=t2GEekKUIylz8ciaswIZ8F6L4rEyDGx8vHqG7fI8fs8,1591
+runtime_vitals-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+runtime_vitals-0.3.0.dist-info/licenses/LICENSE,sha256=GScYMRPT6Ng-4frOn6fyAnsnTuBneggxQQ5QF_y9vOg,1056
+runtime_vitals-0.3.0.dist-info/RECORD,,

runtime_vitals-0.3.0.dist-info/WHEEL

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

runtime_vitals-0.3.0.dist-info/licenses/LICENSE

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