justanalytics-python 0.1.0__py3-none-any.whl

justanalytics/__init__.py

@@ -0,0 +1,429 @@
+"""
+JustAnalytics Python SDK — end-to-end observability for Python applications.
+
+Provides traces, error capture, structured logging, and metrics ingestion
+to the JustAnalytics platform (Datadog + Sentry + Google Analytics in One).
+
+Quick Start::
+
+    import justanalytics
+
+    justanalytics.init(
+        site_id="site_abc123",
+        api_key="ja_sk_your_api_key_here",
+        service_name="api-server",
+        environment="production",
+    )
+
+    # Create traced spans
+    with justanalytics.start_span("process-order") as span:
+        span.set_attribute("order.id", "12345")
+        result = process_order()
+
+    # Capture exceptions
+    try:
+        risky_operation()
+    except Exception as e:
+        justanalytics.capture_exception(e, tags={"module": "payments"})
+
+    # Capture messages
+    justanalytics.capture_message("Deployment complete", level="info")
+
+    # Set user context
+    justanalytics.set_user(id="user-123", email="alice@example.com")
+
+    # Set tags
+    justanalytics.set_tag("feature", "checkout")
+
+    # Flush before shutdown
+    justanalytics.flush()
+    justanalytics.close()
+
+Wire Protocol (all SDKs share the same endpoints)::
+
+    POST /api/ingest/spans    — trace spans (batched array)
+    POST /api/ingest/errors   — error events (individual)
+    POST /api/ingest/logs     — log entries (batched array)
+    POST /api/ingest/metrics  — infrastructure metrics (batched array)
+
+    Headers:
+      Authorization: Bearer ja_sk_...
+      Content-Type: application/json
+      X-Site-ID: <siteId>
+      User-Agent: justanalytics-python/0.1.0
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from contextlib import contextmanager
+from typing import Any, Callable, Dict, Generator, List, Optional, TypeVar, Union
+
+from .client import JustAnalyticsClient
+from .context import get_active_span, get_tags, get_trace_id, get_user
+from .span import Span
+from .trace_context import TraceparentData, parse_traceparent, serialize_traceparent
+from .types import (
+    ErrorLevel,
+    ErrorPayload,
+    LogLevel,
+    LogPayload,
+    MetricPayload,
+    SpanEvent,
+    SpanKind,
+    SpanPayload,
+    SpanStatus,
+    UserContext,
+)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# --- Singleton Client ---
+
+_client = JustAnalyticsClient()
+
+
+# --- Public API Functions ---
+
+
+def init(
+    site_id: str,
+    api_key: str,
+    service_name: str,
+    environment: Optional[str] = None,
+    release: Optional[str] = None,
+    server_url: Optional[str] = None,
+    debug: bool = False,
+    flush_interval_s: float = 2.0,
+    max_batch_size: int = 100,
+    enabled: bool = True,
+) -> None:
+    """
+    Initialize the JustAnalytics SDK.
+
+    Must be called before any other SDK method. Calling ``init()`` more
+    than once logs a warning and is ignored.
+
+    Args:
+        site_id: Site ID from the JustAnalytics dashboard.
+        api_key: API key (format: ``ja_sk_...``).
+        service_name: Service name (e.g., "api-server", "worker").
+        environment: Deployment environment (e.g., "production", "staging").
+        release: Release/version string (e.g., "1.2.3", git SHA).
+        server_url: Base URL of JustAnalytics server.
+        debug: Enable debug logging.
+        flush_interval_s: Flush interval in seconds (default: 2.0).
+        max_batch_size: Max items per batch before immediate flush (default: 100).
+        enabled: Enable/disable the SDK (default: True).
+
+    Raises:
+        ValueError: If required fields are missing.
+
+    Example::
+
+        justanalytics.init(
+            site_id="site_abc123",
+            api_key="ja_sk_...",
+            service_name="api-server",
+            environment="production",
+        )
+    """
+    _client.init(
+        site_id=site_id,
+        api_key=api_key,
+        service_name=service_name,
+        environment=environment,
+        release=release,
+        server_url=server_url,
+        debug=debug,
+        flush_interval_s=flush_interval_s,
+        max_batch_size=max_batch_size,
+        enabled=enabled,
+    )
+
+
+def is_initialized() -> bool:
+    """Whether ``init()`` has been called successfully."""
+    return _client.is_initialized
+
+
+@contextmanager
+def start_span(
+    name: str,
+    op: Optional[str] = None,
+    kind: SpanKind = SpanKind.INTERNAL,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> Generator[Span, None, None]:
+    """
+    Create a span as a context manager.
+
+    The span is automatically ended when the ``with`` block exits.
+    If an exception occurs, the span status is set to ``error``.
+
+    Nested ``start_span()`` calls automatically form parent-child
+    relationships via ``contextvars``.
+
+    Args:
+        name: Operation name for the span.
+        op: Optional operation type.
+        kind: Span kind (default: INTERNAL).
+        attributes: Initial attributes.
+
+    Yields:
+        The created Span instance.
+
+    Example::
+
+        with justanalytics.start_span("fetch-user") as span:
+            span.set_attribute("user.id", user_id)
+            user = db.get_user(user_id)
+    """
+    with _client.start_span(name, op=op, kind=kind, attributes=attributes) as span:
+        yield span
+
+
+def span(
+    name: Optional[str] = None,
+    op: Optional[str] = None,
+    kind: SpanKind = SpanKind.INTERNAL,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator that wraps a function in a span.
+
+    Args:
+        name: Span name (defaults to the function's qualified name).
+        op: Optional operation type.
+        kind: Span kind.
+        attributes: Initial span attributes.
+
+    Returns:
+        A decorator.
+
+    Example::
+
+        @justanalytics.span(op="db.query")
+        def get_user(user_id: str):
+            return db.query(...)
+    """
+    return _client.span_decorator(name=name, op=op, kind=kind, attributes=attributes)
+
+
+def capture_exception(
+    error: BaseException,
+    tags: Optional[Dict[str, str]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+    user: Optional[UserContext] = None,
+    level: Union[ErrorLevel, str] = ErrorLevel.ERROR,
+    fingerprint: Optional[List[str]] = None,
+) -> str:
+    """
+    Capture an exception and send it to JustAnalytics.
+
+    Automatically attaches the current trace_id, span_id, user context,
+    and tags from the contextvars context.
+
+    Args:
+        error: The exception to capture.
+        tags: Additional tags (merged with context tags).
+        extra: Arbitrary extra data.
+        user: User context (overrides context user).
+        level: Severity level (default: ERROR).
+        fingerprint: Custom fingerprint for grouping.
+
+    Returns:
+        A unique event_id, or empty string if SDK is disabled.
+
+    Example::
+
+        try:
+            risky_operation()
+        except Exception as e:
+            justanalytics.capture_exception(e, tags={"module": "payments"})
+    """
+    if isinstance(level, str):
+        level = ErrorLevel(level)
+    return _client.capture_exception(
+        error=error,
+        tags=tags,
+        extra=extra,
+        user=user,
+        level=level,
+        fingerprint=fingerprint,
+    )
+
+
+def capture_message(
+    message: str,
+    level: Union[ErrorLevel, str] = ErrorLevel.INFO,
+    tags: Optional[Dict[str, str]] = None,
+    extra: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Capture a message and send it to JustAnalytics.
+
+    Args:
+        message: The message string.
+        level: Severity level (default: INFO).
+        tags: Additional tags.
+        extra: Arbitrary extra data.
+
+    Returns:
+        A unique event_id, or empty string if SDK is disabled.
+
+    Example::
+
+        justanalytics.capture_message(
+            "User exceeded rate limit",
+            level="warning",
+            tags={"userId": user.id},
+        )
+    """
+    if isinstance(level, str):
+        level = ErrorLevel(level)
+    return _client.capture_message(message=message, level=level, tags=tags, extra=extra)
+
+
+def set_user(
+    id: Optional[str] = None,
+    email: Optional[str] = None,
+    username: Optional[str] = None,
+) -> None:
+    """
+    Set user context for the current execution scope.
+
+    Args:
+        id: User ID.
+        email: User email.
+        username: Username.
+
+    Example::
+
+        justanalytics.set_user(id="user-123", email="alice@example.com")
+    """
+    _client.set_user(id=id, email=email, username=username)
+
+
+def set_tag(key: str, value: str) -> None:
+    """
+    Set a tag for the current execution scope.
+
+    Tags are attached as attributes on all spans created within
+    the current contextvars scope.
+
+    Args:
+        key: Tag key.
+        value: Tag value.
+
+    Example::
+
+        justanalytics.set_tag("feature", "checkout")
+    """
+    _client.set_tag(key, value)
+
+
+def log(
+    level: Union[LogLevel, str],
+    message: str,
+    attributes: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    Send a structured log entry to JustAnalytics.
+
+    Args:
+        level: Log severity level.
+        message: Log message.
+        attributes: Optional key-value metadata.
+
+    Example::
+
+        justanalytics.log("info", "User logged in", {"userId": "u123"})
+    """
+    if isinstance(level, str):
+        level = LogLevel(level)
+    _client.log(level=level, message=message, attributes=attributes)
+
+
+def record_metric(
+    metric_name: str,
+    value: float,
+    tags: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    Record a custom infrastructure metric.
+
+    Args:
+        metric_name: Metric name using dot notation.
+        value: Numeric value.
+        tags: Optional additional tags.
+
+    Example::
+
+        justanalytics.record_metric("custom.queue_size", 42, {"queue": "emails"})
+    """
+    _client.record_metric(metric_name=metric_name, value=value, tags=tags)
+
+
+def flush() -> None:
+    """
+    Manually flush all pending data to the server.
+
+    Useful before a serverless function completes or in tests.
+    """
+    _client.flush()
+
+
+def close() -> None:
+    """
+    Shut down the SDK: flush remaining data, stop timers.
+
+    After calling ``close()``, the SDK cannot be used again
+    until ``init()`` is called.
+    """
+    _client.close()
+
+
+# --- Exported Names ---
+
+__all__ = [
+    "__version__",
+    # Lifecycle
+    "init",
+    "is_initialized",
+    "flush",
+    "close",
+    # Spans
+    "start_span",
+    "span",
+    "get_active_span",
+    "get_trace_id",
+    # Errors
+    "capture_exception",
+    "capture_message",
+    # Context
+    "set_user",
+    "set_tag",
+    "get_user",
+    "get_tags",
+    # Logging
+    "log",
+    # Metrics
+    "record_metric",
+    # W3C Trace Context
+    "parse_traceparent",
+    "serialize_traceparent",
+    # Types
+    "Span",
+    "SpanKind",
+    "SpanStatus",
+    "SpanEvent",
+    "SpanPayload",
+    "ErrorLevel",
+    "ErrorPayload",
+    "LogLevel",
+    "LogPayload",
+    "MetricPayload",
+    "UserContext",
+    "TraceparentData",
+]