obtrace-sdk-python 1.0.0__tar.gz

obtrace_sdk_python-1.0.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: obtrace-sdk-python
+Version: 1.0.0
+Summary: Obtrace Python SDK
+Author: Obtrace
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: requests
+Requires-Dist: requests>=2.31.0; extra == "requests"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27.0; extra == "httpx"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.112.0; extra == "fastapi"
+Requires-Dist: starlette>=0.37.0; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=3.0.0; extra == "flask"
+
+# obtrace-sdk-python
+
+Python backend SDK for Obtrace telemetry transport and instrumentation.
+
+## Scope
+- OTLP logs/traces/metrics transport
+- Context propagation
+- HTTP instrumentation (requests/httpx)
+- Framework helpers (FastAPI, Flask)
+
+## Design Principle
+SDK is thin/dumb.
+- No business logic authority in client SDK.
+- Policy and product logic are server-side.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Configuration
+
+Required:
+- `api_key`
+- `ingest_base_url`
+- `service_name`
+
+Optional (auto-resolved from API key on the server side):
+- `tenant_id`
+- `project_id`
+- `app_id`
+- `env`
+- `service_version`
+
+## Quickstart
+
+### Simplified setup
+
+The API key resolves `tenant_id`, `project_id`, `app_id`, and `env` automatically on the server side, so only three fields are needed:
+
+```python
+from obtrace_sdk import ObtraceClient, ObtraceConfig
+
+client = ObtraceClient(
+    ObtraceConfig(
+        api_key="obt_live_...",
+        ingest_base_url="https://ingest.obtrace.io",
+        service_name="my-service",
+    )
+)
+```
+
+### Full configuration
+
+For advanced use cases you can override the resolved values explicitly:
+
+```python
+from obtrace_sdk import ObtraceClient, ObtraceConfig, SemanticMetrics
+
+client = ObtraceClient(
+    ObtraceConfig(
+        api_key="<API_KEY>",
+        ingest_base_url="https://inject.obtrace.ai",
+        service_name="python-api",
+        env="prod",
+    )
+)
+
+client.log("info", "started")
+client.metric(SemanticMetrics.RUNTIME_CPU_UTILIZATION, 0.41)
+client.span(
+    "checkout.charge",
+    attrs={
+        "feature.name": "checkout",
+        "payment.provider": "stripe",
+    },
+)
+client.flush()
+```
+
+## Canonical metrics and custom spans
+
+- Use `SemanticMetrics` for the product-wide metric catalog.
+- Custom spans use `client.span(name, attrs=...)`.
+- Keep free-form metric names only for truly product-specific signals that are not part of the shared catalog.
+
+## Frameworks and HTTP
+
+- Framework helpers: FastAPI and Flask
+- HTTP instrumentation: `requests` and `httpx`
+- Reference docs:
+  - `docs/frameworks.md`
+  - `docs/http-instrumentation.md`
+
+## Production Hardening
+
+1. Keep `api_key` only in server-side secret storage.
+2. Use one key per environment and rotate periodically.
+3. Keep fail-open behavior (telemetry must not break request flow).
+4. Validate ingestion after deploy using Query Gateway and ClickHouse checks.
+
+## Troubleshooting
+
+- No telemetry: validate `ingest_base_url`, API key, and egress connectivity.
+- Missing correlation: ensure propagation headers are injected on outbound HTTP.
+- Short-lived workers: call `flush()` before process exit.
+
+## Documentation
+- Docs index: `docs/index.md`
+- LLM context file: `llm.txt`
+- MCP metadata: `mcp.json`
+
+## Reference

obtrace_sdk_python-1.0.0/README.md

@@ -0,0 +1,114 @@
+# obtrace-sdk-python
+
+Python backend SDK for Obtrace telemetry transport and instrumentation.
+
+## Scope
+- OTLP logs/traces/metrics transport
+- Context propagation
+- HTTP instrumentation (requests/httpx)
+- Framework helpers (FastAPI, Flask)
+
+## Design Principle
+SDK is thin/dumb.
+- No business logic authority in client SDK.
+- Policy and product logic are server-side.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Configuration
+
+Required:
+- `api_key`
+- `ingest_base_url`
+- `service_name`
+
+Optional (auto-resolved from API key on the server side):
+- `tenant_id`
+- `project_id`
+- `app_id`
+- `env`
+- `service_version`
+
+## Quickstart
+
+### Simplified setup
+
+The API key resolves `tenant_id`, `project_id`, `app_id`, and `env` automatically on the server side, so only three fields are needed:
+
+```python
+from obtrace_sdk import ObtraceClient, ObtraceConfig
+
+client = ObtraceClient(
+    ObtraceConfig(
+        api_key="obt_live_...",
+        ingest_base_url="https://ingest.obtrace.io",
+        service_name="my-service",
+    )
+)
+```
+
+### Full configuration
+
+For advanced use cases you can override the resolved values explicitly:
+
+```python
+from obtrace_sdk import ObtraceClient, ObtraceConfig, SemanticMetrics
+
+client = ObtraceClient(
+    ObtraceConfig(
+        api_key="<API_KEY>",
+        ingest_base_url="https://inject.obtrace.ai",
+        service_name="python-api",
+        env="prod",
+    )
+)
+
+client.log("info", "started")
+client.metric(SemanticMetrics.RUNTIME_CPU_UTILIZATION, 0.41)
+client.span(
+    "checkout.charge",
+    attrs={
+        "feature.name": "checkout",
+        "payment.provider": "stripe",
+    },
+)
+client.flush()
+```
+
+## Canonical metrics and custom spans
+
+- Use `SemanticMetrics` for the product-wide metric catalog.
+- Custom spans use `client.span(name, attrs=...)`.
+- Keep free-form metric names only for truly product-specific signals that are not part of the shared catalog.
+
+## Frameworks and HTTP
+
+- Framework helpers: FastAPI and Flask
+- HTTP instrumentation: `requests` and `httpx`
+- Reference docs:
+  - `docs/frameworks.md`
+  - `docs/http-instrumentation.md`
+
+## Production Hardening
+
+1. Keep `api_key` only in server-side secret storage.
+2. Use one key per environment and rotate periodically.
+3. Keep fail-open behavior (telemetry must not break request flow).
+4. Validate ingestion after deploy using Query Gateway and ClickHouse checks.
+
+## Troubleshooting
+
+- No telemetry: validate `ingest_base_url`, API key, and egress connectivity.
+- Missing correlation: ensure propagation headers are injected on outbound HTTP.
+- Short-lived workers: call `flush()` before process exit.
+
+## Documentation
+- Docs index: `docs/index.md`
+- LLM context file: `llm.txt`
+- MCP metadata: `mcp.json`
+
+## Reference

obtrace_sdk_python-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "obtrace-sdk-python"
+version = "1.0.0"
+description = "Obtrace Python SDK"
+classifiers = ["License :: OSI Approved :: MIT License"]
+requires-python = ">=3.10"
+readme = "README.md"
+authors = [{ name = "Obtrace" }]
+dependencies = []
+
+[project.optional-dependencies]
+requests = ["requests>=2.31.0"]
+httpx = ["httpx>=0.27.0"]
+fastapi = ["fastapi>=0.112.0", "starlette>=0.37.0"]
+flask = ["flask>=3.0.0"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

obtrace_sdk_python-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

obtrace_sdk_python-1.0.0/src/obtrace_sdk/__init__.py

@@ -0,0 +1,12 @@
+from .client import ObtraceClient, ObtraceConfig
+from .context import create_traceparent, ensure_propagation_headers
+from .semantic_metrics import SemanticMetrics, is_semantic_metric
+
+__all__ = [
+    "ObtraceClient",
+    "ObtraceConfig",
+    "SemanticMetrics",
+    "is_semantic_metric",
+    "create_traceparent",
+    "ensure_propagation_headers",
+]

obtrace_sdk_python-1.0.0/src/obtrace_sdk/client.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import atexit
+import json
+import threading
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .context import ensure_propagation_headers, random_hex
+from .otlp import build_logs_payload, build_metric_payload, build_span_payload
+from .semantic_metrics import is_semantic_metric
+from .types import ObtraceConfig, SDKContext
+
+
+@dataclass(slots=True)
+class _Queued:
+    endpoint: str
+    payload: Dict[str, Any]
+
+
+class ObtraceClient:
+    def __init__(self, cfg: ObtraceConfig):
+        if not cfg.api_key or not cfg.ingest_base_url or not cfg.service_name:
+            raise ValueError("api_key, ingest_base_url and service_name are required")
+        self.cfg = cfg
+        self._queue: List[_Queued] = []
+        self._lock = threading.Lock()
+        self._circuit_failures = 0
+        self._circuit_open_until = 0.0
+        atexit.register(self.flush)
+
+    def __enter__(self) -> ObtraceClient:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.flush()
+
+    @staticmethod
+    def _truncate(s: str, max_len: int) -> str:
+        if len(s) <= max_len:
+            return s
+        return s[:max_len] + "...[truncated]"
+
+    def log(self, level: str, message: str, context: Optional[SDKContext] = None) -> None:
+        self._enqueue("/otlp/v1/logs", build_logs_payload(self.cfg, level, self._truncate(message, 32768), context))
+
+    def metric(self, name: str, value: float, unit: str = "1", context: Optional[SDKContext] = None) -> None:
+        if self.cfg.validate_semantic_metrics and self.cfg.debug and not is_semantic_metric(name):
+            print(f"[obtrace-sdk-python] non-canonical metric name: {name}")
+        self._enqueue("/otlp/v1/metrics", build_metric_payload(self.cfg, self._truncate(name, 1024), value, unit, context))
+
+    def span(
+        self,
+        name: str,
+        trace_id: Optional[str] = None,
+        span_id: Optional[str] = None,
+        start_unix_nano: Optional[str] = None,
+        end_unix_nano: Optional[str] = None,
+        status_code: Optional[int] = None,
+        status_message: str = "",
+        attrs: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, str]:
+        t = trace_id if trace_id and len(trace_id) == 32 else random_hex(16)
+        s = span_id if span_id and len(span_id) == 16 else random_hex(8)
+        start = start_unix_nano or str(int(time.time() * 1_000_000_000))
+        end = end_unix_nano or str(int(time.time() * 1_000_000_000))
+
+        truncated_name = self._truncate(name, 32768)
+        if attrs:
+            attrs = {k: self._truncate(v, 4096) if isinstance(v, str) else v for k, v in attrs.items()}
+
+        self._enqueue(
+            "/otlp/v1/traces",
+            build_span_payload(self.cfg, truncated_name, t, s, start, end, status_code, status_message, attrs),
+        )
+        return {"trace_id": t, "span_id": s}
+
+    def inject_propagation(
+        self,
+        headers: Optional[Dict[str, str]] = None,
+        trace_id: Optional[str] = None,
+        span_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ) -> Dict[str, str]:
+        return ensure_propagation_headers(headers, trace_id, span_id, session_id)
+
+    def flush(self) -> None:
+        with self._lock:
+            now = time.time()
+            if now < self._circuit_open_until:
+                return
+            half_open = self._circuit_failures >= 5
+            if half_open:
+                batch = self._queue[:1]
+                self._queue = self._queue[1:]
+            else:
+                batch = list(self._queue)
+                self._queue.clear()
+
+        for item in batch:
+            try:
+                self._send(item)
+                with self._lock:
+                    if self._circuit_failures > 0:
+                        if self.cfg.debug:
+                            print("[obtrace-sdk-python] circuit breaker closed")
+                        self._circuit_failures = 0
+                        self._circuit_open_until = 0.0
+            except Exception:  # noqa: BLE001
+                with self._lock:
+                    self._circuit_failures += 1
+                    if self._circuit_failures >= 5:
+                        self._circuit_open_until = time.time() + 30.0
+                        if self.cfg.debug:
+                            print("[obtrace-sdk-python] circuit breaker opened")
+                if self.cfg.debug:
+                    import traceback
+                    traceback.print_exc()
+
+    def shutdown(self) -> None:
+        self.flush()
+
+    def _enqueue(self, endpoint: str, payload: Dict[str, Any]) -> None:
+        with self._lock:
+            if len(self._queue) >= self.cfg.max_queue_size:
+                if self.cfg.debug:
+                    print(f"[obtrace-sdk-python] queue full, dropping oldest item")
+                self._queue.pop(0)
+            self._queue.append(_Queued(endpoint=endpoint, payload=payload))
+
+    def _send(self, item: _Queued) -> None:
+        try:
+            body = json.dumps(item.payload).encode("utf-8")
+        except (TypeError, ValueError):
+            if self.cfg.debug:
+                print(f"[obtrace-sdk-python] failed to serialize payload for {item.endpoint}")
+            return
+
+        req = urllib.request.Request(
+            url=f"{self.cfg.ingest_base_url.rstrip('/')}{item.endpoint}",
+            method="POST",
+            data=body,
+            headers={
+                **self.cfg.default_headers,
+                "Authorization": f"Bearer {self.cfg.api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.cfg.request_timeout_sec) as res:
+                code = int(getattr(res, "status", 200))
+                if code >= 300 and self.cfg.debug:
+                    print(f"[obtrace-sdk-python] status={code} endpoint={item.endpoint}")
+        except (urllib.error.URLError, TypeError, ValueError, OSError) as exc:
+            if self.cfg.debug:
+                print(f"[obtrace-sdk-python] send failed endpoint={item.endpoint} err={exc}")

obtrace_sdk_python-1.0.0/src/obtrace_sdk/context.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import secrets
+from typing import Dict, Optional
+
+
+def random_hex(nbytes: int) -> str:
+    return secrets.token_hex(nbytes)
+
+
+def create_traceparent(trace_id: Optional[str] = None, span_id: Optional[str] = None) -> str:
+    t = trace_id if trace_id and len(trace_id) == 32 else random_hex(16)
+    s = span_id if span_id and len(span_id) == 16 else random_hex(8)
+    return f"00-{t}-{s}-01"
+
+
+def ensure_propagation_headers(
+    headers: Optional[Dict[str, str]] = None,
+    trace_id: Optional[str] = None,
+    span_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+    trace_header_name: str = "traceparent",
+    session_header_name: str = "x-obtrace-session-id",
+) -> Dict[str, str]:
+    out = dict(headers or {})
+    lower = {k.lower(): k for k in out.keys()}
+    if trace_header_name.lower() not in lower:
+        out[trace_header_name] = create_traceparent(trace_id, span_id)
+    if session_id and session_header_name.lower() not in lower:
+        out[session_header_name] = session_id
+    return out

obtrace_sdk_python-1.0.0/src/obtrace_sdk/http.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Optional
+
+from .client import ObtraceClient
+from .types import SDKContext
+
+
+def instrument_requests(client: ObtraceClient, request_func: Callable[..., Any]) -> Callable[..., Any]:
+    def wrapped(method: str, url: str, **kwargs: Any) -> Any:
+        started = time.time()
+        trace = client.span(f"http.client {method.upper()}", attrs={"http.method": method.upper(), "http.url": url})
+
+        headers = dict(kwargs.pop("headers", {}) or {})
+        headers = client.inject_propagation(headers, trace_id=trace["trace_id"], span_id=trace["span_id"])
+        kwargs["headers"] = headers
+
+        try:
+            res = request_func(method, url, **kwargs)
+            dur_ms = int((time.time() - started) * 1000)
+            client.log(
+                "info",
+                f"requests {method.upper()} {url} -> {getattr(res, 'status_code', 200)}",
+                SDKContext(
+                    trace_id=trace["trace_id"],
+                    span_id=trace["span_id"],
+                    method=method.upper(),
+                    endpoint=url,
+                    status_code=int(getattr(res, "status_code", 200)),
+                    attrs={"duration_ms": dur_ms},
+                ),
+            )
+            return res
+        except Exception as exc:  # noqa: BLE001
+            dur_ms = int((time.time() - started) * 1000)
+            client.log(
+                "error",
+                f"requests {method.upper()} {url} failed: {exc}",
+                SDKContext(
+                    trace_id=trace["trace_id"],
+                    span_id=trace["span_id"],
+                    method=method.upper(),
+                    endpoint=url,
+                    attrs={"duration_ms": dur_ms},
+                ),
+            )
+            raise
+
+    return wrapped
+
+
+def instrument_httpx(client: ObtraceClient, request_func: Callable[..., Any]) -> Callable[..., Any]:
+    async def wrapped(method: str, url: str, **kwargs: Any) -> Any:
+        started = time.time()
+        trace = client.span(f"http.client {method.upper()}", attrs={"http.method": method.upper(), "http.url": url})
+
+        headers = dict(kwargs.pop("headers", {}) or {})
+        headers = client.inject_propagation(headers, trace_id=trace["trace_id"], span_id=trace["span_id"])
+        kwargs["headers"] = headers
+
+        try:
+            res = await request_func(method, url, **kwargs)
+            dur_ms = int((time.time() - started) * 1000)
+            client.log(
+                "info",
+                f"httpx {method.upper()} {url} -> {getattr(res, 'status_code', 200)}",
+                SDKContext(
+                    trace_id=trace["trace_id"],
+                    span_id=trace["span_id"],
+                    method=method.upper(),
+                    endpoint=url,
+                    status_code=int(getattr(res, "status_code", 200)),
+                    attrs={"duration_ms": dur_ms},
+                ),
+            )
+            return res
+        except Exception as exc:  # noqa: BLE001
+            dur_ms = int((time.time() - started) * 1000)
+            client.log(
+                "error",
+                f"httpx {method.upper()} {url} failed: {exc}",
+                SDKContext(
+                    trace_id=trace["trace_id"],
+                    span_id=trace["span_id"],
+                    method=method.upper(),
+                    endpoint=url,
+                    attrs={"duration_ms": dur_ms},
+                ),
+            )
+            raise
+
+    return wrapped
+
+
+def fastapi_middleware(client: ObtraceClient):
+    async def middleware(request: Any, call_next: Callable[..., Any]) -> Any:
+        started = time.time()
+        trace = client.span(
+            f"http.server {getattr(request, 'method', 'GET')}",
+            attrs={"http.method": getattr(request, "method", "GET"), "http.route": str(getattr(request, "url", ""))},
+        )
+        try:
+            response = await call_next(request)
+            dur_ms = int((time.time() - started) * 1000)
+            client.log(
+                "info",
+                f"fastapi {request.method} {request.url.path} {response.status_code}",
+                SDKContext(
+                    trace_id=trace["trace_id"],
+                    span_id=trace["span_id"],
+                    method=request.method,
+                    endpoint=request.url.path,
+                    status_code=response.status_code,
+                    attrs={"duration_ms": dur_ms},
+                ),
+            )
+            return response
+        except Exception as exc:  # noqa: BLE001
+            dur_ms = int((time.time() - started) * 1000)
+            client.log(
+                "error",
+                f"fastapi request failed: {exc}",
+                SDKContext(
+                    trace_id=trace["trace_id"],
+                    span_id=trace["span_id"],
+                    method=getattr(request, "method", "GET"),
+                    endpoint=str(getattr(request, "url", "")),
+                    attrs={"duration_ms": dur_ms},
+                ),
+            )
+            raise
+
+    return middleware
+
+
+def flask_before_after(client: ObtraceClient):
+    def before() -> Dict[str, Any]:
+        started = time.time()
+        trace = client.span("http.server request")
+        return {"started": started, "trace": trace}
+
+    def after(meta: Dict[str, Any], method: str, path: str, status_code: int) -> None:
+        dur_ms = int((time.time() - meta["started"]) * 1000)
+        tr = meta["trace"]
+        client.log(
+            "info",
+            f"flask {method} {path} {status_code}",
+            SDKContext(
+                trace_id=tr["trace_id"],
+                span_id=tr["span_id"],
+                method=method,
+                endpoint=path,
+                status_code=status_code,
+                attrs={"duration_ms": dur_ms},
+            ),
+        )
+
+    return before, after

obtrace_sdk_python-1.0.0/src/obtrace_sdk/otlp.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+from .types import ObtraceConfig, SDKContext
+
+
+def _now_unix_nano_str() -> str:
+    return str(int(time.time() * 1_000_000_000))
+
+
+def _attrs(attrs: Optional[Dict[str, Any]]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    if not attrs:
+        return out
+    for k, v in attrs.items():
+        if isinstance(v, bool):
+            val = {"boolValue": v}
+        elif isinstance(v, (int, float)):
+            val = {"doubleValue": float(v)}
+        else:
+            val = {"stringValue": str(v)}
+        out.append({"key": str(k), "value": val})
+    return out
+
+
+def _resource(cfg: ObtraceConfig) -> list[dict[str, Any]]:
+    base: Dict[str, Any] = {
+        "service.name": cfg.service_name,
+        "service.version": cfg.service_version,
+        "deployment.environment": cfg.env or "dev",
+        "runtime.name": "python",
+    }
+    if cfg.tenant_id:
+        base["obtrace.tenant_id"] = cfg.tenant_id
+    if cfg.project_id:
+        base["obtrace.project_id"] = cfg.project_id
+    if cfg.app_id:
+        base["obtrace.app_id"] = cfg.app_id
+    if cfg.env:
+        base["obtrace.env"] = cfg.env
+    return _attrs(base)
+
+
+def build_logs_payload(cfg: ObtraceConfig, level: str, body: str, ctx: Optional[SDKContext] = None) -> Dict[str, Any]:
+    context_attrs: Dict[str, Any] = {"obtrace.log.level": level}
+    if ctx:
+        if ctx.trace_id:
+            context_attrs["obtrace.trace_id"] = ctx.trace_id
+        if ctx.span_id:
+            context_attrs["obtrace.span_id"] = ctx.span_id
+        if ctx.session_id:
+            context_attrs["obtrace.session_id"] = ctx.session_id
+        if ctx.route_template:
+            context_attrs["obtrace.route_template"] = ctx.route_template
+        if ctx.endpoint:
+            context_attrs["obtrace.endpoint"] = ctx.endpoint
+        if ctx.method:
+            context_attrs["obtrace.method"] = ctx.method
+        if ctx.status_code is not None:
+            context_attrs["obtrace.status_code"] = ctx.status_code
+        for k, v in ctx.attrs.items():
+            context_attrs[f"obtrace.attr.{k}"] = v
+
+    return {
+        "resourceLogs": [
+            {
+                "resource": {"attributes": _resource(cfg)},
+                "scopeLogs": [
+                    {
+                        "scope": {"name": "obtrace-sdk-python", "version": "1.0.0"},
+                        "logRecords": [
+                            {
+                                "timeUnixNano": _now_unix_nano_str(),
+                                "severityText": level.upper(),
+                                "body": {"stringValue": body},
+                                "attributes": _attrs(context_attrs),
+                            }
+                        ],
+                    }
+                ],
+            }
+        ]
+    }
+
+
+def build_metric_payload(
+    cfg: ObtraceConfig,
+    metric_name: str,
+    value: float,
+    unit: str = "1",
+    ctx: Optional[SDKContext] = None,
+) -> Dict[str, Any]:
+    return {
+        "resourceMetrics": [
+            {
+                "resource": {"attributes": _resource(cfg)},
+                "scopeMetrics": [
+                    {
+                        "scope": {"name": "obtrace-sdk-python", "version": "1.0.0"},
+                        "metrics": [
+                            {
+                                "name": metric_name,
+                                "unit": unit,
+                                "gauge": {
+                                    "dataPoints": [
+                                        {
+                                            "timeUnixNano": _now_unix_nano_str(),
+                                            "asDouble": float(value),
+                                            "attributes": _attrs(ctx.attrs if ctx else None),
+                                        }
+                                    ]
+                                },
+                            }
+                        ],
+                    }
+                ],
+            }
+        ]
+    }
+
+
+def build_span_payload(
+    cfg: ObtraceConfig,
+    name: str,
+    trace_id: str,
+    span_id: str,
+    start_unix_nano: str,
+    end_unix_nano: str,
+    status_code: Optional[int] = None,
+    status_message: str = "",
+    attrs: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    return {
+        "resourceSpans": [
+            {
+                "resource": {"attributes": _resource(cfg)},
+                "scopeSpans": [
+                    {
+                        "scope": {"name": "obtrace-sdk-python", "version": "1.0.0"},
+                        "spans": [
+                            {
+                                "traceId": trace_id,
+                                "spanId": span_id,
+                                "name": name,
+                                "kind": 3,
+                                "startTimeUnixNano": start_unix_nano,
+                                "endTimeUnixNano": end_unix_nano,
+                                "attributes": _attrs(attrs),
+                                "status": {
+                                    "code": 2 if (status_code is not None and status_code >= 400) else 1,
+                                    "message": status_message,
+                                },
+                            }
+                        ],
+                    }
+                ],
+            }
+        ]
+    }

obtrace_sdk_python-1.0.0/src/obtrace_sdk/semantic_metrics.py

@@ -0,0 +1,50 @@
+class SemanticMetrics:
+    THROUGHPUT = "http_requests_total"
+    ERROR_RATE = "http_5xx_total"
+    LATENCY_P95 = "latency_p95"
+    RUNTIME_CPU_UTILIZATION = "runtime.cpu.utilization"
+    RUNTIME_MEMORY_USAGE = "runtime.memory.usage"
+    RUNTIME_THREAD_COUNT = "runtime.thread.count"
+    RUNTIME_GC_PAUSE = "runtime.gc.pause"
+    RUNTIME_EVENTLOOP_LAG = "runtime.eventloop.lag"
+    CLUSTER_CPU_UTILIZATION = "cluster.cpu.utilization"
+    CLUSTER_MEMORY_USAGE = "cluster.memory.usage"
+    CLUSTER_NODE_COUNT = "cluster.node.count"
+    CLUSTER_POD_COUNT = "cluster.pod.count"
+    DB_OPERATION_LATENCY = "db.operation.latency"
+    DB_CLIENT_ERRORS = "db.client.errors"
+    DB_CONNECTIONS_USAGE = "db.connections.usage"
+    MESSAGING_CONSUMER_LAG = "messaging.consumer.lag"
+    WEB_VITAL_LCP = "web.vital.lcp"
+    WEB_VITAL_FCP = "web.vital.fcp"
+    WEB_VITAL_INP = "web.vital.inp"
+    WEB_VITAL_CLS = "web.vital.cls"
+    WEB_VITAL_TTFB = "web.vital.ttfb"
+    USER_ACTIONS = "obtrace.sim.web.react.actions"
+
+
+def is_semantic_metric(name: str) -> bool:
+    return name in {
+        SemanticMetrics.THROUGHPUT,
+        SemanticMetrics.ERROR_RATE,
+        SemanticMetrics.LATENCY_P95,
+        SemanticMetrics.RUNTIME_CPU_UTILIZATION,
+        SemanticMetrics.RUNTIME_MEMORY_USAGE,
+        SemanticMetrics.RUNTIME_THREAD_COUNT,
+        SemanticMetrics.RUNTIME_GC_PAUSE,
+        SemanticMetrics.RUNTIME_EVENTLOOP_LAG,
+        SemanticMetrics.CLUSTER_CPU_UTILIZATION,
+        SemanticMetrics.CLUSTER_MEMORY_USAGE,
+        SemanticMetrics.CLUSTER_NODE_COUNT,
+        SemanticMetrics.CLUSTER_POD_COUNT,
+        SemanticMetrics.DB_OPERATION_LATENCY,
+        SemanticMetrics.DB_CLIENT_ERRORS,
+        SemanticMetrics.DB_CONNECTIONS_USAGE,
+        SemanticMetrics.MESSAGING_CONSUMER_LAG,
+        SemanticMetrics.WEB_VITAL_LCP,
+        SemanticMetrics.WEB_VITAL_FCP,
+        SemanticMetrics.WEB_VITAL_INP,
+        SemanticMetrics.WEB_VITAL_CLS,
+        SemanticMetrics.WEB_VITAL_TTFB,
+        SemanticMetrics.USER_ACTIONS,
+    }

obtrace_sdk_python-1.0.0/src/obtrace_sdk/types.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass(slots=True)
+class ObtraceConfig:
+    api_key: str
+    ingest_base_url: str
+    service_name: str
+    service_version: str = "0.0.0"
+    tenant_id: Optional[str] = None
+    project_id: Optional[str] = None
+    app_id: Optional[str] = None
+    env: Optional[str] = None
+    request_timeout_sec: float = 5.0
+    max_queue_size: int = 1000
+    validate_semantic_metrics: bool = False
+    debug: bool = False
+    default_headers: Dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class SDKContext:
+    trace_id: Optional[str] = None
+    span_id: Optional[str] = None
+    session_id: Optional[str] = None
+    route_template: Optional[str] = None
+    endpoint: Optional[str] = None
+    method: Optional[str] = None
+    status_code: Optional[int] = None
+    attrs: Dict[str, Any] = field(default_factory=dict)

obtrace_sdk_python-1.0.0/src/obtrace_sdk_python.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: obtrace-sdk-python
+Version: 1.0.0
+Summary: Obtrace Python SDK
+Author: Obtrace
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: requests
+Requires-Dist: requests>=2.31.0; extra == "requests"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27.0; extra == "httpx"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.112.0; extra == "fastapi"
+Requires-Dist: starlette>=0.37.0; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=3.0.0; extra == "flask"
+
+# obtrace-sdk-python
+
+Python backend SDK for Obtrace telemetry transport and instrumentation.
+
+## Scope
+- OTLP logs/traces/metrics transport
+- Context propagation
+- HTTP instrumentation (requests/httpx)
+- Framework helpers (FastAPI, Flask)
+
+## Design Principle
+SDK is thin/dumb.
+- No business logic authority in client SDK.
+- Policy and product logic are server-side.
+
+## Install
+
+```bash
+pip install .
+```
+
+## Configuration
+
+Required:
+- `api_key`
+- `ingest_base_url`
+- `service_name`
+
+Optional (auto-resolved from API key on the server side):
+- `tenant_id`
+- `project_id`
+- `app_id`
+- `env`
+- `service_version`
+
+## Quickstart
+
+### Simplified setup
+
+The API key resolves `tenant_id`, `project_id`, `app_id`, and `env` automatically on the server side, so only three fields are needed:
+
+```python
+from obtrace_sdk import ObtraceClient, ObtraceConfig
+
+client = ObtraceClient(
+    ObtraceConfig(
+        api_key="obt_live_...",
+        ingest_base_url="https://ingest.obtrace.io",
+        service_name="my-service",
+    )
+)
+```
+
+### Full configuration
+
+For advanced use cases you can override the resolved values explicitly:
+
+```python
+from obtrace_sdk import ObtraceClient, ObtraceConfig, SemanticMetrics
+
+client = ObtraceClient(
+    ObtraceConfig(
+        api_key="<API_KEY>",
+        ingest_base_url="https://inject.obtrace.ai",
+        service_name="python-api",
+        env="prod",
+    )
+)
+
+client.log("info", "started")
+client.metric(SemanticMetrics.RUNTIME_CPU_UTILIZATION, 0.41)
+client.span(
+    "checkout.charge",
+    attrs={
+        "feature.name": "checkout",
+        "payment.provider": "stripe",
+    },
+)
+client.flush()
+```
+
+## Canonical metrics and custom spans
+
+- Use `SemanticMetrics` for the product-wide metric catalog.
+- Custom spans use `client.span(name, attrs=...)`.
+- Keep free-form metric names only for truly product-specific signals that are not part of the shared catalog.
+
+## Frameworks and HTTP
+
+- Framework helpers: FastAPI and Flask
+- HTTP instrumentation: `requests` and `httpx`
+- Reference docs:
+  - `docs/frameworks.md`
+  - `docs/http-instrumentation.md`
+
+## Production Hardening
+
+1. Keep `api_key` only in server-side secret storage.
+2. Use one key per environment and rotate periodically.
+3. Keep fail-open behavior (telemetry must not break request flow).
+4. Validate ingestion after deploy using Query Gateway and ClickHouse checks.
+
+## Troubleshooting
+
+- No telemetry: validate `ingest_base_url`, API key, and egress connectivity.
+- Missing correlation: ensure propagation headers are injected on outbound HTTP.
+- Short-lived workers: call `flush()` before process exit.
+
+## Documentation
+- Docs index: `docs/index.md`
+- LLM context file: `llm.txt`
+- MCP metadata: `mcp.json`
+
+## Reference

obtrace_sdk_python-1.0.0/src/obtrace_sdk_python.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/obtrace_sdk/__init__.py
+src/obtrace_sdk/client.py
+src/obtrace_sdk/context.py
+src/obtrace_sdk/http.py
+src/obtrace_sdk/otlp.py
+src/obtrace_sdk/semantic_metrics.py
+src/obtrace_sdk/types.py
+src/obtrace_sdk_python.egg-info/PKG-INFO
+src/obtrace_sdk_python.egg-info/SOURCES.txt
+src/obtrace_sdk_python.egg-info/dependency_links.txt
+src/obtrace_sdk_python.egg-info/requires.txt
+src/obtrace_sdk_python.egg-info/top_level.txt
+tests/test_client.py
+tests/test_context.py
+tests/test_semantic_metrics.py

obtrace_sdk_python-1.0.0/src/obtrace_sdk_python.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

obtrace_sdk_python-1.0.0/src/obtrace_sdk_python.egg-info/requires.txt

@@ -0,0 +1,13 @@
+
+[fastapi]
+fastapi>=0.112.0
+starlette>=0.37.0
+
+[flask]
+flask>=3.0.0
+
+[httpx]
+httpx>=0.27.0
+
+[requests]
+requests>=2.31.0

obtrace_sdk_python-1.0.0/src/obtrace_sdk_python.egg-info/top_level.txt

@@ -0,0 +1 @@
+obtrace_sdk

obtrace_sdk_python-1.0.0/tests/test_client.py

@@ -0,0 +1,32 @@
+import unittest
+from unittest.mock import patch, MagicMock
+
+from obtrace_sdk.client import ObtraceClient
+from obtrace_sdk.types import ObtraceConfig
+
+
+class ClientTests(unittest.TestCase):
+    def test_enqueue_and_flush(self):
+        c = ObtraceClient(
+            ObtraceConfig(
+                api_key="devkey",
+                ingest_base_url="https://inject.obtrace.ai",
+                service_name="py-test",
+            )
+        )
+        c.log("info", "hello")
+        c.metric("m", 1)
+        c.span("s")
+
+        with patch("urllib.request.urlopen") as urlopen:
+            cm = MagicMock()
+            cm.__enter__.return_value.status = 202
+            cm.__exit__.return_value = False
+            urlopen.return_value = cm
+            c.flush()
+
+        self.assertEqual(urlopen.call_count, 3)
+
+
+if __name__ == "__main__":
+    unittest.main()

obtrace_sdk_python-1.0.0/tests/test_context.py

@@ -0,0 +1,21 @@
+import unittest
+
+from obtrace_sdk.context import create_traceparent, ensure_propagation_headers
+
+
+class ContextTests(unittest.TestCase):
+    def test_create_traceparent(self):
+        tp = create_traceparent()
+        self.assertTrue(tp.startswith("00-"))
+        parts = tp.split("-")
+        self.assertEqual(len(parts[1]), 32)
+        self.assertEqual(len(parts[2]), 16)
+
+    def test_ensure_propagation_headers(self):
+        out = ensure_propagation_headers({}, session_id="s1")
+        self.assertIn("traceparent", {k.lower(): v for k, v in out.items()})
+        self.assertIn("x-obtrace-session-id", {k.lower(): v for k, v in out.items()})
+
+
+if __name__ == "__main__":
+    unittest.main()

obtrace_sdk_python-1.0.0/tests/test_semantic_metrics.py

@@ -0,0 +1,9 @@
+from obtrace_sdk import SemanticMetrics, is_semantic_metric
+
+
+def test_semantic_metrics_expose_canonical_names() -> None:
+    assert SemanticMetrics.RUNTIME_CPU_UTILIZATION == "runtime.cpu.utilization"
+    assert SemanticMetrics.DB_OPERATION_LATENCY == "db.operation.latency"
+    assert SemanticMetrics.WEB_VITAL_INP == "web.vital.inp"
+    assert is_semantic_metric(SemanticMetrics.WEB_VITAL_INP) is True
+    assert is_semantic_metric("orders.count") is False