viktorbarzin-telemetry 0.1.0__py3-none-any.whl

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/_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/_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/_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/_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()

viktorbarzin_telemetry/_logging.py

@@ -0,0 +1,201 @@
+"""JSON log lines in the OpenTelemetry log data model field names."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import functools
+import json
+import logging
+import re
+import sys
+from collections.abc import Callable, Iterable
+from typing import TextIO
+
+from ._config import resolve_environment
+from ._context import current_context
+from ._scrub import Scrubber
+
+# LogRecord's own attributes, never echoed as extra fields.
+_RECORD_KEYS = frozenset(vars(logging.LogRecord("", 0, "", 0, "", (), None))) | {
+    "message",
+    "asctime",
+    "color_message",
+}
+
+_STANDARD_KEYS = frozenset(
+    {
+        "timestamp",
+        "severity_text",
+        "severity_number",
+        "body",
+        "logger.name",
+        "service.name",
+        "service.version",
+        "deployment.environment.name",
+        "trace_id",
+        "span_id",
+        "enduser.id",
+        "exception.type",
+        "exception.message",
+        "exception.stacktrace",
+        "code.stacktrace",
+    }
+)
+
+_CAMEL_WORD = re.compile(r"(.)([A-Z][a-z]+)")
+_CAMEL_TAIL = re.compile(r"([a-z0-9])([A-Z])")
+_NOT_SNAKE = re.compile(r"[^a-z0-9]+")
+
+
+def severity(levelno: int) -> tuple[str, int]:
+    """OpenTelemetry severity text and number for a ``logging`` level."""
+    if levelno < logging.INFO:
+        return "DEBUG", 5
+    if levelno < logging.WARNING:
+        return "INFO", 9
+    if levelno < logging.ERROR:
+        return "WARN", 13
+    if levelno < logging.CRITICAL:
+        return "ERROR", 17
+    return "FATAL", 21
+
+
+def format_timestamp(created: float) -> str:
+    """RFC 3339 in UTC with a ``Z``, to the microsecond ``logging`` records."""
+    moment = _dt.datetime.fromtimestamp(created, tz=_dt.timezone.utc)
+    return moment.strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def snake_case_key(key: str) -> str:
+    """``channelId`` to ``channel_id``. Dots stay, for OTel names like ``http.request.method``."""
+    parts: list[str] = []
+    for segment in key.split("."):
+        words = _CAMEL_TAIL.sub(r"\1_\2", _CAMEL_WORD.sub(r"\1_\2", segment)).lower()
+        cleaned = _NOT_SNAKE.sub("_", words).strip("_")
+        if cleaned:
+            parts.append(cleaned)
+    return ".".join(parts) or "attribute"
+
+
+SpanIds = Callable[[], "tuple[str, str] | None"]
+
+
+@functools.cache
+def _otel_span_ids() -> SpanIds | None:
+    """A reader for the active OTel span's ids, or None without opentelemetry-api."""
+    try:
+        from opentelemetry import trace
+    except ImportError:
+        return None
+
+    def read() -> tuple[str, str] | None:
+        ctx = trace.get_current_span().get_span_context()
+        if not ctx.is_valid:
+            return None
+        return format(ctx.trace_id, "032x"), format(ctx.span_id, "016x")
+
+    return read
+
+
+def _exception_type(exc_type: type[BaseException]) -> str:
+    if exc_type.__module__ == "builtins":
+        return exc_type.__qualname__
+    return f"{exc_type.__module__}.{exc_type.__qualname__}"
+
+
+class JsonFormatter(logging.Formatter):
+    """One JSON object per record, scrubbed of secrets."""
+
+    def __init__(
+        self,
+        *,
+        service_name: str,
+        service_version: str,
+        environment: str | None = None,
+        secrets: Iterable[str] = (),
+    ) -> None:
+        super().__init__()
+        self._service = {
+            "service.name": service_name,
+            "service.version": service_version,
+            "deployment.environment.name": resolve_environment(environment),
+        }
+        self._scrubber = Scrubber(secrets)
+
+    def format(self, record: logging.LogRecord) -> str:
+        text, number = severity(record.levelno)
+        payload: dict[str, object] = {
+            "timestamp": format_timestamp(record.created),
+            "severity_text": text,
+            "severity_number": number,
+            "body": record.getMessage(),
+            "logger.name": record.name,
+            **self._service,
+        }
+        ctx = current_context()
+        reader = _otel_span_ids()
+        span = reader() if reader is not None else None
+        trace_id, span_id = span if span is not None else (ctx.trace_id, ctx.span_id)
+        if trace_id:
+            payload["trace_id"] = trace_id
+        if span_id:
+            payload["span_id"] = span_id
+        if ctx.enduser_id:
+            payload["enduser.id"] = ctx.enduser_id
+
+        attributes: dict[str, object] = {}
+        for key, value in ctx.attributes.items():
+            attributes[snake_case_key(key)] = value
+        for key, value in vars(record).items():
+            if key not in _RECORD_KEYS and not key.startswith("_"):
+                attributes[snake_case_key(key)] = value
+        for key, value in attributes.items():
+            if key not in _STANDARD_KEYS:
+                payload[key] = value
+
+        if record.exc_info and record.exc_info[0] is not None:
+            exc_type, exc, _ = record.exc_info
+            payload["exception.type"] = _exception_type(exc_type)
+            payload["exception.message"] = str(exc)
+            payload["exception.stacktrace"] = self.formatException(record.exc_info)
+        if record.stack_info:
+            payload["code.stacktrace"] = record.stack_info
+        return self._scrubber.scrub(_dumps(payload))
+
+
+def _dumps(payload: dict[str, object]) -> str:
+    try:
+        return json.dumps(payload, ensure_ascii=False, default=str)
+    except ValueError:
+        # A circular structure: keep the line, as text.
+        flat = {
+            k: v if isinstance(v, (str, int, float, bool)) else str(v) for k, v in payload.items()
+        }
+        return json.dumps(flat, ensure_ascii=False)
+
+
+def setup_logging(
+    *,
+    service_name: str,
+    service_version: str,
+    environment: str | None = None,
+    level: int | str = logging.INFO,
+    stream: TextIO | None = None,
+    secrets: Iterable[str] = (),
+) -> logging.Handler:
+    """Make the root logger write JSON lines to stdout (or ``stream``), replacing its handlers."""
+    handler = logging.StreamHandler(stream if stream is not None else sys.stdout)
+    handler.setFormatter(
+        JsonFormatter(
+            service_name=service_name,
+            service_version=service_version,
+            environment=environment,
+            secrets=secrets,
+        )
+    )
+    root = logging.getLogger()
+    for existing in list(root.handlers):
+        root.removeHandler(existing)
+    root.addHandler(handler)
+    root.setLevel(level)
+    return handler

viktorbarzin_telemetry/_scrub.py

@@ -0,0 +1,54 @@
+"""Redact secrets from a rendered log line before it leaves the process.
+
+The same approach as tripit's ``observability.Scrubber``: known secret values,
+plus credential-shaped patterns that should never reach a shared log store.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+REDACTED = "[REDACTED]"
+
+# Values shorter than this are not masked: hiding short config such as "dev"
+# would remove ordinary content from the logs.
+MIN_SECRET_LENGTH = 8
+
+_BEARER_RE = re.compile(r"(?i)\bbearer\s+[A-Za-z0-9._~+/=\-]+")
+_BASIC_RE = re.compile(r"(?i)\bbasic\s+[A-Za-z0-9+/]{8,}={0,2}")
+_JWT_RE = re.compile(r"\beyJ[A-Za-z0-9_\-]{5,}\.[A-Za-z0-9_\-]{5,}\.[A-Za-z0-9_\-]{2,}")
+_PEM_RE = re.compile(r"-----BEGIN[^-]+-----.*?-----END[^-]+-----", re.DOTALL)
+
+
+_registered: tuple[str, ...] = ()
+
+
+def _longest_first(values: Iterable[str]) -> tuple[str, ...]:
+    # Longest first, so a secret that contains another is masked whole.
+    return tuple(sorted({v for v in values if len(v) >= MIN_SECRET_LENGTH}, key=len, reverse=True))
+
+
+def register_secret(value: str) -> None:
+    """Mask ``value`` in every Scrubber from now on. ``configure`` registers the write key."""
+    global _registered
+    _registered = _longest_first((*_registered, value))
+
+
+class Scrubber:
+    def __init__(self, secret_values: Iterable[str] = ()) -> None:
+        self._own = _longest_first(secret_values)
+        self._seen: tuple[str, ...] | None = None
+        self._secrets: tuple[str, ...] = self._own
+
+    def scrub(self, text: str) -> str:
+        if self._seen is not _registered:
+            self._seen = _registered
+            self._secrets = _longest_first((*self._own, *_registered))
+        for secret in self._secrets:
+            if secret in text:
+                text = text.replace(secret, REDACTED)
+        text = _BEARER_RE.sub(f"Bearer {REDACTED}", text)
+        text = _BASIC_RE.sub(f"Basic {REDACTED}", text)
+        text = _JWT_RE.sub(REDACTED, text)
+        return _PEM_RE.sub(REDACTED, text)

viktorbarzin_telemetry/_sentry.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import logging
+
+_log = logging.getLogger("viktorbarzin_telemetry")
+
+
+def init_sentry(dsn: str, *, release: str, environment: str) -> bool:
+    """Start the Sentry SDK against GlitchTip. False when sentry-sdk is not installed.
+
+    The DSN has the form ``https://<key>@<app host>/_t/x/<project id>``.
+    """
+    try:
+        import sentry_sdk
+    except ImportError:
+        _log.warning(
+            "a Sentry DSN is set but sentry-sdk is not installed; "
+            "install viktorbarzin-telemetry[sentry]"
+        )
+        return False
+    sentry_sdk.init(dsn=dsn, release=release, environment=environment)
+    return True

viktorbarzin_telemetry/_validation.py

@@ -0,0 +1,49 @@
+"""The Product event rules the Event pipeline also enforces.
+
+The pipeline rejects an event that breaks them, so the library checks first,
+drops the event and logs why, instead of sending something that will be thrown
+away.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping, Sequence
+from typing import TypeAlias
+
+JsonValue: TypeAlias = (
+    "str | int | float | bool | Sequence[JsonValue] | Mapping[str, JsonValue] | None"
+)
+Properties: TypeAlias = Mapping[str, JsonValue]
+
+EVENT_NAME_PATTERN = re.compile(r"[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*")
+PROPERTY_KEY_PATTERN = re.compile(r"[a-z][a-z0-9_]*")
+MAX_PROPERTIES_LENGTH = 2048
+
+
+def event_name_problem(name: str) -> str | None:
+    """Why ``name`` is not a valid ``noun.past_verb`` event name, or None."""
+    if EVENT_NAME_PATTERN.fullmatch(name):
+        return None
+    return f"event name {name!r} is not noun.past_verb"
+
+
+def properties_length(properties: Properties) -> int:
+    """UTF-8 bytes of the compact JSON encoding, which bounds the pipeline's count."""
+    encoded = json.dumps(properties, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+    return len(encoded.encode("utf-8"))
+
+
+def properties_problem(properties: Properties) -> str | None:
+    """Why ``properties`` would be rejected, or None when they are fine."""
+    for key in properties:
+        if not PROPERTY_KEY_PATTERN.fullmatch(key):
+            return f"property key {key!r} is not snake_case"
+    try:
+        length = properties_length(properties)
+    except (TypeError, ValueError) as err:
+        return f"properties are not JSON: {err}"
+    if length > MAX_PROPERTIES_LENGTH:
+        return f"properties are {length} bytes as JSON, over {MAX_PROPERTIES_LENGTH}"
+    return None

viktorbarzin_telemetry-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,14 @@
+viktorbarzin_telemetry/__init__.py,sha256=a5HFlrVugjtuxJ9SMMW4EAANceQOe9X0kIFmMYNomyk,1378
+viktorbarzin_telemetry/_asgi.py,sha256=jjmRpiN37a1axKXgPG49cEnKjZEcaGxHHDeQIl7Ld_0,1470
+viktorbarzin_telemetry/_config.py,sha256=aSszoN_r8oMncpoIunLSRBvLHqvugxZ8g6-kmWvbVDo,1352
+viktorbarzin_telemetry/_context.py,sha256=eOv2T2vkhLuFj-hAsHdrvd4mHzLokMSNuJjd_hxUf5k,1903
+viktorbarzin_telemetry/_events.py,sha256=yqwWAbDuQu5TIzg-sTMDxM_MhDNAAWRpo4Nu5M8TKEA,5898
+viktorbarzin_telemetry/_logging.py,sha256=BPAh4QbcJ5ZyO2S4aXBZ_aWgTCouflEjNbNsqLd-dbY,6400
+viktorbarzin_telemetry/_scrub.py,sha256=nFSQbBOcpnYmCR6QQtUcrJxLtciX15gz9theAFYR-rs,2023
+viktorbarzin_telemetry/_sentry.py,sha256=1_8Q_DuA0K5rMm_NU_D-QwGveUimsRZrSSrhlmAsLjg,664
+viktorbarzin_telemetry/_validation.py,sha256=nZGavopfoQij2DRD246UNuYMIpejhhOvdPwtZ5CBeQI,1774
+viktorbarzin_telemetry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+viktorbarzin_telemetry-0.1.0.dist-info/METADATA,sha256=8Vosj-l8GFxiT8FN7Q_Myt1fkBnPSpp_crrcaVHAp5g,2848
+viktorbarzin_telemetry-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+viktorbarzin_telemetry-0.1.0.dist-info/licenses/LICENSE,sha256=bh5tWZXvkWABk3qpM5JpCVN6xihEm7WaUCyKaZ_UwEo,1070
+viktorbarzin_telemetry-0.1.0.dist-info/RECORD,,

viktorbarzin_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

viktorbarzin_telemetry-0.1.0.dist-info/licenses/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.