queuelens 0.1.0__py3-none-any.whl

queuelens/__init__.py

@@ -0,0 +1,5 @@
+from queuelens.client import QueueLens
+
+__version__ = "0.1.0"
+
+__all__ = ["QueueLens"]

queuelens/client.py

@@ -0,0 +1,91 @@
+
+import logging
+from typing import Any, Self
+
+from queuelens.config import QueueLensConfig
+from queuelens.exceptions import QueueLensConfigurationError
+
+logger = logging.getLogger(__name__)
+
+
+class QueueLens:
+    """Public client for integrating QueueLens with Celery applications."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        endpoint: str | None = None,
+        batch_size: int | None = None,
+        flush_interval: float | None = None,
+        timeout: float | None = None,
+        buffer_capacity: int | None = None,
+        max_batches_per_cycle: int | None = None,
+        shutdown_timeout: float | None = None,
+    ) -> None:
+        try:
+            self._config = QueueLensConfig.from_env(
+                api_key=api_key,
+                endpoint=endpoint,
+                batch_size=batch_size,
+                flush_interval=flush_interval,
+                timeout=timeout,
+                buffer_capacity=buffer_capacity,
+                max_batches_per_cycle=max_batches_per_cycle,
+                shutdown_timeout=shutdown_timeout,
+            )
+        except (TypeError, ValueError) as exc:
+            raise QueueLensConfigurationError(str(exc)) from exc
+
+        self._integrations: dict[int, Any] = {}
+        self._closed = False
+
+    def instrument(self, celery_app: Any) -> Any:
+        """Instrument a Celery application with QueueLens."""
+
+        if self._closed:
+            raise RuntimeError(
+                "QueueLens client is closed and cannot instrument applications"
+            )
+
+        from queuelens.instrumentation.celery import CeleryInstrumentation
+
+        app_id = id(celery_app)
+
+        if app_id in self._integrations:
+            return self._integrations[app_id]
+
+        integration = CeleryInstrumentation(self._config)
+        integration.instrument(celery_app)
+
+        self._integrations[app_id] = integration
+
+        logger.info("QueueLens instrumented Celery application")
+
+        return integration
+
+    def close(self) -> None:
+        """Close all registered integrations."""
+
+        self._closed = True
+
+        for app_id, integration in list(self._integrations.items()):
+            try:
+                integration.close()
+            except Exception:
+                logger.exception(
+                    "QueueLens failed to close an integration for app %s",
+                    app_id,
+                )
+            else:
+                self._integrations.pop(app_id, None)
+
+        logger.info("QueueLens client shutdown completed")
+
+    def __enter__(self) -> Self:
+        if self._closed:
+            raise RuntimeError("QueueLens client is already closed")
+
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()

queuelens/config.py

@@ -0,0 +1,100 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class QueueLensConfig:
+    api_key: str
+    endpoint: str
+    batch_size: int = 100
+    flush_interval: float = 5.0
+    timeout: float = 5.0
+    buffer_capacity: int = 1000
+    max_batches_per_cycle: int = 10
+    shutdown_timeout: float = 10.0
+
+    def __post_init__(self) -> None:
+        if not self.api_key.strip():
+            raise ValueError("API key cannot be empty")
+
+        if not self.endpoint.strip():
+            raise ValueError("Endpoint cannot be empty")
+
+        if self.batch_size < 1:
+            raise ValueError("batch_size must be at least 1")
+
+        if self.flush_interval <= 0:
+            raise ValueError("flush_interval must be greater than 0")
+
+        if self.timeout <= 0:
+            raise ValueError("timeout must be greater than 0")
+
+        if self.buffer_capacity < 1:
+            raise ValueError("buffer_capacity must be at least 1")
+
+        if self.max_batches_per_cycle < 1:
+            raise ValueError("max_batches_per_cycle must be at least 1")
+
+        if self.shutdown_timeout <= 0:
+            raise ValueError("shutdown_timeout must be greater than 0")
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        api_key: str | None = None,
+        endpoint: str | None = None,
+        batch_size: int | None = None,
+        flush_interval: float | None = None,
+        timeout: float | None = None,
+        buffer_capacity: int | None = None,
+        max_batches_per_cycle: int | None = None,
+        shutdown_timeout: float | None = None,
+    ) -> "QueueLensConfig":
+        resolved_api_key = (
+            api_key if api_key is not None else os.getenv("QUEUELENS_API_KEY")
+        )
+        resolved_endpoint = (
+            endpoint if endpoint is not None else os.getenv("QUEUELENS_ENDPOINT")
+        )
+
+        if resolved_api_key is None:
+            raise ValueError("QUEUELENS_API_KEY is required")
+
+        if resolved_endpoint is None:
+            raise ValueError("QUEUELENS_ENDPOINT is required")
+
+        return cls(
+            api_key=resolved_api_key,
+            endpoint=resolved_endpoint,
+            batch_size=(
+                batch_size
+                if batch_size is not None
+                else int(os.getenv("QUEUELENS_BATCH_SIZE", "100"))
+            ),
+            flush_interval=(
+                flush_interval
+                if flush_interval is not None
+                else float(os.getenv("QUEUELENS_FLUSH_INTERVAL", "5"))
+            ),
+            timeout=(
+                timeout
+                if timeout is not None
+                else float(os.getenv("QUEUELENS_TIMEOUT", "5"))
+            ),
+            buffer_capacity=(
+                buffer_capacity
+                if buffer_capacity is not None
+                else int(os.getenv("QUEUELENS_BUFFER_CAPACITY", "1000"))
+            ),
+            max_batches_per_cycle=(
+                max_batches_per_cycle
+                if max_batches_per_cycle is not None
+                else int(os.getenv("QUEUELENS_MAX_BATCHES_PER_CYCLE", "10"))
+            ),
+            shutdown_timeout=(
+                shutdown_timeout
+                if shutdown_timeout is not None
+                else float(os.getenv("QUEUELENS_SHUTDOWN_TIMEOUT", "10"))
+            ),
+        )

queuelens/events.py

@@ -0,0 +1,46 @@
+import uuid
+from datetime import UTC, datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class JobEventType(StrEnum):
+    RECEIVED = "received"
+    STARTED = "started"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    RETRIED = "retried"
+
+
+class JobEvent(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    event_id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    task_id: str = Field(min_length=1)
+    task_name: str = Field(min_length=1)
+    event_type: JobEventType
+    occurred_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    worker_name: str | None = None
+    queue_name: str | None = None
+    attempt: int = Field(default=1, ge=1)
+
+    exchange: str | None = Field(default=None, max_length=255)
+    routing_key: str | None = Field(default=None, max_length=255)
+
+    exception_type: str | None = Field(default=None, max_length=255)
+    exception_message: str | None = Field(default=None, max_length=4096)
+    traceback: str | None = Field(default=None, max_length=16000)
+
+    @field_validator("occurred_at")
+    @classmethod
+    def require_timezone(cls, value: datetime) -> datetime:
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError("occurred_at must include timezone information")
+        return value
+
+
+class IngestionResponse(BaseModel):
+    accepted_count: int = Field(ge=0)
+    duplicate_count: int = Field(ge=0)

queuelens/exceptions.py

@@ -0,0 +1,6 @@
+class QueueLensError(Exception):
+    """Base exception for the QueueLens SDK."""
+
+
+class QueueLensConfigurationError(QueueLensError):
+    """Raised when SDK configuration is invalid."""

queuelens/instrumentation/__init__.py

@@ -0,0 +1,3 @@
+from queuelens.instrumentation.celery import CeleryInstrumentation
+
+__all__ = ["CeleryInstrumentation"]