justanalytics-python 0.1.0__py3-none-any.whl

justanalytics/integrations/flask.py

@@ -0,0 +1,203 @@
+"""
+Flask middleware for JustAnalytics.
+
+Provides ``JustAnalyticsMiddleware`` that uses Flask's ``before_request``
+and ``after_request`` hooks to automatically:
+- Create server spans for incoming HTTP requests
+- Read ``traceparent`` headers for distributed trace propagation
+- Capture unhandled exceptions via error handler
+- Record HTTP method, path, status code, and timing
+
+Usage::
+
+    from flask import Flask
+    from justanalytics.integrations.flask import JustAnalyticsMiddleware
+
+    app = Flask(__name__)
+    JustAnalyticsMiddleware(app)
+
+The middleware expects ``justanalytics.init()`` to have been called before
+the first request is served.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger("justanalytics.integrations.flask")
+
+# Flask stores the current span in g.ja_span
+_SPAN_ATTR = "ja_span"
+_SPAN_TOKEN_ATTR = "ja_span_token"
+_TRACE_TOKEN_ATTR = "ja_trace_token"
+
+
+class JustAnalyticsMiddleware:
+    """
+    Flask middleware using before/after request hooks and error handler.
+
+    Registers hooks on the Flask app to create server spans for every
+    incoming request.
+
+    Args:
+        app: The Flask application instance. If None, call ``init_app()`` later.
+    """
+
+    def __init__(self, app: Any = None) -> None:
+        self.app = app
+        if app is not None:
+            self.init_app(app)
+
+    def init_app(self, app: Any) -> None:
+        """
+        Initialize the middleware on a Flask app.
+
+        Registers ``before_request``, ``after_request``, and ``teardown_request``
+        hooks, plus a catch-all error handler.
+
+        Args:
+            app: The Flask application instance.
+        """
+        app.before_request(self._before_request)
+        app.after_request(self._after_request)
+        app.teardown_request(self._teardown_request)
+        # Register error handler for uncaught exceptions
+        app.register_error_handler(Exception, self._handle_error)
+
+    def _before_request(self) -> None:
+        """Create a server span before each request."""
+        try:
+            from flask import request, g
+            from .. import context as ctx
+            from ..span import Span, _generate_trace_id
+            from ..trace_context import parse_traceparent
+            from ..types import SpanKind
+        except Exception:
+            return
+
+        try:
+            import justanalytics as ja
+            client = ja._client
+            if not client.is_initialized or not client._enabled:
+                return
+        except Exception:
+            return
+
+        method = request.method or "GET"
+        path = request.path or "/"
+        span_name = f"{method} {path}"
+
+        # Parse incoming traceparent header
+        traceparent_header = request.headers.get("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.url,
+            "http.target": path,
+            "http.scheme": request.scheme,
+        }
+        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,
+        )
+
+        # Enter the span context (set in contextvars)
+        span_token = ctx.set_active_span(span)
+        trace_token = ctx.set_trace_id(span.trace_id)
+
+        # Store span and tokens in Flask's g for later retrieval
+        setattr(g, _SPAN_ATTR, span)
+        setattr(g, _SPAN_TOKEN_ATTR, span_token)
+        setattr(g, _TRACE_TOKEN_ATTR, trace_token)
+
+    def _after_request(self, response: Any) -> Any:
+        """End the span and record response status after each request."""
+        try:
+            from flask import g
+            from ..types import SpanStatus
+        except Exception:
+            return response
+
+        span = getattr(g, _SPAN_ATTR, None)
+        if span is None:
+            return response
+
+        try:
+            status_code = response.status_code
+            span.set_attribute("http.status_code", status_code)
+            if status_code >= 400:
+                span.set_status(SpanStatus.ERROR, f"HTTP {status_code}")
+            else:
+                span.set_status(SpanStatus.OK)
+        except Exception:
+            pass
+
+        return response
+
+    def _teardown_request(self, exception: Optional[BaseException] = None) -> None:
+        """End the span and restore context at teardown."""
+        try:
+            from flask import g
+            from .. import context as ctx
+            from ..types import SpanStatus
+        except Exception:
+            return
+
+        span = getattr(g, _SPAN_ATTR, None)
+        if span is None:
+            return
+
+        # If there was an exception, mark the span as error
+        if exception is not None and not span.is_ended:
+            span.set_status(SpanStatus.ERROR, str(exception))
+
+        # End the span
+        if not span.is_ended:
+            span.end()
+
+        # Enqueue the span
+        try:
+            import justanalytics as ja
+            client = ja._client
+            if client._transport:
+                client._transport.enqueue_span(span.to_dict())
+        except Exception:
+            pass
+
+        # Restore context
+        span_token = getattr(g, _SPAN_TOKEN_ATTR, None)
+        trace_token = getattr(g, _TRACE_TOKEN_ATTR, None)
+        if span_token is not None:
+            ctx._active_span_var.reset(span_token)
+        if trace_token is not None:
+            ctx._trace_id_var.reset(trace_token)
+
+    def _handle_error(self, error: Exception) -> Any:
+        """Capture uncaught exceptions via the SDK."""
+        try:
+            import justanalytics as ja
+            client = ja._client
+            if client.is_initialized and client._enabled:
+                client.capture_exception(error)
+        except Exception:
+            pass
+        # Re-raise to let Flask handle the error response
+        raise error

justanalytics/integrations/logging.py

@@ -0,0 +1,175 @@
+"""
+Python ``logging.Handler`` bridge for JustAnalytics log ingestion.
+
+Provides ``JustAnalyticsHandler`` that bridges Python's standard ``logging``
+module to JustAnalytics' log ingestion API. Log records are automatically
+enriched with trace context (trace_id, span_id) from the current
+``contextvars`` scope.
+
+Usage::
+
+    import logging
+    from justanalytics.integrations.logging import JustAnalyticsHandler
+
+    # Add to root logger
+    handler = JustAnalyticsHandler()
+    logging.getLogger().addHandler(handler)
+
+    # Or add to a specific logger
+    logger = logging.getLogger("myapp")
+    logger.addHandler(JustAnalyticsHandler(level=logging.WARNING))
+
+    # Logs will now be sent to JustAnalytics with trace context
+    logger.info("User logged in", extra={"userId": "u123"})
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .. import context as ctx
+from ..types import LogLevel, LogPayload
+
+# Map Python log levels to JustAnalytics log levels
+_LEVEL_MAP: Dict[int, LogLevel] = {
+    logging.DEBUG: LogLevel.DEBUG,
+    logging.INFO: LogLevel.INFO,
+    logging.WARNING: LogLevel.WARN,
+    logging.ERROR: LogLevel.ERROR,
+    logging.CRITICAL: LogLevel.FATAL,
+}
+
+
+def _map_level(levelno: int) -> LogLevel:
+    """Map a Python logging level number to a JustAnalytics LogLevel."""
+    if levelno <= logging.DEBUG:
+        return LogLevel.DEBUG
+    elif levelno <= logging.INFO:
+        return LogLevel.INFO
+    elif levelno <= logging.WARNING:
+        return LogLevel.WARN
+    elif levelno <= logging.ERROR:
+        return LogLevel.ERROR
+    else:
+        return LogLevel.FATAL
+
+
+class JustAnalyticsHandler(logging.Handler):
+    """
+    A ``logging.Handler`` that sends log records to JustAnalytics.
+
+    Automatically attaches trace context (trace_id, span_id) from the
+    current ``contextvars`` scope. Extra fields from the log record
+    are included as attributes.
+
+    The handler is a no-op if the SDK is not initialized.
+
+    Args:
+        level: Minimum logging level (default: ``logging.NOTSET``).
+        service_name_override: Override the service name from SDK config.
+
+    Example::
+
+        handler = JustAnalyticsHandler(level=logging.INFO)
+        logging.getLogger("myapp").addHandler(handler)
+    """
+
+    def __init__(
+        self,
+        level: int = logging.NOTSET,
+        service_name_override: Optional[str] = None,
+    ) -> None:
+        super().__init__(level)
+        self._service_name_override = service_name_override
+
+    def _get_client(self):
+        """Get the JustAnalytics client. Returns None if unavailable."""
+        try:
+            import justanalytics
+            return justanalytics._client
+        except Exception:
+            return None
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """
+        Emit a log record to JustAnalytics.
+
+        Converts the log record to a ``LogPayload`` and enqueues it
+        in the SDK's transport buffer.
+
+        Args:
+            record: The logging.LogRecord to process.
+        """
+        try:
+            client = self._get_client()
+            if client is None or not client.is_initialized or not client._enabled or not client._transport:
+                return
+        except Exception:
+            return
+
+        try:
+            # Map level
+            ja_level = _map_level(record.levelno)
+
+            # Get trace context
+            active_span = ctx.get_active_span()
+            trace_id = active_span.trace_id if active_span else None
+            span_id = active_span.id if active_span else None
+
+            # Build attributes from record extras
+            attributes: Dict[str, Any] = {}
+
+            # Standard record fields worth capturing
+            if record.name:
+                attributes["logger.name"] = record.name
+            if record.funcName and record.funcName != "<module>":
+                attributes["code.function"] = record.funcName
+            if record.pathname:
+                attributes["code.filepath"] = record.pathname
+            if record.lineno:
+                attributes["code.lineno"] = record.lineno
+
+            # Extract extra fields (user-supplied via extra={} in logging call)
+            # Avoid standard LogRecord attributes
+            _STANDARD_ATTRS = frozenset({
+                "name", "msg", "args", "created", "relativeCreated",
+                "exc_info", "exc_text", "stack_info", "lineno", "funcName",
+                "pathname", "filename", "module", "levelno", "levelname",
+                "thread", "threadName", "process", "processName",
+                "getMessage", "message", "asctime", "msecs", "taskName",
+            })
+            for key, value in record.__dict__.items():
+                if key.startswith("_") or key in _STANDARD_ATTRS:
+                    continue
+                # Only include serializable values
+                if isinstance(value, (str, int, float, bool)):
+                    attributes[key] = value
+
+            # Format the message
+            message = record.getMessage()
+
+            # Include exception info if present
+            if record.exc_info and record.exc_info[0] is not None:
+                import traceback as tb
+                exc_text = "".join(tb.format_exception(*record.exc_info))
+                attributes["exception.stacktrace"] = exc_text
+
+            service_name = self._service_name_override or client._service_name
+
+            payload = LogPayload(
+                level=ja_level.value,
+                message=message[:10000],  # Server enforces max 10000 chars
+                service_name=service_name,
+                timestamp=datetime.now(timezone.utc).isoformat(),
+                trace_id=trace_id,
+                span_id=span_id,
+                attributes=attributes,
+            )
+
+            client._transport.enqueue_log(payload.to_dict())
+
+        except Exception:
+            # Never crash from the logging handler
+            self.handleError(record)

justanalytics/integrations/requests.py

@@ -0,0 +1,149 @@
+"""
+Auto-instrumentation for the ``requests`` library.
+
+Monkey-patches ``requests.Session.send()`` to automatically create client
+spans for outgoing HTTP requests, inject ``traceparent`` headers for
+distributed tracing, and capture response status codes.
+
+Usage::
+
+    from justanalytics.integrations.requests import RequestsIntegration
+
+    # Enable (call after justanalytics.init())
+    integration = RequestsIntegration()
+    integration.enable()
+
+    # All requests.get/post/etc. calls will now be traced
+
+    # Disable (restores original behavior)
+    integration.disable()
+
+The integration is safe to enable/disable multiple times. It only patches
+``Session.send()`` once, even if ``enable()`` is called multiple times.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional, TYPE_CHECKING
+
+from .. import context as ctx
+from ..span import Span
+from ..trace_context import serialize_traceparent
+from ..types import SpanKind, SpanStatus
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger("justanalytics.integrations.requests")
+
+
+class RequestsIntegration:
+    """
+    Monkey-patches ``requests.Session.send()`` to create spans for outgoing HTTP.
+
+    Args:
+        enqueue_span: Callback to enqueue ended spans for transport.
+            If None, spans are created but not sent.
+        service_name: Service name for span attribution.
+        ignore_urls: URL patterns to exclude from instrumentation.
+    """
+
+    def __init__(
+        self,
+        enqueue_span: Optional[Callable[[dict], None]] = None,
+        service_name: str = "unknown",
+        ignore_urls: Optional[list] = None,
+    ) -> None:
+        self._enqueue_span = enqueue_span
+        self._service_name = service_name
+        self._ignore_urls = ignore_urls or []
+        self._original_send: Optional[Callable] = None
+        self._enabled = False
+
+    def enable(self) -> None:
+        """Enable the integration by monkey-patching requests.Session.send."""
+        if self._enabled:
+            return
+        try:
+            import requests
+        except ImportError:
+            logger.debug("requests library not installed, skipping integration")
+            return
+
+        self._original_send = requests.Session.send
+        integration = self
+
+        def patched_send(session_self: Any, request: Any, **kwargs: Any) -> Any:
+            """Wrapped Session.send that creates spans for outgoing HTTP."""
+            url = str(request.url) if request.url else ""
+
+            # Check ignore patterns
+            for pattern in integration._ignore_urls:
+                if isinstance(pattern, str) and pattern in url:
+                    return integration._original_send(session_self, request, **kwargs)  # type: ignore[misc]
+
+            method = (request.method or "GET").upper()
+            span_name = f"{method} {_extract_host(url)}"
+
+            # Create span
+            parent = ctx.get_active_span()
+            span = Span(
+                operation_name=span_name,
+                service_name=integration._service_name,
+                kind=SpanKind.CLIENT,
+                trace_id=parent.trace_id if parent else None,
+                parent_span_id=parent.id if parent else None,
+                attributes={
+                    "http.method": method,
+                    "http.url": url,
+                },
+            )
+
+            # Inject traceparent header
+            traceparent = serialize_traceparent(span.trace_id, span.id)
+            if request.headers is None:
+                request.headers = {}
+            request.headers["traceparent"] = traceparent
+
+            with span:
+                try:
+                    response = integration._original_send(session_self, request, **kwargs)  # type: ignore[misc]
+                    span.set_attribute("http.status_code", response.status_code)
+                    if response.status_code >= 400:
+                        span.set_status(SpanStatus.ERROR, f"HTTP {response.status_code}")
+                    else:
+                        span.set_status(SpanStatus.OK)
+                    return response
+                except Exception as exc:
+                    span.set_status(SpanStatus.ERROR, str(exc))
+                    raise
+
+            # Note: span is ended by context manager __exit__, then we enqueue
+            if integration._enqueue_span and span.is_ended:
+                integration._enqueue_span(span.to_dict())
+
+        requests.Session.send = patched_send  # type: ignore[assignment]
+        self._enabled = True
+
+    def disable(self) -> None:
+        """Disable the integration by restoring the original Session.send."""
+        if not self._enabled or self._original_send is None:
+            return
+        try:
+            import requests
+            requests.Session.send = self._original_send  # type: ignore[assignment]
+        except ImportError:
+            pass
+        self._original_send = None
+        self._enabled = False
+
+
+def _extract_host(url: str) -> str:
+    """Extract the host portion from a URL for the span name."""
+    try:
+        from urllib.parse import urlparse
+        parsed = urlparse(url)
+        return parsed.netloc or url
+    except Exception:
+        return url

justanalytics/integrations/urllib3.py

@@ -0,0 +1,146 @@
+"""
+Auto-instrumentation for ``urllib3``.
+
+Patches ``urllib3.HTTPConnectionPool.urlopen()`` to automatically create
+client spans for outgoing HTTP requests at the connection pool level.
+This captures HTTP traffic from libraries that use urllib3 under the hood
+(including ``requests``).
+
+Usage::
+
+    from justanalytics.integrations.urllib3 import Urllib3Integration
+
+    integration = Urllib3Integration(enqueue_span=transport.enqueue_span)
+    integration.enable()
+
+    # All urllib3 requests will now be traced
+
+    integration.disable()
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Optional
+
+from .. import context as ctx
+from ..span import Span
+from ..trace_context import serialize_traceparent
+from ..types import SpanKind, SpanStatus
+
+logger = logging.getLogger("justanalytics.integrations.urllib3")
+
+
+class Urllib3Integration:
+    """
+    Patches ``urllib3.HTTPConnectionPool.urlopen()`` for outgoing HTTP spans.
+
+    Args:
+        enqueue_span: Callback to enqueue ended spans for transport.
+        service_name: Service name for span attribution.
+        ignore_urls: URL patterns to exclude from instrumentation.
+    """
+
+    def __init__(
+        self,
+        enqueue_span: Optional[Callable[[dict], None]] = None,
+        service_name: str = "unknown",
+        ignore_urls: Optional[list] = None,
+    ) -> None:
+        self._enqueue_span = enqueue_span
+        self._service_name = service_name
+        self._ignore_urls = ignore_urls or []
+        self._original_urlopen: Optional[Callable] = None
+        self._enabled = False
+
+    def enable(self) -> None:
+        """Enable the integration by monkey-patching urllib3."""
+        if self._enabled:
+            return
+        try:
+            import urllib3
+        except ImportError:
+            logger.debug("urllib3 library not installed, skipping integration")
+            return
+
+        self._original_urlopen = urllib3.HTTPConnectionPool.urlopen
+        integration = self
+
+        def patched_urlopen(
+            pool_self: Any, method: str, url: str, body: Any = None, headers: Any = None, **kwargs: Any
+        ) -> Any:
+            """Wrapped urlopen that creates spans for outgoing HTTP."""
+            # Reconstruct full URL for ignore checks
+            scheme = "https" if hasattr(pool_self, "scheme") and pool_self.scheme == "https" else "http"
+            host = getattr(pool_self, "host", "unknown")
+            port = getattr(pool_self, "port", None)
+            if port and port not in (80, 443):
+                full_url = f"{scheme}://{host}:{port}{url}"
+            else:
+                full_url = f"{scheme}://{host}{url}"
+
+            # Check ignore patterns
+            for pattern in integration._ignore_urls:
+                if isinstance(pattern, str) and pattern in full_url:
+                    return integration._original_urlopen(  # type: ignore[misc]
+                        pool_self, method, url, body=body, headers=headers, **kwargs
+                    )
+
+            method_upper = method.upper()
+            span_name = f"{method_upper} {host}"
+
+            parent = ctx.get_active_span()
+            span = Span(
+                operation_name=span_name,
+                service_name=integration._service_name,
+                kind=SpanKind.CLIENT,
+                trace_id=parent.trace_id if parent else None,
+                parent_span_id=parent.id if parent else None,
+                attributes={
+                    "http.method": method_upper,
+                    "http.url": full_url,
+                    "net.peer.name": host,
+                },
+            )
+
+            # Inject traceparent header
+            if headers is None:
+                headers = {}
+            else:
+                headers = dict(headers)
+            headers["traceparent"] = serialize_traceparent(span.trace_id, span.id)
+
+            with span:
+                try:
+                    response = integration._original_urlopen(  # type: ignore[misc]
+                        pool_self, method, url, body=body, headers=headers, **kwargs
+                    )
+                    status_code = getattr(response, "status", None)
+                    if status_code is not None:
+                        span.set_attribute("http.status_code", status_code)
+                        if 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))
+                    raise
+
+            if integration._enqueue_span and span.is_ended:
+                integration._enqueue_span(span.to_dict())
+
+        urllib3.HTTPConnectionPool.urlopen = patched_urlopen  # type: ignore[assignment]
+        self._enabled = True
+
+    def disable(self) -> None:
+        """Disable the integration by restoring the original urlopen."""
+        if not self._enabled or self._original_urlopen is None:
+            return
+        try:
+            import urllib3
+            urllib3.HTTPConnectionPool.urlopen = self._original_urlopen  # type: ignore[assignment]
+        except ImportError:
+            pass
+        self._original_urlopen = None
+        self._enabled = False