justanalytics-python 0.1.0__py3-none-any.whl

justanalytics/transport.py

@@ -0,0 +1,430 @@
+"""
+Batched HTTP transport for sending telemetry data to the JustAnalytics server.
+
+Collects spans, errors, logs, and metrics in thread-safe in-memory queues
+and periodically flushes them to their respective ingestion endpoints:
+- Spans:   POST /api/ingest/spans   (batched array, max 100)
+- Errors:  POST /api/ingest/errors  (individual POST per error)
+- Logs:    POST /api/ingest/logs    (batched array, max 200)
+- Metrics: POST /api/ingest/metrics (batched array, max 500)
+
+Flush behavior:
+- Timer-based: flushes every ``flush_interval_s`` seconds (default: 2.0)
+- Size-based: flushes immediately when a buffer reaches ``max_batch_size`` (default: 100)
+- Manual: ``flush()`` can be called explicitly
+- Shutdown: ``atexit`` handler ensures pending data is flushed
+
+Error handling:
+- HTTP 429 (rate limited): doubles flush interval for 60 seconds, then resets
+- Network errors / non-2xx: logs warning (debug mode), drops the batch
+- Never raises exceptions that could crash the host process
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import logging
+import threading
+import time
+from collections import deque
+from typing import Any, Deque, Dict, List, Optional
+from urllib.parse import urljoin
+
+import urllib3
+
+from .types import ErrorPayload, LogPayload, MetricPayload
+
+logger = logging.getLogger("justanalytics.transport")
+
+# SDK version included in User-Agent header
+_SDK_VERSION = "0.1.0"
+
+
+class BatchTransport:
+    """
+    Thread-safe batched HTTP transport for JustAnalytics telemetry data.
+
+    Uses urllib3 for connection pooling and keep-alive. All public methods
+    are safe to call from any thread.
+
+    Args:
+        server_url: Base URL of the JustAnalytics server.
+        api_key: API key for authentication (``ja_sk_...``).
+        site_id: Site ID from the JustAnalytics dashboard.
+        flush_interval_s: Flush interval in seconds (default: 2.0).
+        max_batch_size: Max items per batch before immediate flush (default: 100).
+        debug: Enable debug logging (default: False).
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        api_key: str,
+        site_id: str,
+        flush_interval_s: float = 2.0,
+        max_batch_size: int = 100,
+        debug: bool = False,
+    ) -> None:
+        self._server_url = server_url.rstrip("/")
+        self._api_key = api_key
+        self._site_id = site_id
+        self._flush_interval_s = flush_interval_s
+        self._original_flush_interval_s = flush_interval_s
+        self._max_batch_size = max_batch_size
+        self._debug = debug
+
+        # Thread-safe buffers
+        self._span_buffer: Deque[Dict[str, Any]] = deque()
+        self._error_buffer: Deque[Dict[str, Any]] = deque()
+        self._log_buffer: Deque[Dict[str, Any]] = deque()
+        self._metric_buffer: Deque[Dict[str, Any]] = deque()
+        self._lock = threading.Lock()
+
+        # Flushing guards
+        self._flushing_spans = False
+        self._flushing_errors = False
+        self._flushing_logs = False
+        self._flushing_metrics = False
+
+        # Timer
+        self._timer: Optional[threading.Timer] = None
+        self._running = False
+
+        # Connection pool
+        self._http = urllib3.PoolManager(
+            num_pools=4,
+            maxsize=10,
+            timeout=urllib3.Timeout(connect=5.0, read=10.0),
+            retries=urllib3.Retry(total=0),  # No retries; we handle drops ourselves
+        )
+
+        # Common headers
+        self._headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+            "X-Site-ID": self._site_id,
+            "User-Agent": f"justanalytics-python/{_SDK_VERSION}",
+        }
+
+        # Backoff timer
+        self._backoff_timer: Optional[threading.Timer] = None
+
+    # --- Buffer Enqueue Methods ---
+
+    def enqueue_span(self, span_dict: Dict[str, Any]) -> None:
+        """Enqueue a serialized span for batched sending.
+
+        If the buffer reaches ``max_batch_size``, triggers an immediate flush.
+
+        Args:
+            span_dict: Serialized span dict (from Span.to_dict()).
+        """
+        with self._lock:
+            self._span_buffer.append(span_dict)
+            size = len(self._span_buffer)
+        if size >= self._max_batch_size:
+            self._flush_spans_async()
+
+    def enqueue_error(self, error_dict: Dict[str, Any]) -> None:
+        """Enqueue a serialized error for sending.
+
+        Args:
+            error_dict: Serialized error dict (from ErrorPayload.to_dict()).
+        """
+        with self._lock:
+            self._error_buffer.append(error_dict)
+            size = len(self._error_buffer)
+        if size >= self._max_batch_size:
+            self._flush_errors_async()
+
+    def enqueue_log(self, log_dict: Dict[str, Any]) -> None:
+        """Enqueue a serialized log entry for batched sending.
+
+        Args:
+            log_dict: Serialized log dict (from LogPayload.to_dict()).
+        """
+        with self._lock:
+            self._log_buffer.append(log_dict)
+            size = len(self._log_buffer)
+        if size >= self._max_batch_size:
+            self._flush_logs_async()
+
+    def enqueue_metric(self, metric_dict: Dict[str, Any]) -> None:
+        """Enqueue a serialized metric for batched sending.
+
+        Args:
+            metric_dict: Serialized metric dict (from MetricPayload.to_dict()).
+        """
+        with self._lock:
+            self._metric_buffer.append(metric_dict)
+            size = len(self._metric_buffer)
+        if size >= self._max_batch_size:
+            self._flush_metrics_async()
+
+    # --- Lifecycle ---
+
+    def start(self) -> None:
+        """Start the periodic flush timer."""
+        self._running = True
+        self._schedule_flush()
+        atexit.register(self._atexit_flush)
+
+    def stop(self) -> None:
+        """Stop the periodic flush timer."""
+        self._running = False
+        if self._timer:
+            self._timer.cancel()
+            self._timer = None
+        if self._backoff_timer:
+            self._backoff_timer.cancel()
+            self._backoff_timer = None
+
+    def flush(self) -> None:
+        """Flush all pending buffers synchronously.
+
+        Safe to call from any thread. Blocks until all buffers are flushed.
+        """
+        self._flush_spans()
+        self._flush_errors()
+        self._flush_logs()
+        self._flush_metrics()
+
+    @property
+    def pending_count(self) -> int:
+        """Total number of items across all buffers."""
+        return (
+            len(self._span_buffer)
+            + len(self._error_buffer)
+            + len(self._log_buffer)
+            + len(self._metric_buffer)
+        )
+
+    # --- Internal: Timer ---
+
+    def _schedule_flush(self) -> None:
+        """Schedule the next flush timer."""
+        if not self._running:
+            return
+        self._timer = threading.Timer(self._flush_interval_s, self._timer_flush)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _timer_flush(self) -> None:
+        """Called by the timer to flush all buffers and reschedule."""
+        try:
+            self.flush()
+        except Exception:
+            pass  # Never crash the timer thread
+        self._schedule_flush()
+
+    def _atexit_flush(self) -> None:
+        """Called by atexit to flush remaining data."""
+        self._running = False
+        if self._timer:
+            self._timer.cancel()
+        try:
+            self.flush()
+        except Exception:
+            pass  # Never crash during shutdown
+
+    # --- Internal: Async Flush Triggers ---
+
+    def _flush_spans_async(self) -> None:
+        """Trigger a span flush in a background thread."""
+        t = threading.Thread(target=self._flush_spans, daemon=True)
+        t.start()
+
+    def _flush_errors_async(self) -> None:
+        """Trigger an error flush in a background thread."""
+        t = threading.Thread(target=self._flush_errors, daemon=True)
+        t.start()
+
+    def _flush_logs_async(self) -> None:
+        """Trigger a log flush in a background thread."""
+        t = threading.Thread(target=self._flush_logs, daemon=True)
+        t.start()
+
+    def _flush_metrics_async(self) -> None:
+        """Trigger a metric flush in a background thread."""
+        t = threading.Thread(target=self._flush_metrics, daemon=True)
+        t.start()
+
+    # --- Internal: Flush Implementations ---
+
+    def _flush_spans(self) -> None:
+        """Flush all pending spans to POST /api/ingest/spans."""
+        if self._flushing_spans:
+            return
+        with self._lock:
+            if not self._span_buffer:
+                return
+            batch = list(self._span_buffer)
+            self._span_buffer.clear()
+        self._flushing_spans = True
+        try:
+            self._send_batch("/api/ingest/spans", {"spans": batch}, len(batch), "span")
+        except Exception as exc:
+            if self._debug:
+                logger.debug("Span flush failed, dropped %d span(s): %s", len(batch), exc)
+        finally:
+            self._flushing_spans = False
+
+    def _flush_errors(self) -> None:
+        """Flush all pending errors to POST /api/ingest/errors (one per request)."""
+        if self._flushing_errors:
+            return
+        with self._lock:
+            if not self._error_buffer:
+                return
+            batch = list(self._error_buffer)
+            self._error_buffer.clear()
+        self._flushing_errors = True
+        try:
+            for error_dict in batch:
+                self._send_single("/api/ingest/errors", error_dict, "error")
+        except Exception as exc:
+            if self._debug:
+                logger.debug("Error flush failed, dropped %d error(s): %s", len(batch), exc)
+        finally:
+            self._flushing_errors = False
+
+    def _flush_logs(self) -> None:
+        """Flush all pending logs to POST /api/ingest/logs."""
+        if self._flushing_logs:
+            return
+        with self._lock:
+            if not self._log_buffer:
+                return
+            batch = list(self._log_buffer)
+            self._log_buffer.clear()
+        self._flushing_logs = True
+        try:
+            self._send_batch("/api/ingest/logs", {"logs": batch}, len(batch), "log")
+        except Exception as exc:
+            if self._debug:
+                logger.debug("Log flush failed, dropped %d log(s): %s", len(batch), exc)
+        finally:
+            self._flushing_logs = False
+
+    def _flush_metrics(self) -> None:
+        """Flush all pending metrics to POST /api/ingest/metrics."""
+        if self._flushing_metrics:
+            return
+        with self._lock:
+            if not self._metric_buffer:
+                return
+            batch = list(self._metric_buffer)
+            self._metric_buffer.clear()
+        self._flushing_metrics = True
+        try:
+            self._send_batch(
+                "/api/ingest/metrics", {"metrics": batch}, len(batch), "metric"
+            )
+        except Exception as exc:
+            if self._debug:
+                logger.debug("Metric flush failed, dropped %d metric(s): %s", len(batch), exc)
+        finally:
+            self._flushing_metrics = False
+
+    # --- Internal: HTTP Sending ---
+
+    def _send_batch(
+        self, path: str, body: Dict[str, Any], count: int, label: str
+    ) -> None:
+        """Send a batched POST request to the given path.
+
+        Args:
+            path: API path (e.g., "/api/ingest/spans").
+            body: Request body dict to JSON-encode.
+            count: Number of items for logging.
+            label: Item type label for logging (e.g., "span").
+        """
+        url = f"{self._server_url}{path}"
+        try:
+            data = json.dumps(body).encode("utf-8")
+            response = self._http.request(
+                "POST",
+                url,
+                body=data,
+                headers=self._headers,
+            )
+            status = response.status
+            if 200 <= status < 300:
+                if self._debug:
+                    logger.debug("Flushed %d %s(s) successfully", count, label)
+            elif status == 429:
+                self._handle_backoff()
+                if self._debug:
+                    logger.debug(
+                        "Rate limited (429). Backing off. Dropped %d %s(s).",
+                        count,
+                        label,
+                    )
+            else:
+                if self._debug:
+                    logger.debug(
+                        "Flush failed HTTP %d. Dropped %d %s(s). Response: %s",
+                        status,
+                        count,
+                        label,
+                        response.data.decode("utf-8", errors="replace")[:500],
+                    )
+        except Exception as exc:
+            if self._debug:
+                logger.debug(
+                    "Network error during %s flush: %s. Dropped %d %s(s).",
+                    label,
+                    exc,
+                    count,
+                    label,
+                )
+
+    def _send_single(self, path: str, body: Dict[str, Any], label: str) -> None:
+        """Send a single POST request.
+
+        Args:
+            path: API path.
+            body: Request body dict.
+            label: Item type label for logging.
+        """
+        url = f"{self._server_url}{path}"
+        try:
+            data = json.dumps(body).encode("utf-8")
+            response = self._http.request(
+                "POST",
+                url,
+                body=data,
+                headers=self._headers,
+            )
+            status = response.status
+            if 200 <= status < 300:
+                if self._debug:
+                    logger.debug("Sent %s event successfully", label)
+            elif status == 429:
+                self._handle_backoff()
+                if self._debug:
+                    logger.debug("Rate limited (429) sending %s event", label)
+            else:
+                if self._debug:
+                    logger.debug(
+                        "Failed to send %s event: HTTP %d", label, status
+                    )
+        except Exception as exc:
+            if self._debug:
+                logger.debug("Network error sending %s event: %s", label, exc)
+
+    def _handle_backoff(self) -> None:
+        """Handle HTTP 429 backoff: double flush interval for 60 seconds."""
+        self._flush_interval_s = self._original_flush_interval_s * 2
+
+        # Cancel existing backoff timer
+        if self._backoff_timer:
+            self._backoff_timer.cancel()
+
+        def reset_interval() -> None:
+            self._flush_interval_s = self._original_flush_interval_s
+
+        self._backoff_timer = threading.Timer(60.0, reset_interval)
+        self._backoff_timer.daemon = True
+        self._backoff_timer.start()

justanalytics/types.py

@@ -0,0 +1,214 @@
+"""
+Shared types and enumerations for the JustAnalytics Python SDK.
+
+Provides type definitions matching the wire protocol expected by
+the JustAnalytics ingestion endpoints (POST /api/ingest/*).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from dataclasses import dataclass, field
+
+
+class SpanKind(str, Enum):
+    """Valid span kinds (OpenTelemetry-compatible)."""
+
+    CLIENT = "client"
+    SERVER = "server"
+    PRODUCER = "producer"
+    CONSUMER = "consumer"
+    INTERNAL = "internal"
+
+
+class SpanStatus(str, Enum):
+    """Valid span statuses."""
+
+    OK = "ok"
+    ERROR = "error"
+    UNSET = "unset"
+
+
+class LogLevel(str, Enum):
+    """Valid log severity levels matching POST /api/ingest/logs schema."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+    FATAL = "fatal"
+
+
+class ErrorLevel(str, Enum):
+    """Valid error severity levels matching POST /api/ingest/errors schema."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    FATAL = "fatal"
+
+
+class MechanismType(str, Enum):
+    """How the error was captured."""
+
+    MANUAL = "manual"
+    UNCAUGHT_EXCEPTION = "uncaughtException"
+    UNHANDLED_REJECTION = "unhandledRejection"
+
+
+@dataclass
+class UserContext:
+    """User context attached to spans, errors, and logs."""
+
+    id: Optional[str] = None
+    email: Optional[str] = None
+    username: Optional[str] = None
+
+    def to_dict(self) -> Optional[Dict[str, str]]:
+        """Serialize to dict, returning None if all fields are empty."""
+        result: Dict[str, str] = {}
+        if self.id:
+            result["id"] = self.id
+        if self.email:
+            result["email"] = self.email
+        if self.username:
+            result["username"] = self.username
+        return result if result else None
+
+
+@dataclass
+class SpanEvent:
+    """A timestamped event attached to a span."""
+
+    name: str
+    timestamp: str
+    attributes: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dict for the wire protocol."""
+        result: Dict[str, Any] = {
+            "name": self.name,
+            "timestamp": self.timestamp,
+        }
+        if self.attributes:
+            result["attributes"] = self.attributes
+        return result
+
+
+@dataclass
+class SpanPayload:
+    """Serialized span payload matching POST /api/ingest/spans schema."""
+
+    id: str
+    trace_id: str
+    parent_span_id: Optional[str]
+    operation_name: str
+    service_name: str
+    kind: str
+    start_time: str
+    end_time: Optional[str]
+    duration: Optional[int]
+    status: str
+    status_message: Optional[str]
+    attributes: Dict[str, Any]
+    events: List[Dict[str, Any]]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dict matching the server's Zod schema (camelCase keys)."""
+        return {
+            "id": self.id,
+            "traceId": self.trace_id,
+            "parentSpanId": self.parent_span_id,
+            "operationName": self.operation_name,
+            "serviceName": self.service_name,
+            "kind": self.kind,
+            "startTime": self.start_time,
+            "endTime": self.end_time,
+            "duration": self.duration,
+            "status": self.status,
+            "statusMessage": self.status_message,
+            "attributes": self.attributes,
+            "events": self.events,
+        }
+
+
+@dataclass
+class ErrorPayload:
+    """Serialized error payload matching POST /api/ingest/errors schema."""
+
+    event_id: str
+    timestamp: str
+    error: Dict[str, Any]
+    level: str
+    mechanism: Dict[str, Any]
+    context: Dict[str, Any]
+    trace: Optional[Dict[str, Optional[str]]]
+    user: Optional[Dict[str, str]]
+    tags: Optional[Dict[str, str]]
+    extra: Optional[Dict[str, Any]]
+    fingerprint: Optional[List[str]]
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dict matching the server's Zod schema (camelCase keys)."""
+        return {
+            "eventId": self.event_id,
+            "timestamp": self.timestamp,
+            "error": self.error,
+            "level": self.level,
+            "mechanism": self.mechanism,
+            "context": self.context,
+            "trace": self.trace,
+            "user": self.user,
+            "tags": self.tags,
+            "extra": self.extra,
+            "fingerprint": self.fingerprint,
+        }
+
+
+@dataclass
+class LogPayload:
+    """Serialized log entry matching POST /api/ingest/logs schema."""
+
+    level: str
+    message: str
+    service_name: str
+    timestamp: str
+    trace_id: Optional[str]
+    span_id: Optional[str]
+    attributes: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dict matching the server's Zod schema (camelCase keys)."""
+        return {
+            "level": self.level,
+            "message": self.message,
+            "serviceName": self.service_name,
+            "timestamp": self.timestamp,
+            "traceId": self.trace_id,
+            "spanId": self.span_id,
+            "attributes": self.attributes,
+        }
+
+
+@dataclass
+class MetricPayload:
+    """Serialized metric data point matching POST /api/ingest/metrics schema."""
+
+    metric_name: str
+    value: float
+    service_name: str
+    timestamp: str
+    tags: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to dict matching the server's Zod schema (camelCase keys)."""
+        return {
+            "metricName": self.metric_name,
+            "value": self.value,
+            "serviceName": self.service_name,
+            "timestamp": self.timestamp,
+            "tags": self.tags,
+        }