tellann 0.1.0__tar.gz

tellann-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Dependency directories
+node_modules/
+.pnpm-store/
+
+# Build and build cache outputs
+dist/
+build/
+release/
+apps/desktop/release/
+.next/
+.codex/
+.turbo/
+out/
+artifacts/
+tmp/
+**/tmp/
+
+# Logs
+*.log
+*.err
+
+# Env files
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# IDE/OS files
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

tellann-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.5
+Name: tellann
+Version: 0.1.0
+Summary: Tellann SDK for Python: behaviour telemetry for Django, Flask, FastAPI and Starlette applications.
+Project-URL: Homepage, https://tellann.com
+Author: Tellann
+License: MIT
+Keywords: django,fastapi,flask,observability,telemetry
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: django
+Requires-Dist: django>=3.2; extra == 'django'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.95; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# tellann (Python SDK)
+
+Behaviour telemetry for Python services, matching `@tellann/backend-sdk` event
+for event. A Flow that crosses a React page and a Django view reaches the
+collector as one sequence.
+
+```bash
+python -m pip install tellann
+```
+
+## Initialize
+
+```python
+from tellann import TELLANN
+
+TELLANN.initialize(
+    endpoint="https://gateway.example.com",
+    application_id="...",
+    environment_id="...",
+    api_key="...",
+)
+TELLANN.verify_installation()
+```
+
+Every argument falls back to an environment variable — `TELLANN_GATEWAY_URL`,
+`TELLANN_INGESTION_KEY`, `TELLANN_APPLICATION_ID`, `TELLANN_ENVIRONMENT_ID` —
+so `TELLANN.initialize()` with no arguments works wherever those are set. If
+the endpoint or application id is missing the SDK disables itself rather than
+raising: telemetry that is not configured must not stop an application booting.
+
+## Frameworks
+
+**Django** — add the middleware and initialize from `settings.py`:
+
+```python
+from tellann.integrations.django_middleware import instrument_django
+
+instrument_django()
+
+MIDDLEWARE = [
+    "tellann.integrations.django_middleware.TellannMiddleware",
+    # ... your middleware
+]
+```
+
+**Flask** — attach to the application, including inside a factory:
+
+```python
+from tellann import instrument_flask
+
+app = Flask(__name__)
+instrument_flask(app)
+```
+
+**FastAPI / Starlette** — attach to the application:
+
+```python
+from tellann import instrument_fastapi
+
+app = FastAPI()
+instrument_fastapi(app)
+```
+
+Each integration reports the matched **route template** (`/invoices/{pk}`),
+never the concrete path, so identifiers in URLs stay out of telemetry and the
+graph sees one endpoint instead of one per request.
+
+## Primitives
+
+```python
+TELLANN.track_api("POST", "/invoices/{pk}", 201, duration_ms=12.5)
+TELLANN.track_state("AWAITING_PAYMENT", previous_state="DRAFT")
+TELLANN.capture_error(error)
+TELLANN.track_event("BUSINESS_EVENT", {"plan": "pro"})
+
+with TELLANN.workflow("checkout") as workflow_id:
+    charge(...)          # failure fails the workflow and re-raises
+```
+
+## Behaviour under load and failure
+
+Delivery runs on a daemon thread behind a bounded queue. A collector that is
+down, slow or unreachable costs a dropped event and nothing else — no blocked
+request, no raised exception, no unbounded memory. Events larger than the
+collector's 32 KB limit are dropped locally with a warning rather than sent and
+discarded on the other side.
+
+The package has **no runtime dependencies**; delivery uses only the standard
+library, so it never conflicts with the versions an application has pinned.
+
+## Development
+
+```bash
+python -m unittest discover -s tests
+```

tellann-0.1.0/README.md

@@ -0,0 +1,95 @@
+# tellann (Python SDK)
+
+Behaviour telemetry for Python services, matching `@tellann/backend-sdk` event
+for event. A Flow that crosses a React page and a Django view reaches the
+collector as one sequence.
+
+```bash
+python -m pip install tellann
+```
+
+## Initialize
+
+```python
+from tellann import TELLANN
+
+TELLANN.initialize(
+    endpoint="https://gateway.example.com",
+    application_id="...",
+    environment_id="...",
+    api_key="...",
+)
+TELLANN.verify_installation()
+```
+
+Every argument falls back to an environment variable — `TELLANN_GATEWAY_URL`,
+`TELLANN_INGESTION_KEY`, `TELLANN_APPLICATION_ID`, `TELLANN_ENVIRONMENT_ID` —
+so `TELLANN.initialize()` with no arguments works wherever those are set. If
+the endpoint or application id is missing the SDK disables itself rather than
+raising: telemetry that is not configured must not stop an application booting.
+
+## Frameworks
+
+**Django** — add the middleware and initialize from `settings.py`:
+
+```python
+from tellann.integrations.django_middleware import instrument_django
+
+instrument_django()
+
+MIDDLEWARE = [
+    "tellann.integrations.django_middleware.TellannMiddleware",
+    # ... your middleware
+]
+```
+
+**Flask** — attach to the application, including inside a factory:
+
+```python
+from tellann import instrument_flask
+
+app = Flask(__name__)
+instrument_flask(app)
+```
+
+**FastAPI / Starlette** — attach to the application:
+
+```python
+from tellann import instrument_fastapi
+
+app = FastAPI()
+instrument_fastapi(app)
+```
+
+Each integration reports the matched **route template** (`/invoices/{pk}`),
+never the concrete path, so identifiers in URLs stay out of telemetry and the
+graph sees one endpoint instead of one per request.
+
+## Primitives
+
+```python
+TELLANN.track_api("POST", "/invoices/{pk}", 201, duration_ms=12.5)
+TELLANN.track_state("AWAITING_PAYMENT", previous_state="DRAFT")
+TELLANN.capture_error(error)
+TELLANN.track_event("BUSINESS_EVENT", {"plan": "pro"})
+
+with TELLANN.workflow("checkout") as workflow_id:
+    charge(...)          # failure fails the workflow and re-raises
+```
+
+## Behaviour under load and failure
+
+Delivery runs on a daemon thread behind a bounded queue. A collector that is
+down, slow or unreachable costs a dropped event and nothing else — no blocked
+request, no raised exception, no unbounded memory. Events larger than the
+collector's 32 KB limit are dropped locally with a warning rather than sent and
+discarded on the other side.
+
+The package has **no runtime dependencies**; delivery uses only the standard
+library, so it never conflicts with the versions an application has pinned.
+
+## Development
+
+```bash
+python -m unittest discover -s tests
+```

tellann-0.1.0/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@tellann/python-sdk",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Workspace entry for the Tellann Python SDK. The package itself is published to PyPI as `tellann`; this manifest exists so changesets versions it alongside the npm SDKs and turbo runs its tests.",
+  "scripts": {
+    "test": "python -m unittest discover -s tests"
+  }
+}

tellann-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tellann"
+version = "0.1.0"
+description = "Tellann SDK for Python: behaviour telemetry for Django, Flask, FastAPI and Starlette applications."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Tellann" }]
+keywords = ["telemetry", "observability", "django", "flask", "fastapi"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "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 :: System :: Monitoring",
+]
+# No runtime dependencies on purpose: the SDK is installed into applications
+# that pin their own versions of everything, and delivery needs only the
+# standard library.
+dependencies = []
+
+[project.optional-dependencies]
+django = ["Django>=3.2"]
+flask = ["Flask>=2.0"]
+fastapi = ["fastapi>=0.95"]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://tellann.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tellann"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

tellann-0.1.0/src/tellann/__init__.py

@@ -0,0 +1,74 @@
+"""Tellann SDK for Python.
+
+The public surface mirrors `@tellann/backend-sdk`, so the same concepts appear
+under the same names in both languages::
+
+    from tellann import TELLANN
+
+    TELLANN.initialize(
+        endpoint="https://gateway.example.com",
+        application_id="...",
+        environment_id="...",
+    )
+    TELLANN.verify_installation()
+
+Framework integrations are imported on demand, so installing this package never
+requires a framework the project does not use.
+"""
+
+from __future__ import annotations
+
+from .client import TELLANN, TellannBackend
+from .events import EVENT_TYPES, MAX_EVENT_BYTES, SOURCE, TellannEvent
+from .transport import EventTransport
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EVENT_TYPES",
+    "EventTransport",
+    "MAX_EVENT_BYTES",
+    "SOURCE",
+    "TELLANN",
+    "TellannBackend",
+    "TellannEvent",
+    "__version__",
+    "capture_error",
+    "checkpoint",
+    "instrument_django",
+    "instrument_fastapi",
+    "instrument_flask",
+    "instrument_starlette",
+    "track_api",
+    "track_event",
+    "track_state",
+]
+
+
+def track_api(*args, **kwargs) -> None:
+    """Module-level helper, matching the JavaScript SDK's loose functions."""
+    TELLANN.track_api(*args, **kwargs)
+
+
+def track_event(*args, **kwargs) -> None:
+    TELLANN.track_event(*args, **kwargs)
+
+
+def track_state(*args, **kwargs) -> None:
+    TELLANN.track_state(*args, **kwargs)
+
+
+def capture_error(*args, **kwargs) -> None:
+    TELLANN.capture_error(*args, **kwargs)
+
+
+def checkpoint(*args, **kwargs) -> None:
+    TELLANN.checkpoint(*args, **kwargs)
+
+
+def __getattr__(name: str):
+    if name.startswith("instrument_"):
+        from . import integrations
+
+        return getattr(integrations, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tellann-0.1.0/src/tellann/client.py

@@ -0,0 +1,307 @@
+"""The `TELLANN` singleton, mirroring `@tellann/backend-sdk`.
+
+Method names are snake_case because this is Python, but every one of them has a
+camelCase counterpart in the JavaScript SDK and produces an identical event. A
+Flow instrumented across a React page and a Django view therefore reaches the
+collector as one sequence, not two dialects of one.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import threading
+import time
+import traceback
+import uuid
+from typing import Any, Dict, Iterator, Optional
+
+from .events import EVENT_TYPES, SOURCE, TellannEvent
+from .transport import EventTransport
+
+#: Environment variables read when `initialize` is called without arguments.
+#: The names match what the desktop instrumenter writes into `.env`.
+ENV_ENDPOINT = "TELLANN_GATEWAY_URL"
+ENV_API_KEY = "TELLANN_INGESTION_KEY"
+ENV_APPLICATION_ID = "TELLANN_APPLICATION_ID"
+ENV_ENVIRONMENT_ID = "TELLANN_ENVIRONMENT_ID"
+
+
+class TellannBackend:
+    """Configuration, session identity and event construction."""
+
+    def __init__(self) -> None:
+        self._transport: Optional[EventTransport] = None
+        self._config: Optional[Dict[str, Any]] = None
+        self._workflows: Dict[str, Dict[str, Any]] = {}
+        self._lock = threading.Lock()
+
+    # ── lifecycle ─────────────────────────────────────────────────────────────
+
+    def initialize(
+        self,
+        endpoint: Optional[str] = None,
+        *,
+        application_id: Optional[str] = None,
+        api_key: Optional[str] = None,
+        environment_id: Optional[str] = None,
+        tenant_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        trace_id: Optional[str] = None,
+        agent_version: Optional[str] = None,
+        instrumentation_manifest_version: Optional[str] = None,
+        transport: Optional[EventTransport] = None,
+    ) -> "TellannBackend":
+        """Configure the SDK.
+
+        Every argument falls back to its environment variable, so a generated
+        module can call `initialize()` with no arguments and still work in an
+        environment where the values are supplied by deployment rather than by
+        the checked-in source.
+        """
+        resolved_endpoint = endpoint or os.environ.get(ENV_ENDPOINT)
+        resolved_application = application_id or os.environ.get(ENV_APPLICATION_ID)
+        if not resolved_endpoint or not resolved_application:
+            # Misconfiguration disables the SDK rather than raising: telemetry
+            # that is not set up must not stop an application from booting.
+            self._config = None
+            return self
+
+        self._config = {
+            "endpoint": resolved_endpoint.rstrip("/"),
+            "application_id": resolved_application,
+            "environment_id": environment_id or os.environ.get(ENV_ENVIRONMENT_ID),
+            "tenant_id": tenant_id or "unknown",
+            "session_id": session_id or str(uuid.uuid4()),
+            "run_id": run_id or os.environ.get("TELLANN_RUN_ID"),
+            "trace_id": trace_id or os.environ.get("TELLANN_TRACE_ID"),
+            "agent_version": agent_version,
+            "instrumentation_manifest_version": instrumentation_manifest_version,
+        }
+        self._transport = transport or EventTransport(
+            self._config["endpoint"], api_key or os.environ.get(ENV_API_KEY)
+        )
+        return self
+
+    def is_initialized(self) -> bool:
+        return self._config is not None
+
+    def get_config(self) -> Optional[Dict[str, Any]]:
+        return dict(self._config) if self._config else None
+
+    def teardown(self) -> None:
+        """Release the worker thread. Used by tests and by worker shutdown."""
+        if self._transport is not None:
+            self._transport.close()
+        self._transport = None
+        self._config = None
+        self._workflows.clear()
+
+    def flush(self, timeout: Optional[float] = None) -> None:
+        if self._transport is not None:
+            self._transport.flush(timeout)
+
+    # ── event construction ────────────────────────────────────────────────────
+
+    def track_event(
+        self,
+        event_type: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+    ) -> None:
+        """Send one event. Unknown event types are sent as given.
+
+        The collector owns the authoritative list, and refusing to send a type
+        this SDK version has not heard of would make every new event type a
+        blocking SDK upgrade.
+        """
+        if self._config is None or self._transport is None:
+            return
+        event = TellannEvent(
+            event_type=event_type,
+            application_id=self._config["application_id"],
+            session_id=session_id or self._config["session_id"],
+            tenant_id=self._config["tenant_id"],
+            environment_id=self._config["environment_id"],
+            run_id=self._config["run_id"],
+            trace_id=self._config["trace_id"],
+            agent_version=self._config["agent_version"],
+            instrumentation_manifest_version=self._config["instrumentation_manifest_version"],
+            metadata=metadata or {},
+            source=SOURCE,
+        )
+        self._transport.send(event.to_payload())
+
+    def verify_installation(self, session_id: Optional[str] = None) -> None:
+        """Prove the SDK is wired up, which is what marks the target connected."""
+        self.track_event(
+            "TELLANN_INITIALIZED",
+            {"source": "manual_verification", "verificationKind": "BOOTSTRAP_INITIALIZED"},
+            session_id,
+        )
+
+    # ── the four primitives the JavaScript SDK exposes ────────────────────────
+
+    def track_api(
+        self,
+        method: str,
+        route: str,
+        status_code: Optional[int] = None,
+        duration_ms: Optional[float] = None,
+        *,
+        session_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        payload: Dict[str, Any] = {"method": str(method).upper(), "route": route}
+        if status_code is not None:
+            payload["statusCode"] = int(status_code)
+        if duration_ms is not None:
+            payload["durationMs"] = round(float(duration_ms), 3)
+        payload.update(metadata or {})
+        self.track_event("API_REQUEST", payload, session_id)
+
+    def capture_error(
+        self,
+        error: BaseException | str,
+        *,
+        session_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        if isinstance(error, BaseException):
+            payload: Dict[str, Any] = {
+                "message": str(error),
+                "type": type(error).__name__,
+                # Bounded: a deep stack in a hot error path would otherwise
+                # push the event past the collector's size limit.
+                "stack": "".join(traceback.format_exception(error))[:4_000],
+            }
+        else:
+            payload = {"message": str(error), "type": "Error"}
+        payload.update(metadata or {})
+        self.track_event("SERVER_ERROR", payload, session_id)
+
+    def capture_message(
+        self,
+        message: str,
+        severity: str = "error",
+        session_id: Optional[str] = None,
+    ) -> None:
+        self.track_event("SERVER_ERROR", {"message": message, "severity": severity}, session_id)
+
+    def track_state(
+        self,
+        state: str,
+        *,
+        previous_state: Optional[str] = None,
+        session_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        payload: Dict[str, Any] = {"state": state}
+        if previous_state:
+            payload["previousState"] = previous_state
+        payload.update(metadata or {})
+        self.track_event(
+            "STATE_TRANSITION" if previous_state else "STATE_ENTERED", payload, session_id
+        )
+
+    # ── workflows ─────────────────────────────────────────────────────────────
+
+    def start_workflow(self, workflow_name: str, session_id: Optional[str] = None) -> str:
+        workflow_id = str(uuid.uuid4())
+        with self._lock:
+            self._workflows[workflow_id] = {"name": workflow_name, "started": time.monotonic()}
+        self.track_event(
+            "WORKFLOW_STARTED", {"workflowId": workflow_id, "workflowName": workflow_name}, session_id
+        )
+        return workflow_id
+
+    def _finish_workflow(self, workflow_id: str) -> Optional[Dict[str, Any]]:
+        with self._lock:
+            record = self._workflows.pop(workflow_id, None)
+        if record is None:
+            return None
+        return {
+            "workflowName": record["name"],
+            "durationMs": round((time.monotonic() - record["started"]) * 1000, 3),
+        }
+
+    def complete_workflow(self, workflow_id: str, session_id: Optional[str] = None) -> None:
+        result = self._finish_workflow(workflow_id)
+        if result:
+            self.track_event("WORKFLOW_COMPLETED", {"workflowId": workflow_id, **result}, session_id)
+
+    def fail_workflow(
+        self, workflow_id: str, reason: Optional[str] = None, session_id: Optional[str] = None
+    ) -> None:
+        result = self._finish_workflow(workflow_id)
+        if result:
+            self.track_event(
+                "WORKFLOW_FAILED",
+                {"workflowId": workflow_id, "reason": reason or "Unknown error", **result},
+                session_id,
+            )
+
+    def cancel_workflow(
+        self, workflow_id: str, reason: Optional[str] = None, session_id: Optional[str] = None
+    ) -> None:
+        result = self._finish_workflow(workflow_id)
+        if result:
+            self.track_event(
+                "WORKFLOW_CANCELLED",
+                {"workflowId": workflow_id, "reason": reason or "Cancelled", **result},
+                session_id,
+            )
+
+    def abandon_workflow(self, workflow_id: str) -> None:
+        with self._lock:
+            self._workflows.pop(workflow_id, None)
+
+    @contextlib.contextmanager
+    def workflow(self, workflow_name: str, session_id: Optional[str] = None) -> Iterator[str]:
+        """Run a block as a workflow, failing it if the block raises."""
+        workflow_id = self.start_workflow(workflow_name, session_id)
+        try:
+            yield workflow_id
+        except BaseException as error:
+            self.fail_workflow(workflow_id, str(error), session_id)
+            raise
+        else:
+            self.complete_workflow(workflow_id, session_id)
+
+    # ── Flow checkpoints ──────────────────────────────────────────────────────
+
+    def checkpoint(
+        self,
+        checkpoint_id: str,
+        *,
+        event_type: str = "FLOW_STATE_REACHED",
+        state_id: Optional[str] = None,
+        transition_id: Optional[str] = None,
+        terminal_kind: Optional[str] = None,
+        flow_initialization_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Mark a declared Flow checkpoint.
+
+        This is what the instrumenter inserts into application code, so its
+        signature is a contract: changing it breaks every file already patched.
+        """
+        payload: Dict[str, Any] = {"checkpointId": checkpoint_id}
+        if state_id:
+            payload["stateId"] = state_id
+        if transition_id:
+            payload["transitionId"] = transition_id
+        if terminal_kind:
+            payload["terminalKind"] = terminal_kind
+        if flow_initialization_id:
+            payload["flowInitializationId"] = flow_initialization_id
+        payload.update(metadata or {})
+        self.track_event(
+            event_type if event_type in EVENT_TYPES else "FLOW_STATE_REACHED", payload, session_id
+        )
+
+
+#: The module-level singleton, matching the JavaScript SDK's `TELLANN` export.
+TELLANN = TellannBackend()