tracely-sdk 0.1.0__py3-none-any.whl

tracely/instrumentation/flask_inst.py

@@ -0,0 +1,215 @@
+"""Flask auto-instrumentation (WSGI middleware).
+
+Provides a WSGI middleware that wraps Flask (or any WSGI) applications
+to create structured Span objects for each HTTP request, with full trace
+hierarchy support via context propagation. Captures full request/response
+data (FR6/FR7).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Iterable
+
+from tracely.capture import build_url, capture_request_data, capture_response_data
+from tracely.context import _span_context
+from tracely.instrumentation.base import BaseInstrumentor
+from tracely.span import Span
+from tracely.span_processor import on_span_end, on_span_start
+
+logger = logging.getLogger("tracely")
+
+
+def _extract_wsgi_headers(environ: dict[str, Any]) -> dict[str, str]:
+    """Extract HTTP headers from WSGI environ dict.
+
+    WSGI stores headers as HTTP_<NAME> with underscores replacing hyphens.
+    CONTENT_TYPE and CONTENT_LENGTH are special cases without HTTP_ prefix.
+    """
+    headers: dict[str, str] = {}
+    for key, value in environ.items():
+        if key.startswith("HTTP_"):
+            header_name = key[5:].lower().replace("_", "-")
+            headers[header_name] = str(value)
+        elif key == "CONTENT_TYPE":
+            headers["content-type"] = str(value)
+        elif key == "CONTENT_LENGTH":
+            headers["content-length"] = str(value)
+    return headers
+
+
+def _read_wsgi_body(environ: dict[str, Any]) -> bytes:
+    """Read request body from WSGI environ's wsgi.input stream."""
+    try:
+        content_length = int(environ.get("CONTENT_LENGTH", 0) or 0)
+    except (ValueError, TypeError):
+        content_length = 0
+
+    if content_length <= 0:
+        return b""
+
+    wsgi_input = environ.get("wsgi.input")
+    if wsgi_input is None:
+        return b""
+
+    try:
+        return wsgi_input.read(content_length)
+    except Exception:
+        logger.debug("Error reading WSGI body", exc_info=True)
+        return b""
+
+
+class TracelyWSGIMiddleware:
+    """WSGI middleware that creates root spans for HTTP requests.
+
+    Creates a Span object with trace_id and span_id, sets it as the
+    active span via context propagation, and captures HTTP attributes
+    including full request/response data (headers, body, URL).
+    """
+
+    def __init__(
+        self,
+        app: Callable[..., Iterable[bytes]],
+        on_span: Callable[[dict[str, Any]], None] | None = None,
+        service_name: str | None = None,
+        on_end: Callable[[Span], None] | None = None,
+    ) -> None:
+        self.app = app
+        self._on_span = on_span
+        self._service_name = service_name
+        self._on_end = on_end
+
+    def __call__(
+        self,
+        environ: dict[str, Any],
+        start_response: Callable[..., Any],
+    ) -> Iterable[bytes]:
+        method = environ.get("REQUEST_METHOD", "UNKNOWN")
+        path = environ.get("PATH_INFO", "/")
+        query = environ.get("QUERY_STRING", "")
+
+        # Build full URL
+        scheme = environ.get("wsgi.url_scheme", "http")
+        host = environ.get("HTTP_HOST", "")
+        if not host:
+            server_name = environ.get("SERVER_NAME", "localhost")
+            server_port = environ.get("SERVER_PORT", "80")
+            if (scheme == "https" and server_port != "443") or (scheme == "http" and server_port != "80"):
+                host = f"{server_name}:{server_port}"
+            else:
+                host = server_name
+        full_url = build_url(scheme, host, path, query)
+
+        # Read request headers and body
+        req_headers = _extract_wsgi_headers(environ)
+        req_content_type = req_headers.get("content-type", "")
+        req_body = _read_wsgi_body(environ)
+
+        span = Span(
+            name=f"{method} {path}",
+            kind="SERVER",
+            service_name=self._service_name,
+            on_end=self._on_end or on_span_end,
+        )
+        span.set_attribute("http.route", path)
+        span.set_attribute("http.query", query)
+
+        # AR3: Export pending_span immediately for real-time dashboard
+        on_span_start(span)
+
+        status_code = 0
+        resp_headers_dict: dict[str, str] = {}
+        resp_content_type = ""
+
+        def wrapped_start_response(
+            status: str, headers: list[Any], exc_info: Any = None
+        ) -> Any:
+            nonlocal status_code, resp_headers_dict, resp_content_type
+            try:
+                status_code = int(status.split(" ", 1)[0])
+            except (ValueError, IndexError):
+                status_code = 0
+            # Convert response headers to dict
+            for name, value in headers:
+                resp_headers_dict[str(name).lower()] = str(value)
+            resp_content_type = resp_headers_dict.get("content-type", "")
+            return start_response(status, headers, exc_info)
+
+        with _span_context(span):
+            try:
+                result = self.app(environ, wrapped_start_response)
+                # Collect response body
+                response_body_chunks: list[bytes] = []
+                collected: list[bytes] = []
+                for chunk in result:
+                    collected.append(chunk)
+                    response_body_chunks.append(chunk)
+                response_body = b"".join(response_body_chunks)
+
+                # Capture request data (FR6)
+                capture_request_data(
+                    span,
+                    method=method,
+                    url=full_url,
+                    headers=req_headers,
+                    body=req_body,
+                    content_type=req_content_type,
+                    query_params=query,
+                )
+
+                # Capture response data (FR7)
+                capture_response_data(
+                    span,
+                    status_code=status_code,
+                    headers=resp_headers_dict,
+                    body=response_body,
+                    content_type=resp_content_type,
+                )
+
+                return collected
+            except Exception as exc:
+                span.set_status("ERROR", str(exc))
+                span.set_attribute("error", "true")
+                span.set_attribute("error.type", type(exc).__name__)
+                span.set_attribute("error.message", str(exc))
+                raise
+            finally:
+                span.set_attribute("http.status_code", str(status_code))
+                span.end()
+                if self._on_span is not None:
+                    try:
+                        self._on_span(span.to_dict())
+                    except Exception:
+                        logger.debug("Error in on_span callback", exc_info=True)
+
+
+class FlaskInstrumentor(BaseInstrumentor):
+    """Instruments Flask applications with WSGI middleware wrapping."""
+
+    def __init__(self, framework_info: Any) -> None:
+        super().__init__(framework_info)
+        self._active = False
+
+    def activate(self) -> None:
+        self._active = True
+        logger.info("TRACELY: Flask instrumentation activated")
+
+    def deactivate(self) -> None:
+        self._active = False
+        logger.debug("TRACELY: Flask instrumentation deactivated")
+
+    @property
+    def is_active(self) -> bool:
+        return self._active
+
+    @staticmethod
+    def wrap_app(
+        app: Callable[..., Iterable[bytes]],
+        on_span: Callable[[dict[str, Any]], None] | None = None,
+        service_name: str | None = None,
+        on_end: Callable[[Span], None] | None = None,
+    ) -> TracelyWSGIMiddleware:
+        """Wrap a WSGI app with TRACELY middleware."""
+        return TracelyWSGIMiddleware(
+            app=app, on_span=on_span, service_name=service_name, on_end=on_end,
+        )

tracely/instrumentation/generic.py

@@ -0,0 +1,38 @@
+"""Generic fallback instrumentation when no framework is detected.
+
+Provides basic Python process instrumentation and logs guidance
+about manual instrumentation options.
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("tracely")
+
+
+class GenericInstrumentor:
+    """Fallback instrumentor for non-framework Python applications.
+
+    Logs an info message about manual instrumentation when activated.
+    Does not require BaseInstrumentor inheritance since it is used
+    outside the framework detection flow.
+    """
+
+    def __init__(self) -> None:
+        self._active = False
+
+    def activate(self) -> None:
+        self._active = True
+        logger.info(
+            "TRACELY: No supported framework detected. "
+            "For manual instrumentation, use tracely.create_span() "
+            "to instrument your application code."
+        )
+
+    def deactivate(self) -> None:
+        self._active = False
+
+    @property
+    def is_active(self) -> bool:
+        return self._active

tracely/instrumentation/httpx_inst.py

@@ -0,0 +1,130 @@
+"""External HTTP call instrumentation via httpx event hooks.
+
+Creates child spans for outbound HTTP calls made through httpx,
+capturing method, URL, status code, and duration (AC3).
+
+All instrumentation is fail-silent — never crashes the host application.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from tracely.context import get_current_span
+from tracely.span import Span
+
+logger = logging.getLogger("tracely")
+
+
+class HttpxInstrumentor:
+    """Instruments httpx clients to create child spans for outbound HTTP calls.
+
+    Usage:
+        instrumentor = HttpxInstrumentor()
+        instrumentor.activate()  # Patches httpx.Client and httpx.AsyncClient
+        instrumentor.deactivate()  # Restores originals
+    """
+
+    def __init__(self) -> None:
+        self._active = False
+        self._original_sync_send: Any = None
+        self._original_async_send: Any = None
+
+    def activate(self) -> None:
+        """Patch httpx Client/AsyncClient to create child spans."""
+        if self._active:
+            return
+
+        self._original_sync_send = httpx.Client.send
+        self._original_async_send = httpx.AsyncClient.send
+
+        original_sync = self._original_sync_send
+        original_async = self._original_async_send
+
+        def instrumented_sync_send(client_self: httpx.Client, request: httpx.Request, **kwargs: Any) -> httpx.Response:
+            parent = get_current_span()
+            if parent is None:
+                return original_sync(client_self, request, **kwargs)
+
+            span = Span(
+                name=f"HTTP {request.method} {request.url.host}",
+                parent=parent,
+                kind="CLIENT",
+            )
+            span.set_attribute("http.method", str(request.method))
+            span.set_attribute("http.url", str(request.url))
+
+            try:
+                response = original_sync(client_self, request, **kwargs)
+                span.set_attribute("http.status_code", str(response.status_code))
+                if response.status_code >= 400:
+                    span.set_status("ERROR", f"HTTP {response.status_code}")
+                else:
+                    span.set_status("OK")
+                return response
+            except Exception as exc:
+                span.set_status("ERROR", str(exc))
+                span.set_attribute("error", "true")
+                span.set_attribute("error.type", type(exc).__name__)
+                span.set_attribute("error.message", str(exc))
+                raise
+            finally:
+                span.end()
+
+        async def instrumented_async_send(client_self: httpx.AsyncClient, request: httpx.Request, **kwargs: Any) -> httpx.Response:
+            parent = get_current_span()
+            if parent is None:
+                return await original_async(client_self, request, **kwargs)
+
+            span = Span(
+                name=f"HTTP {request.method} {request.url.host}",
+                parent=parent,
+                kind="CLIENT",
+            )
+            span.set_attribute("http.method", str(request.method))
+            span.set_attribute("http.url", str(request.url))
+
+            try:
+                response = await original_async(client_self, request, **kwargs)
+                span.set_attribute("http.status_code", str(response.status_code))
+                if response.status_code >= 400:
+                    span.set_status("ERROR", f"HTTP {response.status_code}")
+                else:
+                    span.set_status("OK")
+                return response
+            except Exception as exc:
+                span.set_status("ERROR", str(exc))
+                span.set_attribute("error", "true")
+                span.set_attribute("error.type", type(exc).__name__)
+                span.set_attribute("error.message", str(exc))
+                raise
+            finally:
+                span.end()
+
+        httpx.Client.send = instrumented_sync_send  # type: ignore[assignment]
+        httpx.AsyncClient.send = instrumented_async_send  # type: ignore[assignment]
+        self._active = True
+        logger.info("TRACELY: httpx instrumentation activated")
+
+    def deactivate(self) -> None:
+        """Restore original httpx send methods."""
+        if not self._active:
+            return
+
+        if self._original_sync_send is not None:
+            httpx.Client.send = self._original_sync_send  # type: ignore[assignment]
+        if self._original_async_send is not None:
+            httpx.AsyncClient.send = self._original_async_send  # type: ignore[assignment]
+
+        self._active = False
+        self._original_sync_send = None
+        self._original_async_send = None
+        logger.debug("TRACELY: httpx instrumentation deactivated")
+
+    @property
+    def is_active(self) -> bool:
+        return self._active

tracely/log_handler.py

@@ -0,0 +1,55 @@
+"""Log event handler for span association (FR60).
+
+Captures log events and associates them with the currently active
+span's span_id and trace_id. Only captures events when a span is
+active — otherwise silently discards them.
+
+All operations are fail-silent to avoid crashing the host application.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+from tracely.context import get_current_span
+
+_logger = logging.getLogger("tracely")
+
+
+class TracelyLogHandler(logging.Handler):
+    """Logging handler that associates log events with active spans.
+
+    Args:
+        on_event: Callback invoked with a dict for each captured log event.
+                  If None, events are silently discarded.
+    """
+
+    def __init__(self, on_event: Callable[[dict[str, Any]], None] | None = None) -> None:
+        super().__init__()
+        self._on_event = on_event
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            span = get_current_span()
+            if span is None:
+                return
+
+            event: dict[str, Any] = {
+                "trace_id": span.trace_id,
+                "span_id": span.span_id,
+                "level": record.levelname,
+                "message": record.getMessage(),
+                "timestamp": record.created,
+                "logger_name": record.name,
+            }
+
+            if record.exc_info and record.exc_info[1] is not None:
+                exc = record.exc_info[1]
+                event["exception_type"] = type(exc).__name__
+                event["exception_message"] = str(exc)
+
+            if self._on_event is not None:
+                self._on_event(event)
+        except Exception:
+            _logger.debug("Error in TracelyLogHandler.emit", exc_info=True)

tracely/logging_api.py

@@ -0,0 +1,38 @@
+"""Public logging API for adding events to the active span.
+
+Provides debug(), info(), warning(), error() functions that attach
+log events to the currently active span. All functions are fail-silent
+and no-op when no span is active.
+"""
+
+from __future__ import annotations
+
+from tracely.context import get_current_span
+
+
+def debug(message: str, **attributes: str) -> None:
+    """Add a DEBUG event to the active span."""
+    span = get_current_span()
+    if span is not None:
+        span.add_event(message, level="DEBUG", attributes=attributes or None)
+
+
+def info(message: str, **attributes: str) -> None:
+    """Add an INFO event to the active span."""
+    span = get_current_span()
+    if span is not None:
+        span.add_event(message, level="INFO", attributes=attributes or None)
+
+
+def warning(message: str, **attributes: str) -> None:
+    """Add a WARNING event to the active span."""
+    span = get_current_span()
+    if span is not None:
+        span.add_event(message, level="WARNING", attributes=attributes or None)
+
+
+def error(message: str, **attributes: str) -> None:
+    """Add an ERROR event to the active span."""
+    span = get_current_span()
+    if span is not None:
+        span.add_event(message, level="ERROR", attributes=attributes or None)

tracely/otlp.py

@@ -0,0 +1,128 @@
+"""OTLP protobuf serialization for span data (AR2).
+
+Converts internal span dicts to OTLP ExportTraceServiceRequest protobuf bytes
+for transmission via OTLP/HTTP.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Any
+
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
+    ExportTraceServiceRequest,
+)
+from opentelemetry.proto.common.v1.common_pb2 import AnyValue, KeyValue
+from opentelemetry.proto.resource.v1.resource_pb2 import Resource
+from opentelemetry.proto.trace.v1.trace_pb2 import (
+    ResourceSpans,
+    ScopeSpans,
+    Span as OtlpSpan,
+    Status,
+)
+
+logger = logging.getLogger("tracely")
+
+# OTLP SpanKind mapping
+_KIND_MAP: dict[str, int] = {
+    "INTERNAL": 1,  # SPAN_KIND_INTERNAL
+    "SERVER": 2,    # SPAN_KIND_SERVER
+    "CLIENT": 3,    # SPAN_KIND_CLIENT
+    "PRODUCER": 4,  # SPAN_KIND_PRODUCER
+    "CONSUMER": 5,  # SPAN_KIND_CONSUMER
+}
+
+# OTLP StatusCode mapping
+_STATUS_MAP: dict[str, int] = {
+    "UNSET": 0,  # STATUS_CODE_UNSET
+    "OK": 1,     # STATUS_CODE_OK
+    "ERROR": 2,  # STATUS_CODE_ERROR
+}
+
+
+def _seconds_to_nanos(ts: float | None) -> int:
+    """Convert a Unix timestamp in seconds to nanoseconds."""
+    if ts is None:
+        return 0
+    return int(ts * 1_000_000_000)
+
+
+def _make_kv(key: str, value: str) -> KeyValue:
+    """Create an OTLP KeyValue with a string value."""
+    return KeyValue(key=key, value=AnyValue(string_value=str(value)))
+
+
+def _span_to_otlp(span_dict: dict[str, Any]) -> OtlpSpan:
+    """Convert an internal span dict to an OTLP Span message."""
+    trace_id = bytes.fromhex(span_dict["trace_id"])
+    span_id = bytes.fromhex(span_dict["span_id"])
+
+    parent = span_dict.get("parent_span_id")
+    parent_span_id = bytes.fromhex(parent) if parent else b""
+
+    # Build attributes from span dict + tracely.span_type
+    attributes = []
+    for k, v in span_dict.get("attributes", {}).items():
+        attributes.append(_make_kv(k, v))
+    attributes.append(_make_kv("tracely.span_type", span_dict.get("span_type", "span")))
+
+    # Build events
+    events = []
+    for evt in span_dict.get("events", []):
+        evt_attrs = [_make_kv(k, v) for k, v in evt.get("attributes", {}).items()]
+        if evt.get("level"):
+            evt_attrs.append(_make_kv("level", evt["level"]))
+        events.append(OtlpSpan.Event(
+            name=evt.get("message", ""),
+            time_unix_nano=_seconds_to_nanos(evt.get("timestamp")),
+            attributes=evt_attrs,
+        ))
+
+    # Build status
+    status_code = _STATUS_MAP.get(span_dict.get("status_code", "UNSET"), 0)
+    status = Status(
+        code=status_code,
+        message=span_dict.get("status_message", ""),
+    )
+
+    return OtlpSpan(
+        trace_id=trace_id,
+        span_id=span_id,
+        parent_span_id=parent_span_id,
+        name=span_dict.get("span_name", ""),
+        kind=_KIND_MAP.get(span_dict.get("kind", "INTERNAL"), 1),
+        start_time_unix_nano=_seconds_to_nanos(span_dict.get("start_time")),
+        end_time_unix_nano=_seconds_to_nanos(span_dict.get("end_time")),
+        attributes=attributes,
+        events=events,
+        status=status,
+    )
+
+
+def serialize_spans(spans: list[dict[str, Any]]) -> bytes:
+    """Serialize a list of span dicts to OTLP ExportTraceServiceRequest bytes.
+
+    Spans are grouped by service_name into separate ResourceSpans.
+    Returns protobuf-serialized bytes ready for OTLP/HTTP transport.
+    """
+    if not spans:
+        return ExportTraceServiceRequest().SerializeToString()
+
+    # Group spans by service_name
+    grouped: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for span_dict in spans:
+        svc = span_dict.get("service_name") or "unknown"
+        grouped[svc].append(span_dict)
+
+    resource_spans_list = []
+    for svc_name, svc_spans in grouped.items():
+        resource = Resource(attributes=[_make_kv("service.name", svc_name)])
+        otlp_spans = [_span_to_otlp(s) for s in svc_spans]
+        scope_spans = ScopeSpans(spans=otlp_spans)
+        resource_spans_list.append(
+            ResourceSpans(resource=resource, scope_spans=[scope_spans])
+        )
+
+    request = ExportTraceServiceRequest(resource_spans=resource_spans_list)
+    return request.SerializeToString()