justanalytics-python 0.1.0__py3-none-any.whl

justanalytics/context.py

@@ -0,0 +1,143 @@
+"""
+Context propagation using ``contextvars.ContextVar``.
+
+Provides trace context propagation across async/await boundaries using
+Python's built-in ``contextvars`` module (available since Python 3.7).
+This is the Python equivalent of Node.js ``AsyncLocalStorage``.
+
+Context is propagated automatically through:
+- asyncio tasks (await, create_task)
+- threading (when using contextvars.copy_context())
+- generator-based coroutines
+
+Each ``start_span()`` call sets a new active span in the context.
+Nested spans automatically form parent-child relationships.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from typing import Any, Dict, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .span import Span
+    from .types import UserContext
+
+# --- Context Variables ---
+
+_active_span_var: contextvars.ContextVar[Optional[Span]] = contextvars.ContextVar(
+    "ja_active_span", default=None
+)
+
+_trace_id_var: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar(
+    "ja_trace_id", default=None
+)
+
+_user_var: contextvars.ContextVar[Optional[UserContext]] = contextvars.ContextVar(
+    "ja_user", default=None
+)
+
+_tags_var: contextvars.ContextVar[Dict[str, str]] = contextvars.ContextVar(
+    "ja_tags", default={}
+)
+
+
+def get_active_span() -> Optional[Span]:
+    """Get the currently active span from context.
+
+    Returns:
+        The active Span, or None if not in a traced context.
+    """
+    return _active_span_var.get(None)
+
+
+def set_active_span(span: Optional[Span]) -> contextvars.Token:
+    """Set the active span in context.
+
+    Args:
+        span: The span to make active, or None to clear.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    return _active_span_var.set(span)
+
+
+def get_trace_id() -> Optional[str]:
+    """Get the current trace ID from context.
+
+    Returns:
+        The trace ID string, or None if not in a traced context.
+    """
+    return _trace_id_var.get(None)
+
+
+def set_trace_id(trace_id: Optional[str]) -> contextvars.Token:
+    """Set the trace ID in context.
+
+    Args:
+        trace_id: The trace ID to set, or None to clear.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    return _trace_id_var.set(trace_id)
+
+
+def get_user() -> Optional[UserContext]:
+    """Get the current user context.
+
+    Returns:
+        The UserContext, or None if not set.
+    """
+    return _user_var.get(None)
+
+
+def set_user(user: Optional[UserContext]) -> contextvars.Token:
+    """Set the user context.
+
+    Args:
+        user: The user context to set, or None to clear.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    return _user_var.set(user)
+
+
+def get_tags() -> Dict[str, str]:
+    """Get the current context tags.
+
+    Returns:
+        A copy of the current tags dict.
+    """
+    return dict(_tags_var.get({}))
+
+
+def set_tag(key: str, value: str) -> contextvars.Token:
+    """Set a single tag in the context (copy-on-write).
+
+    Tags are attached as attributes on all spans created within this scope.
+
+    Args:
+        key: Tag key.
+        value: Tag value.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    current = _tags_var.get({})
+    new_tags = {**current, key: value}
+    return _tags_var.set(new_tags)
+
+
+def set_tags(tags: Dict[str, str]) -> contextvars.Token:
+    """Replace all tags in the context.
+
+    Args:
+        tags: The new tags dict.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    return _tags_var.set(dict(tags))

justanalytics/integrations/__init__.py

@@ -0,0 +1,11 @@
+"""
+Auto-instrumentation integrations for the JustAnalytics Python SDK.
+
+Available integrations:
+- ``requests``: Monkey-patches ``requests.Session.send()`` for outgoing HTTP spans.
+- ``urllib3``: Patches ``urllib3.HTTPConnectionPool.urlopen()`` for lower-level HTTP tracking.
+- ``django``: ``JustAnalyticsMiddleware`` for incoming request spans, user extraction, error capture.
+- ``flask``: ``JustAnalyticsMiddleware`` for before/after request hooks, error handler.
+- ``fastapi``: ASGI middleware + exception handler for FastAPI/Starlette.
+- ``logging``: ``JustAnalyticsHandler(logging.Handler)`` bridging Python logging to JA log ingestion.
+"""

justanalytics/integrations/django.py

@@ -0,0 +1,157 @@
+"""
+Django middleware for JustAnalytics.
+
+Provides ``JustAnalyticsMiddleware`` that automatically:
+- Creates server spans for incoming HTTP requests
+- Reads ``traceparent`` headers for distributed trace propagation
+- Extracts Django user information
+- Captures unhandled exceptions
+- Records HTTP method, path, status code, and timing
+
+Usage (settings.py)::
+
+    MIDDLEWARE = [
+        "justanalytics.integrations.django.JustAnalyticsMiddleware",
+        # ... other middleware
+    ]
+
+The middleware expects ``justanalytics.init()`` to have been called before
+the first request is served. If the SDK is not initialized, the middleware
+is a no-op passthrough.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Callable, Optional
+
+logger = logging.getLogger("justanalytics.integrations.django")
+
+
+class JustAnalyticsMiddleware:
+    """
+    Django middleware that creates server spans for incoming HTTP requests.
+
+    This middleware:
+    1. Reads the ``traceparent`` header to continue an existing trace
+    2. Creates a ``server`` span for the request
+    3. Extracts the authenticated Django user (if available)
+    4. Captures exceptions and sets span status to ``error``
+    5. Records ``http.method``, ``http.url``, ``http.status_code``
+
+    Args:
+        get_response: The next middleware or view in the Django chain.
+    """
+
+    def __init__(self, get_response: Callable[..., Any]) -> None:
+        self.get_response = get_response
+
+    def __call__(self, request: Any) -> Any:
+        """Process the request, wrapping it in a JA span."""
+        # Import here to avoid circular imports and allow lazy SDK init
+        try:
+            from .. import context as ctx
+            from ..client import JustAnalyticsClient
+            from ..span import Span, _generate_trace_id
+            from ..trace_context import parse_traceparent, serialize_traceparent
+            from ..types import SpanKind, SpanStatus, UserContext
+        except Exception:
+            return self.get_response(request)
+
+        # Access the global client through the module
+        try:
+            import justanalytics as ja
+            client = ja._client
+            if not client.is_initialized or not client._enabled:
+                return self.get_response(request)
+        except Exception:
+            return self.get_response(request)
+
+        method = request.method or "GET"
+        path = request.path or "/"
+        span_name = f"{method} {path}"
+
+        # Parse incoming traceparent header
+        traceparent_header = request.META.get("HTTP_TRACEPARENT", "")
+        parsed = parse_traceparent(traceparent_header) if traceparent_header else None
+
+        if parsed:
+            trace_id = parsed.trace_id
+            parent_span_id = parsed.parent_span_id
+        else:
+            trace_id = _generate_trace_id()
+            parent_span_id = None
+
+        attributes = {
+            "http.method": method,
+            "http.url": request.build_absolute_uri() if hasattr(request, "build_absolute_uri") else path,
+            "http.target": path,
+            "http.scheme": request.scheme if hasattr(request, "scheme") else "http",
+        }
+
+        if client._environment:
+            attributes["environment"] = client._environment
+        if client._release:
+            attributes["release"] = client._release
+
+        span = Span(
+            operation_name=span_name,
+            service_name=client._service_name,
+            kind=SpanKind.SERVER,
+            trace_id=trace_id,
+            parent_span_id=parent_span_id,
+            attributes=attributes,
+        )
+
+        with span:
+            # Extract Django user if authenticated
+            try:
+                if hasattr(request, "user") and request.user.is_authenticated:
+                    user_id = str(getattr(request.user, "pk", "")) or str(getattr(request.user, "id", ""))
+                    email = getattr(request.user, "email", None)
+                    username = getattr(request.user, "username", None)
+                    ctx.set_user(UserContext(id=user_id, email=email, username=username))
+                    span.set_attribute("user.id", user_id)
+                    if email:
+                        span.set_attribute("user.email", email)
+            except Exception:
+                pass  # User extraction is best-effort
+
+            try:
+                response = self.get_response(request)
+                status_code = getattr(response, "status_code", 200)
+                span.set_attribute("http.status_code", status_code)
+                if status_code >= 500:
+                    span.set_status(SpanStatus.ERROR, f"HTTP {status_code}")
+                elif status_code >= 400:
+                    span.set_status(SpanStatus.ERROR, f"HTTP {status_code}")
+                else:
+                    span.set_status(SpanStatus.OK)
+                return response
+            except Exception as exc:
+                span.set_status(SpanStatus.ERROR, str(exc))
+                # Capture exception via SDK
+                try:
+                    client.capture_exception(exc)
+                except Exception:
+                    pass
+                raise
+
+        # Enqueue the ended span
+        if client._transport and span.is_ended:
+            client._transport.enqueue_span(span.to_dict())
+
+    def process_exception(self, request: Any, exception: BaseException) -> None:
+        """
+        Called by Django when a view raises an exception.
+
+        Captures the exception via the SDK for error tracking.
+        """
+        try:
+            import justanalytics as ja
+            client = ja._client
+            if client.is_initialized and client._enabled:
+                client.capture_exception(exception)
+        except Exception:
+            pass  # Never crash from error capture

justanalytics/integrations/fastapi.py

@@ -0,0 +1,197 @@
+"""
+FastAPI / Starlette ASGI middleware for JustAnalytics.
+
+Provides ``JustAnalyticsMiddleware`` as ASGI middleware that automatically:
+- Creates server spans for incoming HTTP requests
+- Reads ``traceparent`` headers for distributed trace propagation
+- Captures unhandled exceptions
+- Records HTTP method, path, status code, and timing
+
+Usage::
+
+    from fastapi import FastAPI
+    from justanalytics.integrations.fastapi import JustAnalyticsMiddleware
+
+    app = FastAPI()
+    app.add_middleware(JustAnalyticsMiddleware)
+
+Works with any ASGI framework (FastAPI, Starlette, etc.).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Awaitable, Callable, Optional
+
+logger = logging.getLogger("justanalytics.integrations.fastapi")
+
+# Type aliases for ASGI
+Scope = dict
+Receive = Callable[[], Awaitable[dict]]
+Send = Callable[[dict], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+
+class JustAnalyticsMiddleware:
+    """
+    ASGI middleware that creates server spans for incoming HTTP requests.
+
+    Compatible with FastAPI, Starlette, and any ASGI-compliant framework.
+
+    Args:
+        app: The ASGI application to wrap.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Process an ASGI request."""
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        try:
+            from .. import context as ctx
+            from ..span import Span, _generate_trace_id
+            from ..trace_context import parse_traceparent
+            from ..types import SpanKind, SpanStatus
+        except Exception:
+            await self.app(scope, receive, send)
+            return
+
+        try:
+            import justanalytics as ja
+            client = ja._client
+            if not client.is_initialized or not client._enabled:
+                await self.app(scope, receive, send)
+                return
+        except Exception:
+            await self.app(scope, receive, send)
+            return
+
+        # Extract request info from ASGI scope
+        method = scope.get("method", "GET")
+        path = scope.get("path", "/")
+        scheme = scope.get("scheme", "http")
+        headers = dict(scope.get("headers", []))
+
+        span_name = f"{method} {path}"
+
+        # Parse incoming traceparent header
+        traceparent_header = ""
+        for key, value in headers.items():
+            if key == b"traceparent":
+                traceparent_header = value.decode("utf-8", errors="replace")
+                break
+
+        parsed = parse_traceparent(traceparent_header) if traceparent_header else None
+
+        if parsed:
+            trace_id = parsed.trace_id
+            parent_span_id = parsed.parent_span_id
+        else:
+            trace_id = _generate_trace_id()
+            parent_span_id = None
+
+        # Build server/host from scope
+        server = scope.get("server")
+        if server:
+            host = f"{server[0]}:{server[1]}"
+        else:
+            host = "unknown"
+
+        attributes = {
+            "http.method": method,
+            "http.url": f"{scheme}://{host}{path}",
+            "http.target": path,
+            "http.scheme": scheme,
+        }
+        if client._environment:
+            attributes["environment"] = client._environment
+        if client._release:
+            attributes["release"] = client._release
+
+        # Query string
+        query_string = scope.get("query_string", b"")
+        if query_string:
+            attributes["http.query_string"] = query_string.decode("utf-8", errors="replace")
+
+        span = Span(
+            operation_name=span_name,
+            service_name=client._service_name,
+            kind=SpanKind.SERVER,
+            trace_id=trace_id,
+            parent_span_id=parent_span_id,
+            attributes=attributes,
+        )
+
+        # Track response status code
+        response_status: Optional[int] = None
+
+        async def send_wrapper(message: dict) -> None:
+            nonlocal response_status
+            if message["type"] == "http.response.start":
+                response_status = message.get("status", 200)
+            await send(message)
+
+        with span:
+            try:
+                await self.app(scope, receive, send_wrapper)
+                if response_status is not None:
+                    span.set_attribute("http.status_code", response_status)
+                    if response_status >= 400:
+                        span.set_status(SpanStatus.ERROR, f"HTTP {response_status}")
+                    else:
+                        span.set_status(SpanStatus.OK)
+                else:
+                    span.set_status(SpanStatus.OK)
+            except Exception as exc:
+                span.set_status(SpanStatus.ERROR, str(exc))
+                # Capture exception
+                try:
+                    client.capture_exception(exc)
+                except Exception:
+                    pass
+                raise
+
+        # Enqueue the ended span
+        if client._transport and span.is_ended:
+            client._transport.enqueue_span(span.to_dict())
+
+
+def setup_exception_handler(app: Any) -> None:
+    """
+    Register a FastAPI exception handler that captures exceptions via JA.
+
+    Args:
+        app: The FastAPI application instance.
+
+    Usage::
+
+        from fastapi import FastAPI
+        from justanalytics.integrations.fastapi import setup_exception_handler
+
+        app = FastAPI()
+        setup_exception_handler(app)
+    """
+    try:
+        from fastapi import Request
+        from fastapi.responses import JSONResponse
+    except ImportError:
+        logger.debug("FastAPI not installed, skipping exception handler setup")
+        return
+
+    @app.exception_handler(Exception)
+    async def ja_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+        try:
+            import justanalytics as ja
+            client = ja._client
+            if client.is_initialized and client._enabled:
+                client.capture_exception(exc)
+        except Exception:
+            pass
+        return JSONResponse(
+            status_code=500,
+            content={"detail": "Internal Server Error"},
+        )