tracely-sdk 0.1.0__py3-none-any.whl

tracely/tracing.py

@@ -0,0 +1,59 @@
+"""Public tracing API for custom spans (FR58, FR59).
+
+Provides the `span()` context manager for developers to create
+custom spans within their application code.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Callable, Generator
+
+from tracely.context import get_current_span, _span_context
+from tracely.span import Span
+from tracely.span_processor import on_span_end, on_span_start
+
+
+@contextmanager
+def span(
+    name: str,
+    *,
+    kind: str = "INTERNAL",
+    service_name: str | None = None,
+    on_end: Callable[[Span], None] | None = None,
+) -> Generator[Span, None, None]:
+    """Create a custom span as a child of the currently active span.
+
+    If no span is active, creates a root span. The span is automatically
+    ended when the context exits (including on exception).
+
+    Usage::
+
+        with tracely.span("my-operation") as s:
+            s.set_attribute("key", "value")
+            # do work
+        # span is ended here
+
+    Args:
+        name: Human-readable operation name.
+        kind: Span kind (INTERNAL, CLIENT, PRODUCER, CONSUMER).
+        service_name: Optional service name override.
+        on_end: Optional callback invoked when span ends.
+    """
+    parent = get_current_span()
+    s = Span(
+        name=name,
+        parent=parent,
+        kind=kind,
+        service_name=service_name,
+        on_end=on_end or on_span_end,
+    )
+
+    # AR3: Export pending_span immediately for real-time dashboard
+    on_span_start(s)
+
+    with _span_context(s):
+        try:
+            yield s
+        finally:
+            s.end()

tracely/transport.py

@@ -0,0 +1,134 @@
+"""HTTP transport with buffering and retry for span data."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections import deque
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("tracely")
+
+DEFAULT_BATCH_SIZE = 50
+DEFAULT_MAX_BUFFER = 1000
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BASE_DELAY = 1.0
+DEFAULT_MAX_DELAY = 30.0
+
+
+class SpanBuffer:
+    """Thread-safe in-memory buffer for span data.
+
+    Drops oldest spans when max_size is exceeded.
+    """
+
+    def __init__(
+        self,
+        max_size: int = DEFAULT_MAX_BUFFER,
+        batch_size: int = DEFAULT_BATCH_SIZE,
+    ) -> None:
+        self._buffer: deque[dict[str, Any]] = deque(maxlen=max_size)
+        self._batch_size = batch_size
+
+    def enqueue(self, span: dict[str, Any]) -> None:
+        """Add a span to the buffer. Oldest dropped if full."""
+        self._buffer.append(span)
+
+    def flush(self) -> list[dict[str, Any]]:
+        """Return all buffered spans and clear the buffer."""
+        spans = list(self._buffer)
+        self._buffer.clear()
+        return spans
+
+    @property
+    def size(self) -> int:
+        """Number of spans currently in buffer."""
+        return len(self._buffer)
+
+    @property
+    def is_ready(self) -> bool:
+        """Buffer has reached the batch threshold."""
+        return len(self._buffer) >= self._batch_size
+
+
+class HttpTransport:
+    """Sends span data to the TRACELY API with retry and backoff.
+
+    All errors are caught silently — the host application must never be
+    affected by transport failures (FR10, NFR22).
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        base_delay: float = DEFAULT_BASE_DELAY,
+        max_delay: float = DEFAULT_MAX_DELAY,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._api_key = api_key
+        self._max_retries = max_retries
+        self._base_delay = base_delay
+        self._max_delay = max_delay
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(10.0),
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/x-protobuf",
+            },
+        )
+
+    async def send(self, payload: bytes) -> bool:
+        """Send OTLP protobuf payload to the API. Returns True on success.
+
+        Args:
+            payload: Serialized OTLP ExportTraceServiceRequest bytes.
+
+        Never raises — all exceptions are caught and logged (FR10, NFR22).
+        """
+        if not payload:
+            return True
+
+        url = f"{self._endpoint}/v1/traces"
+        attempt = 0
+        max_attempts = 1 + self._max_retries
+
+        while attempt < max_attempts:
+            try:
+                response = await self._client.post(url, content=payload)
+                response.raise_for_status()
+                return True
+            except (httpx.HTTPStatusError, httpx.ConnectError, httpx.TimeoutException, ConnectionError, OSError) as exc:
+                attempt += 1
+                if attempt < max_attempts:
+                    delay = min(
+                        self._base_delay * (2 ** (attempt - 1)),
+                        self._max_delay,
+                    )
+                    logger.debug(
+                        "TRACELY transport retry %d/%d after %.1fs: %s",
+                        attempt,
+                        self._max_retries,
+                        delay,
+                        exc,
+                    )
+                    await asyncio.sleep(delay)
+                else:
+                    logger.debug(
+                        "TRACELY transport failed after %d attempts: %s",
+                        max_attempts,
+                        exc,
+                    )
+            except Exception as exc:
+                # Catch-all: SDK must never crash the host app
+                logger.debug("TRACELY transport unexpected error: %s", exc)
+                return False
+
+        return False
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._client.aclose()

tracely_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: tracely-sdk
+Version: 0.1.0
+Summary: Lightweight observability SDK for Python web frameworks. Auto-instruments FastAPI, Flask, and Django with real-time tracing via OTLP/HTTP.
+Project-URL: Homepage, https://tracely.sh
+Project-URL: Documentation, https://docs.tracely.sh
+Project-URL: Repository, https://github.com/TracelyOrg/tracely-sdk
+Project-URL: Issues, https://github.com/TracelyOrg/tracely-sdk/issues
+Author-email: Charles Dzadu <contact@tracely.sh>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: apm,django,fastapi,flask,monitoring,observability,opentelemetry,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: opentelemetry-proto>=1.20
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tracely-sdk
+
+Lightweight observability SDK for Python web frameworks. Auto-instruments **FastAPI**, **Flask**, and **Django** with real-time distributed tracing via OTLP/HTTP.
+
+[![PyPI version](https://img.shields.io/pypi/v/tracely-sdk.svg)](https://pypi.org/project/tracely-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/tracely-sdk.svg)](https://pypi.org/project/tracely-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Zero-config auto-instrumentation** -- detects FastAPI, Flask, and Django automatically
+- **Real-time pending spans** -- see requests the moment they start, not just when they finish
+- **Full request/response capture** -- headers, body, query params with smart redaction
+- **OTLP/HTTP protobuf export** -- standard OpenTelemetry wire format
+- **Batch export with backoff** -- 1s flush interval, exponential retry on failure
+- **Fail-silent design** -- SDK never crashes or degrades your application
+- **Minimal dependencies** -- only `httpx` and `opentelemetry-proto`
+
+## Installation
+
+```bash
+pip install tracely-sdk
+```
+
+## Quick Start
+
+### FastAPI
+
+```python
+import tracely
+from tracely.instrumentation.fastapi_inst import TracelyASGIMiddleware
+
+tracely.init(api_key="trly_your_key_here")
+
+from fastapi import FastAPI
+app = FastAPI()
+app.add_middleware(TracelyASGIMiddleware)
+
+@app.get("/")
+async def root():
+    return {"status": "ok"}
+```
+
+### Flask
+
+```python
+import tracely
+from tracely.instrumentation.flask_inst import FlaskInstrumentor
+
+tracely.init(api_key="trly_your_key_here")
+
+from flask import Flask
+app = Flask(__name__)
+app.wsgi_app = FlaskInstrumentor.wrap_app(app.wsgi_app)
+
+@app.route("/")
+def root():
+    return {"status": "ok"}
+```
+
+### Django
+
+Add the middleware to your `MIDDLEWARE` setting:
+
+```python
+# settings.py
+MIDDLEWARE = [
+    "tracely.instrumentation.django_inst.TracelyDjangoMiddleware",
+    # ... other middleware
+]
+```
+
+Then initialize in your app startup (e.g., `AppConfig.ready()`):
+
+```python
+import tracely
+tracely.init(api_key="trly_your_key_here")
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TRACELY_API_KEY` | API key for authentication | _(required)_ |
+| `TRACELY_ENDPOINT` | Ingestion API endpoint | `https://i.tracely.sh` |
+| `ENVIRONMENT` | Deployment environment (e.g., `production`) | `None` |
+| `TRACELY_REDACT_FIELDS` | Comma-separated header/field names to redact | `None` |
+
+### Programmatic Init
+
+```python
+import tracely
+
+tracely.init(
+    api_key="trly_your_key_here",
+    environment="production",
+    service_name="my-api",
+    service_version="1.0.0",
+)
+```
+
+## Custom Spans
+
+Create manual spans for custom operations:
+
+```python
+import tracely
+
+with tracely.span("db-query", kind="CLIENT") as s:
+    s.set_attribute("db.system", "postgres")
+    s.set_attribute("db.statement", "SELECT * FROM users")
+    result = db.execute("SELECT * FROM users")
+```
+
+## Span Events (Structured Logging)
+
+Attach structured log events to the active span:
+
+```python
+import tracely
+
+with tracely.span("process-order") as s:
+    tracely.info("Order received", order_id="123")
+    # ... process
+    tracely.debug("Validation passed")
+    tracely.warning("Inventory low", sku="WIDGET-42")
+```
+
+## Graceful Shutdown
+
+Flush buffered spans before exit:
+
+```python
+import tracely
+
+tracely.init(api_key="trly_your_key_here")
+# ... application runs ...
+tracely.shutdown()  # flushes remaining spans
+```
+
+## How It Works
+
+```
+Your App
+  |
+  v
+Middleware (FastAPI/Flask/Django)
+  |-- on_start --> SpanProcessor --> SpanBuffer (pending_span)
+  |-- on_end ----> SpanProcessor --> SpanBuffer (final span)
+                                        |
+                                        v
+                                  BatchSpanExporter (1s interval / 50 span threshold)
+                                        |
+                                        v
+                                  OTLP Protobuf Serialization
+                                        |
+                                        v
+                                  HttpTransport --> TRACELY API
+                                  (retry with exponential backoff)
+```
+
+## Documentation
+
+Full docs at [docs.tracely.sh](https://docs.tracely.sh)
+
+## License
+
+MIT

tracely_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+tracely/__init__.py,sha256=7CmCMoZ7kaz2nE7o-iRfZ4z6P2_LrVX9LlCGez4-sac,357
+tracely/capture.py,sha256=_W0V1pdx9dUIQWwafOggm2hDisyfpY_fJsgz1H7Poyo,6636
+tracely/config.py,sha256=F_ytza_-HEpn6rGxb8kBAbuoLrQu88BIey7SpZP9vJ0,1244
+tracely/context.py,sha256=PjxtEph9ooC0T6jOLnX6a16nnThHlWg52183O-wV2bE,1613
+tracely/detection.py,sha256=BI2z2b2ncfEPMA4_JmDulpxMGctQBy-rZSf2xT3JFvs,1460
+tracely/exporter.py,sha256=ce3jfMzBHaa38YgG-I7CP6Q7dwljP4VanWXVPZP4LpM,4018
+tracely/log_handler.py,sha256=BYxUnRTim1D8L79QOlALD9W_feLjSul8oMKrZiTGnys,1776
+tracely/logging_api.py,sha256=KKGRu_mb2XZk7tgzUYWRl6bh0_G42KAar-X2yH_Wm9I,1264
+tracely/otlp.py,sha256=pfeQVN641ZusnovMYz6A4_XkFqcblwO5hT4Cda8LLhQ,4265
+tracely/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tracely/redaction.py,sha256=ywsjD7o20RWu_qS6PYt3WnbxrJslHGA3IeAGS96jpTw,5949
+tracely/sdk.py,sha256=-zvNUFw1Nx4KxR2i90FlW4ELSh0R0Cb2VFuG_o1zWbU,6072
+tracely/span.py,sha256=bWo8LM_vR0Uc1g6o-6-wdYOnwPJ3UQENtcWdGumSwaI,5079
+tracely/span_processor.py,sha256=P4f4192t-FBppw9LmPebHA1ciA5UKp4eseTY-3LAPWA,3370
+tracely/tracing.py,sha256=NiwcrZ9S8-fqVWfYgc6PTlzc141v-Om311TOytowph4,1608
+tracely/transport.py,sha256=mvrA9JqVmHydAs-Z_iPypBNywX8UgZYjooAU-HS11sQ,4131
+tracely/instrumentation/__init__.py,sha256=QPCafxwszvO8nwLrsMkwcsD0j3hg_OG3T5GAd4DYr_E,1476
+tracely/instrumentation/base.py,sha256=g5siRo1L6K88rrb47OS9tmg5riNtljEMlRUy1BENqdQ,860
+tracely/instrumentation/dbapi.py,sha256=ax_wG5PUOASARKay3CCTQBGFeY9rCUBsdNp_Rel9tsc,8882
+tracely/instrumentation/django_inst.py,sha256=wYO5c-TYW9ScyWLnCQw8UHiyKgx-OE0Ie9lNqrwP_X4,5560
+tracely/instrumentation/fastapi_inst.py,sha256=1h4Kd6DTig4CcNFoVKclh0TjAHCFqcAJDzDpUiQMSSQ,7388
+tracely/instrumentation/flask_inst.py,sha256=fCfC-hYKQy1pSNwy3e6VZQ0KF93F82CqnNAFnf-J_Bo,7646
+tracely/instrumentation/generic.py,sha256=hjHlnVrJQXsXtVR3P0mVehf9OqAZ6UZFIR-GI0D0qeQ,1021
+tracely/instrumentation/httpx_inst.py,sha256=hQ25EE37G7EoyLpR9g9r5Z5qVUgw5e4D5fTPKsSiZuE,4825
+tracely_sdk-0.1.0.dist-info/METADATA,sha256=ks5_rxp34HGmqbEMC3tCGo5Y1kl5ryt9amimzY-d2tM,5889
+tracely_sdk-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tracely_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=btzJ8TFbmXLjXC326W6a5ta0IBUtxUAo1X-mCFW_EhQ,1075
+tracely_sdk-0.1.0.dist-info/RECORD,,

tracely_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

tracely_sdk-0.1.0.dist-info/licenses/LICENSE

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