tiden-telemetry 0.1.0__tar.gz

tiden_telemetry-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy

tiden_telemetry-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish
+
+# Publishes to PyPI on a version tag via OIDC trusted publishing — no tokens.
+# pypa/gh-action-pypi-publish attaches PEP 740 provenance attestations by default.
+#
+# One-time setup on pypi.org: add a "pending publisher" for project
+# `tiden-telemetry` → owner `qase-tms`, repo `tiden-telemetry-python`,
+# workflow `publish.yml` (leave environment empty). The first tag then creates
+# the project automatically.
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC -> PyPI trusted publishing (+ attestations)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

tiden_telemetry-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

tiden_telemetry-0.1.0/LICENSE

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

tiden_telemetry-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: tiden-telemetry
+Version: 0.1.0
+Summary: Error-tracking SDK for Python — captures errors and reports them to a Tiden project.
+Project-URL: Homepage, https://tiden.ai
+Project-URL: Repository, https://github.com/qase-tms/tiden-telemetry-python
+Project-URL: Issues, https://github.com/qase-tms/tiden-telemetry-python/issues
+Author: Tiden
+License-Expression: MIT
+License-File: LICENSE
+Keywords: error-tracking,exceptions,monitoring,observability,telemetry,tiden
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Software Development :: Bug Tracking
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tiden-telemetry (Python)
+
+[![CI](https://github.com/qase-tms/tiden-telemetry-python/actions/workflows/ci.yml/badge.svg)](https://github.com/qase-tms/tiden-telemetry-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tiden-telemetry)](https://pypi.org/project/tiden-telemetry/)
+[![Python](https://img.shields.io/pypi/pyversions/tiden-telemetry)](https://pypi.org/project/tiden-telemetry/)
+
+Error-tracking SDK for **Python** apps. Captures errors and uncaught exceptions
+and reports them to your [Tiden](https://tiden.ai) project, with WSGI middleware
+and a `logging` handler. **Zero dependencies** (standard library only), typed.
+
+## Install
+
+```bash
+pip install tiden-telemetry
+```
+
+## Quick start
+
+```python
+import tiden_telemetry as tiden
+
+tiden.init(
+    dsn="http://<publicKey>@<host:ingestPort>/<projectId>",
+    release="my-app@1.2.3",
+    environment="production",
+)
+
+try:
+    do_work()
+except Exception:
+    tiden.capture_exception()  # inside an except block, no argument needed
+```
+
+`init` installs `sys.excepthook` / `threading.excepthook`, so uncaught
+exceptions are reported automatically.
+
+## Capturing
+
+```python
+tiden.capture_exception(err)
+tiden.capture_message("checkout completed", "info")
+
+tiden.set_tag("plan", "pro")
+tiden.set_user({"id": "u_123"})
+```
+
+## WSGI middleware
+
+Captures unhandled exceptions in your app, then re-raises (so the server's own
+error handling still runs):
+
+```python
+from tiden_telemetry.wsgi import TidenWsgiMiddleware
+
+application = TidenWsgiMiddleware(application)
+```
+
+The captured event includes request URL, method, and headers (sensitive headers
+are scrubbed unless `send_default_pii` is set).
+
+## logging handler
+
+Route records (≥ `ERROR` by default) through Tiden — `logger.exception(...)`
+becomes a captured exception:
+
+```python
+import logging
+from tiden_telemetry.logging import TidenLoggingHandler
+
+logging.getLogger().addHandler(TidenLoggingHandler())
+```
+
+## Options
+
+`tiden.init(...)` / `tiden.Client(...)`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `dsn` | `str` | — | **Required.** `http://<publicKey>@<host:ingestPort>/<projectId>`. |
+| `release` | `str` | `None` | App version, e.g. `my-app@1.2.3`. |
+| `environment` | `str` | `None` | e.g. `production`, `staging`. |
+| `send_default_pii` | `bool` | `False` | Send likely-PII. Off by default — common PII is scrubbed. |
+| `before_send` | `Callable[[dict], dict \| None]` | `None` | Inspect, mutate, or drop an event. Return `None` to drop. |
+| `http_timeout` | `float` | `2.0` | Bounds each synchronous send (seconds). |
+| `install_excepthook` | `bool` | `True` (`init`) | Install global excepthooks. |
+
+Use `tiden.Client(...)` directly for multiple clients or to avoid global state;
+pass it to `TidenWsgiMiddleware(app, client=...)` / `TidenLoggingHandler(client=...)`.
+
+## How it works
+
+- Parses the DSN to `/api/<projectId>/envelope/?tiden_key=…`.
+- Normalizes exceptions (incl. the `__cause__` / `__context__` chain) into
+  `exception.values[]` with stack frames (`in_app` excludes the stdlib and
+  site-packages).
+- Serializes the envelope and POSTs it with `Content-Type:
+  application/x-tiden-envelope` — **synchronous, never raises into the host**;
+  honors HTTP 429 + `Retry-After`.
+- Scrubs likely-PII (auth headers, secret-ish keys) unless `send_default_pii`.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+ruff check . && ruff format --check .
+mypy
+pytest -q
+```
+
+## License
+
+[MIT](LICENSE) © Tiden

tiden_telemetry-0.1.0/README.md

@@ -0,0 +1,112 @@
+# tiden-telemetry (Python)
+
+[![CI](https://github.com/qase-tms/tiden-telemetry-python/actions/workflows/ci.yml/badge.svg)](https://github.com/qase-tms/tiden-telemetry-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tiden-telemetry)](https://pypi.org/project/tiden-telemetry/)
+[![Python](https://img.shields.io/pypi/pyversions/tiden-telemetry)](https://pypi.org/project/tiden-telemetry/)
+
+Error-tracking SDK for **Python** apps. Captures errors and uncaught exceptions
+and reports them to your [Tiden](https://tiden.ai) project, with WSGI middleware
+and a `logging` handler. **Zero dependencies** (standard library only), typed.
+
+## Install
+
+```bash
+pip install tiden-telemetry
+```
+
+## Quick start
+
+```python
+import tiden_telemetry as tiden
+
+tiden.init(
+    dsn="http://<publicKey>@<host:ingestPort>/<projectId>",
+    release="my-app@1.2.3",
+    environment="production",
+)
+
+try:
+    do_work()
+except Exception:
+    tiden.capture_exception()  # inside an except block, no argument needed
+```
+
+`init` installs `sys.excepthook` / `threading.excepthook`, so uncaught
+exceptions are reported automatically.
+
+## Capturing
+
+```python
+tiden.capture_exception(err)
+tiden.capture_message("checkout completed", "info")
+
+tiden.set_tag("plan", "pro")
+tiden.set_user({"id": "u_123"})
+```
+
+## WSGI middleware
+
+Captures unhandled exceptions in your app, then re-raises (so the server's own
+error handling still runs):
+
+```python
+from tiden_telemetry.wsgi import TidenWsgiMiddleware
+
+application = TidenWsgiMiddleware(application)
+```
+
+The captured event includes request URL, method, and headers (sensitive headers
+are scrubbed unless `send_default_pii` is set).
+
+## logging handler
+
+Route records (≥ `ERROR` by default) through Tiden — `logger.exception(...)`
+becomes a captured exception:
+
+```python
+import logging
+from tiden_telemetry.logging import TidenLoggingHandler
+
+logging.getLogger().addHandler(TidenLoggingHandler())
+```
+
+## Options
+
+`tiden.init(...)` / `tiden.Client(...)`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `dsn` | `str` | — | **Required.** `http://<publicKey>@<host:ingestPort>/<projectId>`. |
+| `release` | `str` | `None` | App version, e.g. `my-app@1.2.3`. |
+| `environment` | `str` | `None` | e.g. `production`, `staging`. |
+| `send_default_pii` | `bool` | `False` | Send likely-PII. Off by default — common PII is scrubbed. |
+| `before_send` | `Callable[[dict], dict \| None]` | `None` | Inspect, mutate, or drop an event. Return `None` to drop. |
+| `http_timeout` | `float` | `2.0` | Bounds each synchronous send (seconds). |
+| `install_excepthook` | `bool` | `True` (`init`) | Install global excepthooks. |
+
+Use `tiden.Client(...)` directly for multiple clients or to avoid global state;
+pass it to `TidenWsgiMiddleware(app, client=...)` / `TidenLoggingHandler(client=...)`.
+
+## How it works
+
+- Parses the DSN to `/api/<projectId>/envelope/?tiden_key=…`.
+- Normalizes exceptions (incl. the `__cause__` / `__context__` chain) into
+  `exception.values[]` with stack frames (`in_app` excludes the stdlib and
+  site-packages).
+- Serializes the envelope and POSTs it with `Content-Type:
+  application/x-tiden-envelope` — **synchronous, never raises into the host**;
+  honors HTTP 429 + `Retry-After`.
+- Scrubs likely-PII (auth headers, secret-ish keys) unless `send_default_pii`.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+ruff check . && ruff format --check .
+mypy
+pytest -q
+```
+
+## License
+
+[MIT](LICENSE) © Tiden

tiden_telemetry-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tiden-telemetry"
+version = "0.1.0"
+description = "Error-tracking SDK for Python — captures errors and reports them to a Tiden project."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Tiden" }]
+keywords = ["error-tracking", "monitoring", "telemetry", "tiden", "exceptions", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Bug Tracking",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://tiden.ai"
+Repository = "https://github.com/qase-tms/tiden-telemetry-python"
+Issues = "https://github.com/qase-tms/tiden-telemetry-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.6", "mypy>=1.8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tiden_telemetry"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+strict = true
+files = ["src"]

tiden_telemetry-0.1.0/src/tiden_telemetry/__init__.py

@@ -0,0 +1,102 @@
+"""Error-tracking SDK for Python — reports errors and messages to a Tiden project.
+
+Quick start::
+
+    import tiden_telemetry as tiden
+
+    tiden.init(
+        dsn="http://<publicKey>@<host:ingestPort>/<projectId>",
+        release="my-app@1.2.3",
+        environment="production",
+    )
+
+    try:
+        do_work()
+    except Exception:
+        tiden.capture_exception()
+
+Uncaught exceptions are reported automatically once ``init`` is called.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._client import BeforeSend, Client
+from ._dsn import Dsn, parse_dsn
+from ._event import VERSION
+from ._transport import Transport
+
+__all__ = [
+    "VERSION",
+    "BeforeSend",
+    "Client",
+    "Dsn",
+    "Transport",
+    "capture_exception",
+    "capture_message",
+    "get_client",
+    "init",
+    "parse_dsn",
+    "set_tag",
+    "set_user",
+]
+
+_client: Client | None = None
+
+
+def init(
+    dsn: str,
+    *,
+    release: str | None = None,
+    environment: str | None = None,
+    send_default_pii: bool = False,
+    before_send: BeforeSend | None = None,
+    transport: Transport | None = None,
+    http_timeout: float = 2.0,
+    install_excepthook: bool = True,
+) -> Client:
+    """Configure the package-level client. Call once at startup.
+
+    By default this installs ``sys.excepthook`` / ``threading.excepthook`` so
+    uncaught exceptions are reported automatically.
+    """
+    global _client
+    _client = Client(
+        dsn,
+        release=release,
+        environment=environment,
+        send_default_pii=send_default_pii,
+        before_send=before_send,
+        transport=transport,
+        http_timeout=http_timeout,
+        install_excepthook=install_excepthook,
+    )
+    return _client
+
+
+def get_client() -> Client | None:
+    """Return the package-level client (None if ``init`` was not called)."""
+    return _client
+
+
+def capture_exception(error: BaseException | None = None) -> str:
+    """Report an exception via the package-level client."""
+    return _client.capture_exception(error) if _client is not None else ""
+
+
+def capture_message(message: str, level: str = "info") -> str:
+    """Report a message via the package-level client."""
+    return _client.capture_message(message, level) if _client is not None else ""
+
+
+def set_tag(key: str, value: str) -> None:
+    """Attach a tag to subsequent events on the package-level client."""
+    if _client is not None:
+        _client.set_tag(key, value)
+
+
+def set_user(user: dict[str, Any] | None) -> None:
+    """Attach a user to subsequent events on the package-level client."""
+    if _client is not None:
+        _client.set_user(user)

tiden_telemetry-0.1.0/src/tiden_telemetry/_client.py

@@ -0,0 +1,145 @@
+"""The Client: builds events, applies scrubbing + before_send, sends the envelope."""
+
+from __future__ import annotations
+
+import sys
+import threading
+import time
+from types import TracebackType
+from typing import Any, Callable, Optional
+
+from ._dsn import parse_dsn
+from ._envelope import serialize_envelope
+from ._event import _SDK, base_event, exception_from, new_event_id
+from ._scrub import scrub
+from ._transport import HttpTransport, Transport
+
+BeforeSend = Callable[[dict[str, Any]], Optional[dict[str, Any]]]
+
+
+class Client:
+    """Captures errors and messages and reports them to a Tiden project.
+
+    Capture methods never raise into the host application.
+    """
+
+    def __init__(
+        self,
+        dsn: str,
+        *,
+        release: str | None = None,
+        environment: str | None = None,
+        send_default_pii: bool = False,
+        before_send: BeforeSend | None = None,
+        transport: Transport | None = None,
+        http_timeout: float = 2.0,
+        install_excepthook: bool = False,
+    ) -> None:
+        self._dsn = parse_dsn(dsn)
+        self._release = release
+        self._environment = environment
+        self._send_default_pii = send_default_pii
+        self._before_send = before_send
+        self._transport: Transport = transport or HttpTransport(self._dsn.ingest_url, http_timeout)
+        self._lock = threading.Lock()
+        self._tags: dict[str, str] = {}
+        self._user: dict[str, Any] | None = None
+        if install_excepthook:
+            self._install_excepthook()
+
+    def set_tag(self, key: str, value: str) -> None:
+        """Attach a tag to subsequent events."""
+        with self._lock:
+            self._tags[key] = value
+
+    def set_user(self, user: dict[str, Any] | None) -> None:
+        """Attach a user to subsequent events (None clears it)."""
+        with self._lock:
+            self._user = user
+
+    def capture_exception(
+        self,
+        error: BaseException | None = None,
+        *,
+        level: str = "error",
+        request: dict[str, Any] | None = None,
+    ) -> str:
+        """Report an exception. With no argument, captures the active exception."""
+        if error is None:
+            error = sys.exc_info()[1]
+        if error is None:
+            return ""
+        event = self._new_event(level)
+        event["exception"] = exception_from(error)
+        if request is not None:
+            event["request"] = request
+        return self.capture_event(event)
+
+    def capture_message(self, message: str, level: str = "info") -> str:
+        """Report a message at the given level."""
+        event = self._new_event(level or "info")
+        event["message"] = message
+        return self.capture_event(event)
+
+    def capture_event(self, event: dict[str, Any]) -> str:
+        """Send a pre-built event, filling in any missing required fields."""
+        try:
+            event.setdefault("event_id", new_event_id())
+            event.setdefault("timestamp", time.time())
+            event.setdefault("platform", "python")
+            event.setdefault("level", "error")
+            event.setdefault("sdk", dict(_SDK))
+
+            if not self._send_default_pii:
+                event = scrub(event)
+            if self._before_send is not None:
+                result = self._before_send(event)
+                if result is None:
+                    return ""
+                event = result
+
+            self._transport.send(serialize_envelope(event))
+            event_id = event.get("event_id", "")
+            return event_id if isinstance(event_id, str) else ""
+        except Exception:
+            # Monitoring must never crash the app it monitors.
+            return ""
+
+    def _new_event(self, level: str) -> dict[str, Any]:
+        event = base_event(level, self._release, self._environment)
+        with self._lock:
+            if self._tags:
+                event["tags"] = dict(self._tags)
+            if self._user is not None:
+                event["user"] = self._user
+        return event
+
+    def _install_excepthook(self) -> None:
+        prev = sys.excepthook
+
+        def hook(
+            exc_type: type[BaseException],
+            exc_value: BaseException,
+            exc_tb: TracebackType | None,
+        ) -> None:
+            try:
+                event = self._new_event("fatal")
+                event["exception"] = exception_from(exc_value)
+                self.capture_event(event)
+            finally:
+                prev(exc_type, exc_value, exc_tb)
+
+        sys.excepthook = hook
+
+        prev_thread = threading.excepthook
+
+        def thread_hook(args: threading.ExceptHookArgs) -> None:
+            try:
+                if args.exc_value is not None:
+                    event = self._new_event("fatal")
+                    event["exception"] = exception_from(args.exc_value)
+                    self.capture_event(event)
+            finally:
+                prev_thread(args)
+
+        threading.excepthook = thread_hook

tiden_telemetry-0.1.0/src/tiden_telemetry/_dsn.py

@@ -0,0 +1,40 @@
+"""DSN parsing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import quote, urlparse
+
+
+@dataclass(frozen=True)
+class Dsn:
+    """A parsed Tiden DSN."""
+
+    ingest_url: str
+    public_key: str
+    project_id: str
+
+
+def parse_dsn(dsn: str) -> Dsn:
+    """Turn ``http://<publicKey>@host[:port]/<projectId>`` into the ingest URL.
+
+    The Tiden edge expects ``<scheme>://host/api/<projectId>/envelope/?tiden_key=<publicKey>``
+    (wire-compatible with the other Tiden SDKs — the edge reads the ``tiden_key``
+    query param).
+    """
+    u = urlparse(dsn)
+    public_key = u.username or ""
+    project_id = u.path.lstrip("/").split("/", 1)[0] if u.path else ""
+
+    if not u.scheme or not u.hostname or not public_key or not project_id:
+        raise ValueError("tiden: invalid DSN (expected http://<publicKey>@host/<projectId>)")
+
+    host = u.hostname
+    if u.port is not None:
+        host = f"{host}:{u.port}"
+
+    ingest_url = (
+        f"{u.scheme}://{host}/api/{quote(project_id, safe='')}"
+        f"/envelope/?tiden_key={quote(public_key, safe='')}"
+    )
+    return Dsn(ingest_url=ingest_url, public_key=public_key, project_id=project_id)

tiden_telemetry-0.1.0/src/tiden_telemetry/_envelope.py

@@ -0,0 +1,37 @@
+"""Envelope serialization."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+# Envelope media type the ingest backend accepts. Part of the wire contract.
+CONTENT_TYPE = "application/x-tiden-envelope"
+
+
+def serialize_envelope(event: dict[str, Any]) -> bytes:
+    """Produce the bytes the edge parses.
+
+    Framing: ``{envelope header}\\n{item header (with byte length)}\\n{event body}\\n``
+    """
+    body = json.dumps(event, separators=(",", ":"), ensure_ascii=False, default=str).encode("utf-8")
+
+    header = json.dumps(
+        {
+            "event_id": event.get("event_id"),
+            "sent_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        },
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+    item = json.dumps(
+        {
+            "type": "event",
+            "length": len(body),  # byte length used by the edge for framing
+            "content_type": "application/json",
+        },
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+    return header + b"\n" + item + b"\n" + body + b"\n"

tiden_telemetry-0.1.0/src/tiden_telemetry/_event.py

@@ -0,0 +1,103 @@
+"""Event construction: ids, base fields, exception normalization, stack frames."""
+
+from __future__ import annotations
+
+import os
+import time
+import traceback
+import uuid
+from types import TracebackType
+from typing import Any
+
+VERSION = "0.1.0"
+
+_SDK = {"name": "tiden.python", "version": VERSION}
+
+
+def new_event_id() -> str:
+    """Return a 32-char hex UUIDv4 (no dashes) — the event_id shape the edge stores."""
+    return uuid.uuid4().hex
+
+
+def base_event(level: str, release: str | None, environment: str | None) -> dict[str, Any]:
+    """Build the common event fields."""
+    event: dict[str, Any] = {
+        "event_id": new_event_id(),
+        "timestamp": time.time(),
+        "platform": "python",
+        "level": level,
+        "sdk": dict(_SDK),
+    }
+    if release:
+        event["release"] = release
+    if environment:
+        event["environment"] = environment
+    return event
+
+
+def exception_from(exc: BaseException) -> dict[str, Any]:
+    """Normalize an exception (and its cause/context chain) into exception.values.
+
+    Values are ordered with the root cause first — the order the UI expects.
+    """
+    chain: list[BaseException] = []
+    seen: set[int] = set()
+    cur: BaseException | None = exc
+    while cur is not None and id(cur) not in seen:
+        seen.add(id(cur))
+        chain.append(cur)
+        nxt = cur.__cause__
+        if nxt is None and not cur.__suppress_context__:
+            nxt = cur.__context__
+        cur = nxt
+
+    values: list[dict[str, Any]] = []
+    for e in reversed(chain):
+        values.append(
+            {
+                "type": type(e).__name__,
+                "value": str(e),
+                "stacktrace": {"frames": _frames_from(e.__traceback__)},
+            }
+        )
+    return {"values": values}
+
+
+def _frames_from(tb: TracebackType | None) -> list[dict[str, Any]]:
+    # extract_tb yields outermost first with the raise site last — the order
+    # the UI expects (crash frame last).
+    frames: list[dict[str, Any]] = []
+    for fs in traceback.extract_tb(tb):
+        frames.append(_frame(fs.filename, fs.lineno, fs.name))
+    return frames
+
+
+def _frame(filename: str | None, lineno: int | None, function: str | None) -> dict[str, Any]:
+    frame: dict[str, Any] = {}
+    if function:
+        frame["function"] = function
+    if filename:
+        frame["filename"] = _relpath(filename)
+        frame["abs_path"] = filename
+    if lineno:
+        frame["lineno"] = lineno
+    frame["in_app"] = _in_app(filename)
+    return frame
+
+
+def _in_app(filename: str | None) -> bool:
+    if not filename:
+        return False
+    # Heuristic: third-party + standard library are not "in app".
+    return "site-packages" not in filename and "lib/python" not in filename.replace("\\", "/")
+
+
+def _relpath(filename: str) -> str:
+    try:
+        cwd = os.getcwd()
+    except OSError:
+        return filename
+    prefix = cwd + os.sep
+    if filename.startswith(prefix):
+        return filename[len(prefix) :]
+    return filename

tiden_telemetry-0.1.0/src/tiden_telemetry/_scrub.py

@@ -0,0 +1,53 @@
+"""PII scrubbing (applied unless send_default_pii is set)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+REDACTED = "[Filtered]"
+
+_HEADER_DENYLIST = frozenset(
+    {"authorization", "cookie", "set-cookie", "x-api-key", "x-auth-token", "proxy-authorization"}
+)
+
+_KEY_DENYLIST = frozenset(
+    {
+        "password",
+        "passwd",
+        "secret",
+        "token",
+        "api_key",
+        "apikey",
+        "authorization",
+        "credit_card",
+        "card_number",
+        "cvv",
+    }
+)
+
+
+def scrub(event: dict[str, Any]) -> dict[str, Any]:
+    """Redact likely-PII in request headers and extra/user/contexts keys."""
+    request = event.get("request")
+    if isinstance(request, dict):
+        headers = request.get("headers")
+        if isinstance(headers, dict):
+            for name in list(headers):
+                if isinstance(name, str) and name.lower() in _HEADER_DENYLIST:
+                    headers[name] = REDACTED
+
+    for section in ("extra", "user", "contexts"):
+        value = event.get(section)
+        if isinstance(value, dict):
+            event[section] = _scrub_keys(value)
+
+    return event
+
+
+def _scrub_keys(data: dict[str, Any]) -> dict[str, Any]:
+    for key, value in list(data.items()):
+        if isinstance(key, str) and key.lower() in _KEY_DENYLIST:
+            data[key] = REDACTED
+        elif isinstance(value, dict):
+            data[key] = _scrub_keys(value)
+    return data

tiden_telemetry-0.1.0/src/tiden_telemetry/_transport.py

@@ -0,0 +1,57 @@
+"""Synchronous HTTP transport (stdlib only)."""
+
+from __future__ import annotations
+
+import time
+import urllib.error
+import urllib.request
+from typing import Protocol
+
+from ._envelope import CONTENT_TYPE
+
+
+class Transport(Protocol):
+    """Delivers a serialized envelope to the ingest edge."""
+
+    def send(self, envelope: bytes) -> None: ...
+
+
+class HttpTransport:
+    """Posts envelopes synchronously via urllib.
+
+    Every failure is swallowed — monitoring must never crash the host app.
+    Honors HTTP 429 + Retry-After with a process-local gate.
+    """
+
+    def __init__(self, url: str, timeout: float = 2.0) -> None:
+        self._url = url
+        self._timeout = timeout
+        self._rate_limited_until = 0.0
+
+    def send(self, envelope: bytes) -> None:
+        if time.time() < self._rate_limited_until:
+            return
+
+        request = urllib.request.Request(  # noqa: S310 (scheme comes from a trusted DSN)
+            self._url,
+            data=envelope,
+            method="POST",
+            headers={"Content-Type": CONTENT_TYPE},
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as resp:  # noqa: S310
+                resp.read()
+        except urllib.error.HTTPError as exc:
+            if exc.code == 429:
+                self._rate_limited_until = time.time() + _retry_after(exc)
+        except Exception:
+            # Monitoring must never crash the app it monitors.
+            pass
+
+
+def _retry_after(exc: urllib.error.HTTPError) -> float:
+    if exc.headers is not None:
+        value = exc.headers.get("Retry-After")
+        if value is not None and value.strip().isdigit():
+            return float(value.strip())
+    return 60.0

tiden_telemetry-0.1.0/src/tiden_telemetry/logging.py

@@ -0,0 +1,45 @@
+"""A logging.Handler that forwards records to Tiden.
+
+Records with exception info become captured exceptions; others become messages::
+
+    import logging
+    from tiden_telemetry.logging import TidenLoggingHandler
+
+    logging.getLogger().addHandler(TidenLoggingHandler())
+"""
+
+from __future__ import annotations
+
+import logging
+
+from . import get_client
+from ._client import Client
+
+_LEVEL_MAP = {
+    logging.CRITICAL: "fatal",
+    logging.ERROR: "error",
+    logging.WARNING: "warning",
+    logging.INFO: "info",
+    logging.DEBUG: "debug",
+}
+
+
+class TidenLoggingHandler(logging.Handler):
+    """Forwards log records at or above ``level`` (default ERROR) to Tiden."""
+
+    def __init__(self, level: int = logging.ERROR, client: Client | None = None) -> None:
+        super().__init__(level)
+        self._client = client
+
+    def emit(self, record: logging.LogRecord) -> None:
+        client = self._client or get_client()
+        if client is None:
+            return
+        try:
+            level = _LEVEL_MAP.get(record.levelno, "error")
+            if record.exc_info is not None and record.exc_info[1] is not None:
+                client.capture_exception(record.exc_info[1], level=level)
+            else:
+                client.capture_message(record.getMessage(), level)
+        except Exception:
+            self.handleError(record)

tiden_telemetry-0.1.0/src/tiden_telemetry/wsgi.py

@@ -0,0 +1,53 @@
+"""WSGI middleware that reports unhandled exceptions to Tiden."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, Callable
+
+from . import get_client
+from ._client import Client
+
+if TYPE_CHECKING:
+    StartResponse = Callable[..., Any]
+    WSGIEnvironment = dict[str, Any]
+    WSGIApplication = Callable[[WSGIEnvironment, StartResponse], Iterable[bytes]]
+
+
+class TidenWsgiMiddleware:
+    """Wrap a WSGI app so unhandled exceptions are captured, then re-raised.
+
+    Re-raising preserves the server's own error handling; Tiden just observes::
+
+        app = TidenWsgiMiddleware(app)
+    """
+
+    def __init__(self, app: WSGIApplication, client: Client | None = None) -> None:
+        self._app = app
+        self._client = client
+
+    def __call__(self, environ: WSGIEnvironment, start_response: StartResponse) -> Iterable[bytes]:
+        try:
+            return self._app(environ, start_response)
+        except Exception as exc:
+            client = self._client or get_client()
+            if client is not None:
+                client.capture_exception(exc, level="fatal", request=_request_from_environ(environ))
+            raise
+
+
+def _request_from_environ(environ: WSGIEnvironment) -> dict[str, Any]:
+    headers: dict[str, str] = {}
+    for key, value in environ.items():
+        if key.startswith("HTTP_") and isinstance(value, str):
+            name = key[5:].replace("_", "-").title()
+            headers[name] = value
+
+    scheme = environ.get("wsgi.url_scheme", "http")
+    host = environ.get("HTTP_HOST") or environ.get("SERVER_NAME", "")
+    path = environ.get("PATH_INFO", "")
+    return {
+        "url": f"{scheme}://{host}{path}",
+        "method": environ.get("REQUEST_METHOD", ""),
+        "headers": headers,
+    }

tiden_telemetry-0.1.0/tests/test_client.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import pytest
+
+from tiden_telemetry import Client
+from tiden_telemetry.logging import TidenLoggingHandler
+from tiden_telemetry.wsgi import TidenWsgiMiddleware
+
+
+class CaptureTransport:
+    def __init__(self) -> None:
+        self.last: bytes | None = None
+
+    def send(self, envelope: bytes) -> None:
+        self.last = envelope
+
+
+def decode_event(envelope: bytes | None) -> dict[str, Any]:
+    assert envelope is not None
+    lines = envelope.decode("utf-8").rstrip("\n").split("\n")
+    assert len(lines) == 3
+    return json.loads(lines[2])
+
+
+def make_client(**opts: Any) -> tuple[Client, CaptureTransport]:
+    tr = CaptureTransport()
+    client = Client("http://k@host/p", transport=tr, **opts)
+    return client, tr
+
+
+def test_capture_message() -> None:
+    client, tr = make_client()
+    event_id = client.capture_message("checkout completed", "info")
+    assert event_id
+    event = decode_event(tr.last)
+    assert event["message"] == "checkout completed"
+    assert event["level"] == "info"
+
+
+def test_before_send_drop() -> None:
+    client, tr = make_client(before_send=lambda _event: None)
+    assert client.capture_exception(ValueError("x")) == ""
+    assert tr.last is None
+
+
+def test_before_send_mutate() -> None:
+    def mutate(event: dict[str, Any]) -> dict[str, Any]:
+        event["level"] = "warning"
+        return event
+
+    client, tr = make_client(before_send=mutate)
+    client.capture_exception(ValueError("x"))
+    assert decode_event(tr.last)["level"] == "warning"
+
+
+def test_scrub_extra() -> None:
+    client, tr = make_client()
+    event = client._new_event("error")
+    event["extra"] = {"password": "hunter2", "ok": "keep"}
+    client.capture_event(event)
+    extra = decode_event(tr.last)["extra"]
+    assert extra["password"] == "[Filtered]"
+    assert extra["ok"] == "keep"
+
+
+def test_send_default_pii_disables_scrub() -> None:
+    client, tr = make_client(send_default_pii=True)
+    event = client._new_event("error")
+    event["extra"] = {"password": "hunter2"}
+    client.capture_event(event)
+    assert decode_event(tr.last)["extra"]["password"] == "hunter2"
+
+
+def test_set_tag_and_user() -> None:
+    client, tr = make_client()
+    client.set_tag("plan", "pro")
+    client.set_user({"id": "u_1"})
+    client.capture_message("hi", "info")
+    event = decode_event(tr.last)
+    assert event["tags"]["plan"] == "pro"
+    assert event["user"]["id"] == "u_1"
+
+
+def test_capture_no_active_exception() -> None:
+    client, tr = make_client()
+    assert client.capture_exception() == ""
+    assert tr.last is None
+
+
+def test_exception_chain_root_first() -> None:
+    client, tr = make_client()
+    try:
+        try:
+            raise ValueError("root")
+        except ValueError as root:
+            raise RuntimeError("wrapper") from root
+    except RuntimeError:
+        client.capture_exception()
+    values = decode_event(tr.last)["exception"]["values"]
+    assert [v["type"] for v in values] == ["ValueError", "RuntimeError"]
+
+
+def test_wsgi_middleware_captures_and_reraises() -> None:
+    tr = CaptureTransport()
+    client = Client("http://k@host/p", transport=tr)
+
+    def app(environ: dict[str, Any], start_response: Any) -> list[bytes]:
+        raise RuntimeError("handler boom")
+
+    wrapped = TidenWsgiMiddleware(app, client=client)
+    environ = {
+        "REQUEST_METHOD": "GET",
+        "PATH_INFO": "/x",
+        "HTTP_HOST": "example",
+        "wsgi.url_scheme": "http",
+        "HTTP_AUTHORIZATION": "secret",
+    }
+
+    with pytest.raises(RuntimeError):
+        wrapped(environ, lambda *_: None)
+
+    event = decode_event(tr.last)
+    ex = event["exception"]["values"][0]
+    assert ex["value"] == "handler boom"
+    assert event["request"]["method"] == "GET"
+    assert event["request"]["headers"]["Authorization"] == "[Filtered]"
+
+
+def test_logging_handler() -> None:
+    tr = CaptureTransport()
+    client = Client("http://k@host/p", transport=tr)
+    logger = logging.getLogger("tiden-test")
+    logger.setLevel(logging.ERROR)
+    handler = TidenLoggingHandler(client=client)
+    logger.addHandler(handler)
+    try:
+        try:
+            raise ValueError("logged boom")
+        except ValueError:
+            logger.exception("something failed")
+    finally:
+        logger.removeHandler(handler)
+
+    event = decode_event(tr.last)
+    assert event["exception"]["values"][0]["value"] == "logged boom"

tiden_telemetry-0.1.0/tests/test_contract.py

@@ -0,0 +1,78 @@
+"""Wire contract test: pins the exact bytes the SDK puts on the wire.
+
+If the backend changes the ingest interface (auth param, media type, envelope
+framing, or event field names), update the SDK + these assertions together — a
+drift makes this test fail loudly.
+"""
+
+from __future__ import annotations
+
+import json
+
+from tiden_telemetry import Client
+from tiden_telemetry._dsn import parse_dsn
+from tiden_telemetry._envelope import CONTENT_TYPE
+
+
+class CaptureTransport:
+    def __init__(self) -> None:
+        self.last: bytes | None = None
+
+    def send(self, envelope: bytes) -> None:
+        self.last = envelope
+
+
+def test_dsn_ingest_url_and_auth_param() -> None:
+    dsn = parse_dsn("http://pub@host:1140/proj-1")
+    assert dsn.ingest_url == "http://host:1140/api/proj-1/envelope/?tiden_key=pub"
+
+
+def test_envelope_media_type() -> None:
+    assert CONTENT_TYPE == "application/x-tiden-envelope"
+
+
+def test_envelope_framing_and_event_shape() -> None:
+    tr = CaptureTransport()
+    client = Client(
+        "http://pub@host:1140/proj-1",
+        release="app@1.2.3",
+        environment="production",
+        transport=tr,
+    )
+
+    try:
+        raise ValueError("boom")
+    except ValueError:
+        client.capture_exception()
+
+    assert tr.last is not None
+    lines = tr.last.decode("utf-8").rstrip("\n").split("\n")
+    assert len(lines) == 3
+
+    header = json.loads(lines[0])
+    item = json.loads(lines[1])
+    event = json.loads(lines[2])
+
+    # framing
+    assert item["type"] == "event"
+    assert item["content_type"] == "application/json"
+    assert item["length"] == len(lines[2].encode("utf-8"))  # byte length
+    assert header["event_id"] == event["event_id"]
+
+    # event schema the backend normalizer reads
+    assert event["platform"] == "python"
+    assert event["level"] == "error"
+    assert event["release"] == "app@1.2.3"
+    assert event["environment"] == "production"
+    assert event["sdk"]["name"] == "tiden.python"
+
+    ex = event["exception"]["values"][0]
+    assert ex["type"] == "ValueError"
+    assert ex["value"] == "boom"
+    assert ex["stacktrace"]["frames"]
+    last = ex["stacktrace"]["frames"][-1]
+    assert "function" in last
+    assert "in_app" in last
+
+    # event_id shape: 32 hex chars
+    assert len(event["event_id"]) == 32

tiden_telemetry-0.1.0/tests/test_dsn.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import pytest
+
+from tiden_telemetry._dsn import parse_dsn
+
+
+def test_with_port() -> None:
+    dsn = parse_dsn("http://pub@host:1140/proj-1")
+    assert dsn.ingest_url == "http://host:1140/api/proj-1/envelope/?tiden_key=pub"
+    assert dsn.public_key == "pub"
+    assert dsn.project_id == "proj-1"
+
+
+def test_no_port_https() -> None:
+    dsn = parse_dsn("https://k@ingest.tiden.ai/42")
+    assert dsn.ingest_url == "https://ingest.tiden.ai/api/42/envelope/?tiden_key=k"
+
+
+@pytest.mark.parametrize(
+    "bad",
+    [
+        "http://host/proj",  # missing key
+        "http://pub@host/",  # missing project
+        "not-a-url",
+        "",
+    ],
+)
+def test_invalid(bad: str) -> None:
+    with pytest.raises(ValueError):
+        parse_dsn(bad)