viktorbarzin-telemetry 0.1.0__tar.gz

viktorbarzin_telemetry-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+
+# Go
+go/coverage.out
+
+# Android / Gradle
+.gradle/
+android/**/build/
+local.properties
+.idea/
+*.iml
+
+# Editors and OS
+.DS_Store
+
+# agents
+.worktrees/

viktorbarzin_telemetry-0.1.0/LICENSE

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

viktorbarzin_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: viktorbarzin-telemetry
+Version: 0.1.0
+Summary: Product events, errors and JSON logs to the viktorbarzin.me telemetry standard
+Project-URL: Source, https://github.com/ViktorBarzin/telemetry
+Author: Viktor Barzin
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: segment-analytics-python<3,>=2.3
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk<3,>=2.0; extra == 'sentry'
+Description-Content-Type: text/markdown
+
+# viktorbarzin-telemetry
+
+The Python client for the viktorbarzin.me telemetry standard: Product events
+through Segment's `segment-analytics-python` to our Event pipeline, errors
+through `sentry-sdk` to GlitchTip, and logs as one OpenTelemetry-shaped JSON
+object per line on stdout.
+
+```sh
+pip install viktorbarzin-telemetry            # events and logs
+pip install "viktorbarzin-telemetry[sentry]"  # plus Sentry
+```
+
+```python
+import logging
+import viktorbarzin_telemetry as telemetry
+
+telemetry.setup_logging(service_name="tv", service_version="1.4.0")
+telemetry.configure(
+    app="tv",
+    write_key=settings.segment_write_key,
+    release="1.4.0",
+    environment="production",  # or set TELEMETRY_ENVIRONMENT=production
+    host=settings.event_pipeline_url,  # or set TELEMETRY_HOST
+    dsn=settings.sentry_dsn,  # https://<key>@tv.viktorbarzin.me/_t/x/<project id>
+)
+
+with telemetry.log_context(enduser_id=user.sub):
+    logging.getLogger(__name__).info("recording started", extra={"channel_id": 4})
+    telemetry.track("recording.started", {"channel_id": 4})
+
+telemetry.flush()  # before exit
+```
+
+- `host` is the Event pipeline's base URL, from the argument or
+  `TELEMETRY_HOST`. Inside our cluster it is the event-pipeline Service's URL;
+  elsewhere use `telemetry.public_host("tv.viktorbarzin.me")`. Production
+  without a host raises `ValueError`.
+- Nothing is sent unless the environment is `production`. Invalid events
+  are validated in every environment, dropped and logged as a warning.
+- `track` takes `userId` from `log_context(enduser_id=...)` and `anonymousId`
+  from `log_context(anonymous_id=...)`, or a fresh random id.
+- `EnduserMiddleware(app, resolve_user=...)` sets `enduser.id` per request in
+  any ASGI app. `resolve_user` gets the ASGI scope and returns the Person's
+  Authentik `sub` or None, directly or as an awaitable.
+- `trace_id` and `span_id` come from the active OpenTelemetry span when
+  `opentelemetry-api` is installed, else from `log_context`.
+- The JSON formatter masks the write key, values passed as `secrets=`, and
+  bearer tokens, Basic credentials, JWTs and PEM blocks.
+
+The standard itself is in the repository README.

viktorbarzin_telemetry-0.1.0/README.md

@@ -0,0 +1,50 @@
+# viktorbarzin-telemetry
+
+The Python client for the viktorbarzin.me telemetry standard: Product events
+through Segment's `segment-analytics-python` to our Event pipeline, errors
+through `sentry-sdk` to GlitchTip, and logs as one OpenTelemetry-shaped JSON
+object per line on stdout.
+
+```sh
+pip install viktorbarzin-telemetry            # events and logs
+pip install "viktorbarzin-telemetry[sentry]"  # plus Sentry
+```
+
+```python
+import logging
+import viktorbarzin_telemetry as telemetry
+
+telemetry.setup_logging(service_name="tv", service_version="1.4.0")
+telemetry.configure(
+    app="tv",
+    write_key=settings.segment_write_key,
+    release="1.4.0",
+    environment="production",  # or set TELEMETRY_ENVIRONMENT=production
+    host=settings.event_pipeline_url,  # or set TELEMETRY_HOST
+    dsn=settings.sentry_dsn,  # https://<key>@tv.viktorbarzin.me/_t/x/<project id>
+)
+
+with telemetry.log_context(enduser_id=user.sub):
+    logging.getLogger(__name__).info("recording started", extra={"channel_id": 4})
+    telemetry.track("recording.started", {"channel_id": 4})
+
+telemetry.flush()  # before exit
+```
+
+- `host` is the Event pipeline's base URL, from the argument or
+  `TELEMETRY_HOST`. Inside our cluster it is the event-pipeline Service's URL;
+  elsewhere use `telemetry.public_host("tv.viktorbarzin.me")`. Production
+  without a host raises `ValueError`.
+- Nothing is sent unless the environment is `production`. Invalid events
+  are validated in every environment, dropped and logged as a warning.
+- `track` takes `userId` from `log_context(enduser_id=...)` and `anonymousId`
+  from `log_context(anonymous_id=...)`, or a fresh random id.
+- `EnduserMiddleware(app, resolve_user=...)` sets `enduser.id` per request in
+  any ASGI app. `resolve_user` gets the ASGI scope and returns the Person's
+  Authentik `sub` or None, directly or as an awaitable.
+- `trace_id` and `span_id` come from the active OpenTelemetry span when
+  `opentelemetry-api` is installed, else from `log_context`.
+- The JSON formatter masks the write key, values passed as `secrets=`, and
+  bearer tokens, Basic credentials, JWTs and PEM blocks.
+
+The standard itself is in the repository README.

viktorbarzin_telemetry-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "viktorbarzin-telemetry"
+version = "0.1.0"
+description = "Product events, errors and JSON logs to the viktorbarzin.me telemetry standard"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Viktor Barzin" }]
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = ["segment-analytics-python>=2.3,<3"]
+
+[project.optional-dependencies]
+sentry = ["sentry-sdk>=2.0,<3"]
+otel = ["opentelemetry-api>=1.20"]
+
+[project.urls]
+Source = "https://github.com/ViktorBarzin/telemetry"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "hypothesis>=6.100",
+    "mypy>=1.11",
+    "ruff>=0.6",
+    "sentry-sdk>=2.0,<3",
+    "opentelemetry-api>=1.20",
+    "opentelemetry-sdk>=1.20",
+    "types-requests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/viktorbarzin_telemetry"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+mypy_path = "stubs"
+files = ["src", "tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "ANN"]

viktorbarzin_telemetry-0.1.0/src/viktorbarzin_telemetry/__init__.py

@@ -0,0 +1,58 @@
+"""Client library for the viktorbarzin.me telemetry standard.
+
+Product events go to the Event pipeline through Segment's SDK, errors to
+GlitchTip through Sentry's, and logs to stdout as OpenTelemetry-shaped JSON.
+"""
+
+from ._asgi import EnduserMiddleware
+from ._config import (
+    ENVIRONMENT_VARIABLE,
+    HOST_VARIABLE,
+    PRODUCTION,
+    Config,
+    public_host,
+    resolve_environment,
+    resolve_host,
+)
+from ._context import LogContext, current_context, log_context
+from ._events import EventClient, Telemetry, configure, flush, identify, track
+from ._logging import JsonFormatter, setup_logging
+from ._scrub import Scrubber, register_secret
+from ._sentry import init_sentry
+from ._validation import (
+    MAX_PROPERTIES_LENGTH,
+    JsonValue,
+    Properties,
+    event_name_problem,
+    properties_problem,
+)
+
+__all__ = [
+    "ENVIRONMENT_VARIABLE",
+    "HOST_VARIABLE",
+    "MAX_PROPERTIES_LENGTH",
+    "PRODUCTION",
+    "Config",
+    "EnduserMiddleware",
+    "EventClient",
+    "JsonFormatter",
+    "JsonValue",
+    "LogContext",
+    "Properties",
+    "Scrubber",
+    "Telemetry",
+    "configure",
+    "current_context",
+    "event_name_problem",
+    "flush",
+    "identify",
+    "init_sentry",
+    "log_context",
+    "properties_problem",
+    "public_host",
+    "register_secret",
+    "resolve_environment",
+    "resolve_host",
+    "setup_logging",
+    "track",
+]

viktorbarzin_telemetry-0.1.0/src/viktorbarzin_telemetry/_asgi.py

@@ -0,0 +1,39 @@
+"""ASGI middleware that puts the signed-in Person on the request's log context."""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Awaitable, Callable, MutableMapping
+
+from ._context import log_context
+
+Scope = MutableMapping[str, object]
+Message = MutableMapping[str, object]
+Receive = Callable[[], Awaitable[Message]]
+Send = Callable[[Message], Awaitable[None]]
+
+
+class EnduserMiddleware:
+    """Sets ``enduser.id`` for each HTTP or WebSocket request.
+
+    ``resolve_user`` gets the ASGI scope and returns the Person's Authentik
+    ``sub`` (or None), directly or as an awaitable. With Starlette or FastAPI:
+    ``app.add_middleware(EnduserMiddleware, resolve_user=...)``.
+    """
+
+    App = Callable[[Scope, Receive, Send], Awaitable[None]]
+    Resolver = Callable[[Scope], "str | Awaitable[str | None] | None"]
+
+    def __init__(self, app: App, resolve_user: Resolver) -> None:
+        self.app = app
+        self.resolve_user = resolve_user
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+        result = self.resolve_user(scope)
+        user = result if result is None or isinstance(result, str) else await result
+        block = log_context(enduser_id=user) if user else contextlib.nullcontext()
+        with block:
+            await self.app(scope, receive, send)

viktorbarzin_telemetry-0.1.0/src/viktorbarzin_telemetry/_config.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import dataclasses
+import os
+
+PRODUCTION = "production"
+ENVIRONMENT_VARIABLE = "TELEMETRY_ENVIRONMENT"
+HOST_VARIABLE = "TELEMETRY_HOST"
+
+
+def resolve_environment(explicit: str | None = None) -> str:
+    """The explicit value, else ``$TELEMETRY_ENVIRONMENT``, else ``dev``."""
+    if explicit is not None:
+        return explicit
+    return os.environ.get(ENVIRONMENT_VARIABLE) or "dev"
+
+
+def resolve_host(explicit: str | None = None) -> str | None:
+    """The explicit Event pipeline URL, else ``$TELEMETRY_HOST``, else None."""
+    if explicit:
+        return explicit
+    return os.environ.get(HOST_VARIABLE) or None
+
+
+def public_host(app_host: str) -> str:
+    """The Event pipeline on an app's public host, for code outside the cluster."""
+    return f"https://{app_host}/_t/e"
+
+
+@dataclasses.dataclass(frozen=True)
+class Config:
+    """One app's telemetry settings.
+
+    ``host`` is the Event pipeline's base URL; the Segment client appends
+    ``/v1/batch``. Production needs one. Inside our cluster it is the
+    pipeline's Service; elsewhere it is ``public_host("<app host>")``.
+    """
+
+    app: str
+    write_key: str
+    release: str
+    environment: str
+    host: str | None = None
+    dsn: str | None = None
+
+    @property
+    def production(self) -> bool:
+        return self.environment == PRODUCTION

viktorbarzin_telemetry-0.1.0/src/viktorbarzin_telemetry/_context.py

@@ -0,0 +1,63 @@
+"""Per-request context: who the Person is and which trace the work belongs to.
+
+Kept in a ContextVar, so each asyncio task and thread sees its own value and
+the value unwinds when the ``log_context`` block ends.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import dataclasses
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+
+
+@dataclasses.dataclass(frozen=True)
+class LogContext:
+    enduser_id: str | None = None
+    anonymous_id: str | None = None
+    trace_id: str | None = None
+    span_id: str | None = None
+    attributes: Mapping[str, object] = dataclasses.field(
+        default_factory=lambda: MappingProxyType({})
+    )
+
+
+_EMPTY = LogContext()
+_current: contextvars.ContextVar[LogContext] = contextvars.ContextVar(
+    "viktorbarzin_telemetry_context", default=_EMPTY
+)
+
+
+def current_context() -> LogContext:
+    return _current.get()
+
+
+@contextlib.contextmanager
+def log_context(
+    *,
+    enduser_id: str | None = None,
+    anonymous_id: str | None = None,
+    trace_id: str | None = None,
+    span_id: str | None = None,
+    **attributes: object,
+) -> Iterator[LogContext]:
+    """Add fields to every log line, and ids to every event, inside the block.
+
+    Values left as None keep whatever an enclosing block set. Keyword
+    ``attributes`` merge over the enclosing ones.
+    """
+    outer = _current.get()
+    merged = LogContext(
+        enduser_id=enduser_id if enduser_id is not None else outer.enduser_id,
+        anonymous_id=anonymous_id if anonymous_id is not None else outer.anonymous_id,
+        trace_id=trace_id if trace_id is not None else outer.trace_id,
+        span_id=span_id if span_id is not None else outer.span_id,
+        attributes=MappingProxyType({**outer.attributes, **attributes}),
+    )
+    token = _current.set(merged)
+    try:
+        yield merged
+    finally:
+        _current.reset(token)

viktorbarzin_telemetry-0.1.0/src/viktorbarzin_telemetry/_events.py

@@ -0,0 +1,188 @@
+"""Product events through Segment's Python SDK, pointed at the Event pipeline."""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Protocol
+
+from segment.analytics.client import Client
+
+from ._config import HOST_VARIABLE, Config, resolve_environment, resolve_host
+from ._context import current_context
+from ._scrub import register_secret
+from ._sentry import init_sentry
+from ._validation import JsonValue, Properties, event_name_problem, properties_problem
+
+_log = logging.getLogger("viktorbarzin_telemetry")
+
+
+class EventClient(Protocol):
+    """The part of ``segment.analytics.Client`` this package calls."""
+
+    def track(
+        self,
+        *,
+        user_id: str | None,
+        event: str,
+        properties: dict[str, JsonValue],
+        context: dict[str, JsonValue],
+        anonymous_id: str,
+    ) -> object: ...
+
+    def identify(
+        self,
+        *,
+        user_id: str,
+        traits: dict[str, JsonValue],
+        context: dict[str, JsonValue],
+        anonymous_id: str,
+    ) -> object: ...
+
+    def flush(self) -> None: ...
+
+
+def _on_error(err: Exception, batch: list[dict[str, object]]) -> None:
+    _log.warning("sending %d events failed: %s", len(batch), err)
+
+
+def segment_client(config: Config) -> Client:
+    if not config.host:
+        raise ValueError(
+            f"production telemetry needs the Event pipeline URL: pass host or set ${HOST_VARIABLE}"
+        )
+    return Client(config.write_key, host=config.host, on_error=_on_error)
+
+
+class Telemetry:
+    """One app's event sender. Outside production it validates and sends nothing."""
+
+    def __init__(self, config: Config, client: EventClient | None = None) -> None:
+        self.config = config
+        self._client: EventClient | None = None
+        if config.production:
+            self._client = client if client is not None else segment_client(config)
+        self._context: dict[str, JsonValue] = {
+            "app": {"name": config.app, "version": config.release}
+        }
+
+    @property
+    def enabled(self) -> bool:
+        """True when events leave the process."""
+        return self._client is not None
+
+    @property
+    def segment_client(self) -> Client | None:
+        return self._client if isinstance(self._client, Client) else None
+
+    def _ids(self, user_id: str | None, anonymous_id: str | None) -> tuple[str | None, str]:
+        ctx = current_context()
+        user = user_id if user_id is not None else ctx.enduser_id
+        anon = anonymous_id or ctx.anonymous_id or str(uuid.uuid4())
+        return user, anon
+
+    def track(
+        self,
+        event: str,
+        properties: Properties | None = None,
+        *,
+        user_id: str | None = None,
+        anonymous_id: str | None = None,
+    ) -> bool:
+        """Queue a Product event. False when it was invalid and dropped."""
+        props = dict(properties or {})
+        problem = event_name_problem(event) or properties_problem(props)
+        if problem is not None:
+            _log.warning("event dropped: %s", problem, extra={"event_name": event})
+            return False
+        if self._client is not None:
+            user, anon = self._ids(user_id, anonymous_id)
+            self._client.track(
+                user_id=user,
+                event=event,
+                properties=props,
+                context=dict(self._context),
+                anonymous_id=anon,
+            )
+        return True
+
+    def identify(
+        self,
+        user_id: str,
+        traits: Properties | None = None,
+        *,
+        anonymous_id: str | None = None,
+    ) -> bool:
+        """Tie ``anonymous_id`` to the Person ``user_id`` (their Authentik ``sub``)."""
+        values = dict(traits or {})
+        problem = "identify without a user id" if not user_id else properties_problem(values)
+        if problem is not None:
+            _log.warning("identify dropped: %s", problem)
+            return False
+        if self._client is not None:
+            _, anon = self._ids(user_id, anonymous_id)
+            self._client.identify(
+                user_id=user_id, traits=values, context=dict(self._context), anonymous_id=anon
+            )
+        return True
+
+    def flush(self) -> None:
+        """Block until queued events are sent."""
+        if self._client is not None:
+            self._client.flush()
+
+
+_default = Telemetry(Config(app="unconfigured", write_key="", release="0", environment="unset"))
+
+
+def configure(
+    app: str,
+    write_key: str,
+    release: str,
+    environment: str | None = None,
+    dsn: str | None = None,
+    host: str | None = None,
+    *,
+    client: EventClient | None = None,
+) -> Telemetry:
+    """Set up events (and Sentry when ``dsn`` is given) for this process.
+
+    Sending happens only when the environment, explicit or from
+    ``$TELEMETRY_ENVIRONMENT``, is ``production``. ``host`` is the Event
+    pipeline's base URL, explicit or from ``$TELEMETRY_HOST``; production
+    without one raises ValueError.
+    """
+    global _default
+    config = Config(
+        app=app,
+        write_key=write_key,
+        release=release,
+        environment=resolve_environment(environment),
+        host=resolve_host(host),
+        dsn=dsn,
+    )
+    register_secret(write_key)
+    _default = Telemetry(config, client=client)
+    if dsn and config.production:
+        init_sentry(dsn, release=release, environment=config.environment)
+    return _default
+
+
+def track(
+    event: str,
+    properties: Properties | None = None,
+    *,
+    user_id: str | None = None,
+    anonymous_id: str | None = None,
+) -> bool:
+    return _default.track(event, properties, user_id=user_id, anonymous_id=anonymous_id)
+
+
+def identify(
+    user_id: str, traits: Properties | None = None, *, anonymous_id: str | None = None
+) -> bool:
+    return _default.identify(user_id, traits, anonymous_id=anonymous_id)
+
+
+def flush() -> None:
+    _default.flush()