logiq-sdk 1.0.0__tar.gz

logiq_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: logiq-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the LogIQ AI Observability Platform
+License: MIT
+Keywords: monitoring,observability,logging,apm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: asgi
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+
+# logiq
+
+Official Python SDK for the [LogIQ](https://logiq.thetechvoyager.in) AI observability platform. Batches structured log/error events on a background thread and ships them to your LogIQ project over HTTP.
+
+## Install
+
+```bash
+pip install logiq-sdk
+```
+
+## Quick start
+
+```python
+from logiq import Monitor
+
+monitor = Monitor(
+    api_key="<YOUR_API_KEY>",
+    base_url="https://your-logiq-backend.example.com",
+    service_name="checkout-service",
+)
+
+monitor.info("Order placed", operation="create_order", metadata={"order_id": 123})
+
+try:
+    ...
+except Exception as exc:
+    monitor.capture_exception(exc, operation="create_order")
+```
+
+Only `WARN` and above are sent by default — pass `min_level="INFO"` (or `"DEBUG"`) to `Monitor(...)` to lower the threshold.
+
+## ASGI / Flask middleware
+
+```python
+from logiq import MonitorASGIMiddleware, attach_flask_middleware
+
+# FastAPI / Starlette
+app.add_middleware(MonitorASGIMiddleware, monitor=monitor)
+
+# Flask
+attach_flask_middleware(app, monitor)
+```
+
+## Correlation IDs
+
+```python
+from logiq import set_correlation_id, reset_correlation_id, get_correlation_id
+
+token = set_correlation_id("req-123")
+try:
+    ...
+finally:
+    reset_correlation_id(token)
+```
+
+## Heartbeats
+
+```python
+monitor.heartbeat()               # one-off
+monitor.start_heartbeat_loop(30)  # periodic, every 30s, stops on monitor.close()
+```
+
+## License
+
+MIT

logiq_sdk-1.0.0/README.md

@@ -0,0 +1,65 @@
+# logiq
+
+Official Python SDK for the [LogIQ](https://logiq.thetechvoyager.in) AI observability platform. Batches structured log/error events on a background thread and ships them to your LogIQ project over HTTP.
+
+## Install
+
+```bash
+pip install logiq-sdk
+```
+
+## Quick start
+
+```python
+from logiq import Monitor
+
+monitor = Monitor(
+    api_key="<YOUR_API_KEY>",
+    base_url="https://your-logiq-backend.example.com",
+    service_name="checkout-service",
+)
+
+monitor.info("Order placed", operation="create_order", metadata={"order_id": 123})
+
+try:
+    ...
+except Exception as exc:
+    monitor.capture_exception(exc, operation="create_order")
+```
+
+Only `WARN` and above are sent by default — pass `min_level="INFO"` (or `"DEBUG"`) to `Monitor(...)` to lower the threshold.
+
+## ASGI / Flask middleware
+
+```python
+from logiq import MonitorASGIMiddleware, attach_flask_middleware
+
+# FastAPI / Starlette
+app.add_middleware(MonitorASGIMiddleware, monitor=monitor)
+
+# Flask
+attach_flask_middleware(app, monitor)
+```
+
+## Correlation IDs
+
+```python
+from logiq import set_correlation_id, reset_correlation_id, get_correlation_id
+
+token = set_correlation_id("req-123")
+try:
+    ...
+finally:
+    reset_correlation_id(token)
+```
+
+## Heartbeats
+
+```python
+monitor.heartbeat()               # one-off
+monitor.start_heartbeat_loop(30)  # periodic, every 30s, stops on monitor.close()
+```
+
+## License
+
+MIT

logiq_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "logiq-sdk"
+version = "1.0.0"
+description = "Official Python SDK for the LogIQ AI Observability Platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["monitoring", "observability", "logging", "apm"]
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+asgi = []         # MonitorASGIMiddleware ships in the package; no extra deps needed
+flask = ["flask>=2.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

logiq_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

logiq_sdk-1.0.0/src/logiq/__init__.py

@@ -0,0 +1,12 @@
+from logiq.client import Monitor
+from logiq.context import get_correlation_id, reset_correlation_id, set_correlation_id
+from logiq.middleware import MonitorASGIMiddleware, attach_flask_middleware
+
+__all__ = [
+    "Monitor",
+    "MonitorASGIMiddleware",
+    "attach_flask_middleware",
+    "set_correlation_id",
+    "get_correlation_id",
+    "reset_correlation_id",
+]

logiq_sdk-1.0.0/src/logiq/client.py

@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+import atexit
+import threading
+import time
+import traceback
+import uuid
+from dataclasses import dataclass
+from typing import Any, Optional
+
+import requests
+
+from logiq.context import get_correlation_id
+
+
+_LEVEL_PRIORITY: dict[str, int] = {
+    "DEBUG": 0,
+    "INFO": 1,
+    "WARN": 2,
+    "WARNING": 2,
+    "ERROR": 3,
+    "CRITICAL": 4,
+}
+
+
+@dataclass
+class _MonitorConfig:
+    api_key: str
+    base_url: str
+    service_name: str | None
+    source: str
+    batch_size: int
+    flush_interval: float
+    timeout_seconds: float
+    max_retries: int
+    retry_backoff_seconds: float
+    min_level: str
+
+
+class Monitor:
+    """Client SDK for LogIQ log ingestion.
+
+    Features:
+    - non-blocking batching on background thread
+    - retry with exponential backoff
+    - request context propagation through correlation IDs
+    - exception capture helpers
+    - min_level filter: events below the threshold are silently dropped
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        service_name: str | None = None,
+        source: str = "sdk",
+        batch_size: int = 50,
+        flush_interval: float = 2.0,
+        timeout_seconds: float = 5.0,
+        max_retries: int = 3,
+        retry_backoff_seconds: float = 0.5,
+        min_level: str = "WARN",
+        session: Optional[requests.Session] = None,
+        start_background: bool = True,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        if not base_url:
+            raise ValueError("base_url is required")
+        if batch_size < 1:
+            raise ValueError("batch_size must be >= 1")
+        if flush_interval <= 0:
+            raise ValueError("flush_interval must be > 0")
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+        if min_level.upper() not in _LEVEL_PRIORITY:
+            raise ValueError(f"min_level must be one of {list(_LEVEL_PRIORITY)}")
+
+        self._cfg = _MonitorConfig(
+            api_key=api_key,
+            base_url=base_url.rstrip("/"),
+            service_name=service_name,
+            source=source,
+            batch_size=batch_size,
+            flush_interval=flush_interval,
+            timeout_seconds=timeout_seconds,
+            max_retries=max_retries,
+            retry_backoff_seconds=retry_backoff_seconds,
+            min_level=min_level.upper(),
+        )
+
+        self._session = session or requests.Session()
+        self._lock = threading.Lock()
+        self._buffer: list[dict[str, Any]] = []
+        self._dead_letter: list[dict[str, Any]] = []
+        self._stop_event = threading.Event()
+        self._flush_thread: threading.Thread | None = None
+
+        if start_background:
+            self.start()
+        atexit.register(self.close)
+
+    def start(self) -> None:
+        if self._flush_thread and self._flush_thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._flush_thread = threading.Thread(
+            target=self._flush_loop, name="logiq-flush", daemon=True
+        )
+        self._flush_thread.start()
+
+    def start_heartbeat_loop(self, interval: float = 30.0) -> None:
+        """Send a periodic heartbeat every *interval* seconds so the service
+        stays visible in the Servers dashboard while it is running.
+        Stops automatically when the Monitor is closed.
+        """
+        def _loop() -> None:
+            while not self._stop_event.is_set():
+                self._stop_event.wait(interval)
+                if not self._stop_event.is_set():
+                    self.heartbeat()
+
+        t = threading.Thread(target=_loop, name="logiq-heartbeat", daemon=True)
+        t.start()
+
+    def close(self) -> None:
+        self._stop_event.set()
+        if self._flush_thread and self._flush_thread.is_alive():
+            self._flush_thread.join(timeout=2.0)
+        self.flush()
+
+    def dead_letter(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return list(self._dead_letter)
+
+    def log(
+        self,
+        message: str,
+        *,
+        level: str = "INFO",
+        operation: str | None = None,
+        status: str | None = None,
+        error_type: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        correlation_id: str | None = None,
+        service_name: str | None = None,
+        source: str | None = None,
+    ) -> None:
+        if not message:
+            return
+        if _LEVEL_PRIORITY.get(level.upper(), 1) < _LEVEL_PRIORITY[self._cfg.min_level]:
+            return
+
+        resolved_correlation = correlation_id or get_correlation_id()
+        payload = {
+            "service_name": service_name or self._cfg.service_name,
+            "operation": operation,
+            "level": level.upper(),
+            "status": status,
+            "message": message,
+            "error_type": error_type,
+            "correlation_id": resolved_correlation,
+            "metadata": metadata,
+            "source": source or self._cfg.source,
+        }
+
+        with self._lock:
+            self._buffer.append(payload)
+            should_flush = len(self._buffer) >= self._cfg.batch_size
+
+        if should_flush:
+            self.flush()
+
+    def heartbeat(self, service_name: str | None = None) -> None:
+        """Register this service with the monitor immediately, bypassing min_level.
+
+        Useful at startup so the service appears in the Servers dashboard even
+        before any real errors occur.
+        """
+        resolved = service_name or self._cfg.service_name
+        payload = {
+            "service_name": resolved,
+            "level": "INFO",
+            "message": f"Service '{resolved}' started",
+            "source": self._cfg.source,
+            "operation": "startup",
+            "status": "started",
+            "error_type": None,
+            "correlation_id": None,
+            "metadata": None,
+        }
+        with self._lock:
+            self._buffer.append(payload)
+
+    def info(self, message: str, **kwargs: Any) -> None:
+        self.log(message, level="INFO", **kwargs)
+
+    def warn(self, message: str, **kwargs: Any) -> None:
+        self.log(message, level="WARN", **kwargs)
+
+    def error(self, message: str, **kwargs: Any) -> None:
+        self.log(message, level="ERROR", **kwargs)
+
+    def debug(self, message: str, **kwargs: Any) -> None:
+        self.log(message, level="DEBUG", **kwargs)
+
+    def capture_exception(
+        self,
+        exc: BaseException,
+        *,
+        operation: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        correlation_id: str | None = None,
+    ) -> None:
+        exc_type = type(exc).__name__
+        detail = "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+        merged_metadata = dict(metadata or {})
+        merged_metadata.setdefault("traceback", detail)
+
+        self.log(
+            message=str(exc) or exc_type,
+            level="ERROR",
+            operation=operation,
+            status="error",
+            error_type=exc_type,
+            metadata=merged_metadata,
+            correlation_id=correlation_id,
+        )
+
+    def trace(self, operation: str, *, metadata: dict[str, Any] | None = None):
+        return _TraceContext(self, operation=operation, metadata=metadata)
+
+    def install_excepthook(self) -> None:
+        import sys
+
+        previous_hook = sys.excepthook
+
+        def _hook(exc_type: type[BaseException], exc: BaseException, tb: Any) -> None:
+            self.capture_exception(exc, operation="unhandled_exception")
+            self.flush()
+            previous_hook(exc_type, exc, tb)
+
+        sys.excepthook = _hook
+
+    def flush(self) -> None:
+        while True:
+            batch = self._drain_batch(self._cfg.batch_size)
+            if not batch:
+                return
+            success = self._send_batch(batch)
+            if not success:
+                with self._lock:
+                    self._dead_letter.extend(batch)
+
+    def _flush_loop(self) -> None:
+        while not self._stop_event.is_set():
+            self._stop_event.wait(self._cfg.flush_interval)
+            if self._stop_event.is_set():
+                break
+            self.flush()
+
+    def _drain_batch(self, n: int) -> list[dict[str, Any]]:
+        with self._lock:
+            if not self._buffer:
+                return []
+            batch = self._buffer[:n]
+            self._buffer = self._buffer[n:]
+            return batch
+
+    def _send_batch(self, batch: list[dict[str, Any]]) -> bool:
+        url = f"{self._cfg.base_url}/api/v1/logs"
+        attempt = 0
+        while attempt <= self._cfg.max_retries:
+            attempt += 1
+            try:
+                resp = self._session.post(
+                    url,
+                    json={"logs": batch},
+                    headers={
+                        "Content-Type": "application/json",
+                        "X-API-Key": self._cfg.api_key,
+                        "Idempotency-Key": str(uuid.uuid4()),
+                    },
+                    timeout=self._cfg.timeout_seconds,
+                )
+                if 200 <= resp.status_code < 300:
+                    return True
+            except requests.RequestException:
+                pass
+
+            if attempt <= self._cfg.max_retries:
+                time.sleep(self._cfg.retry_backoff_seconds * (2 ** (attempt - 1)))
+
+        return False
+
+
+class _TraceContext:
+    def __init__(self, monitor: Monitor, *, operation: str, metadata: dict[str, Any] | None):
+        self._monitor = monitor
+        self._operation = operation
+        self._metadata = metadata or {}
+        self._start = 0.0
+
+    def __enter__(self):
+        self._start = time.perf_counter()
+        self._monitor.debug(
+            message=f"{self._operation} started",
+            operation=self._operation,
+            metadata=self._metadata,
+            status="start",
+        )
+        return self
+
+    def __exit__(self, exc_type, exc, _tb):
+        duration_ms = int((time.perf_counter() - self._start) * 1000)
+        metadata = dict(self._metadata)
+        metadata["duration_ms"] = duration_ms
+
+        if exc is None:
+            self._monitor.info(
+                message=f"{self._operation} completed",
+                operation=self._operation,
+                status="ok",
+                metadata=metadata,
+            )
+            return False
+
+        self._monitor.capture_exception(
+            exc,
+            operation=self._operation,
+            metadata=metadata,
+        )
+        return False

logiq_sdk-1.0.0/src/logiq/context.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import contextvars
+
+_correlation_id_var: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "logiq_correlation_id", default=None
+)
+
+
+def set_correlation_id(correlation_id: str | None) -> contextvars.Token:
+    return _correlation_id_var.set(correlation_id)
+
+
+def reset_correlation_id(token: contextvars.Token) -> None:
+    _correlation_id_var.reset(token)
+
+
+def get_correlation_id() -> str | None:
+    return _correlation_id_var.get()

logiq_sdk-1.0.0/src/logiq/middleware.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import time
+import uuid
+from typing import Any, Callable
+
+from logiq.context import reset_correlation_id, set_correlation_id
+
+
+class MonitorASGIMiddleware:
+    """ASGI middleware that propagates correlation IDs and logs request lifecycle."""
+
+    def __init__(self, app: Callable[..., Any], monitor: Any):
+        self.app = app
+        self.monitor = monitor
+
+    async def __call__(self, scope: dict[str, Any], receive: Callable[..., Any], send: Callable[..., Any]) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        headers = {
+            k.decode("latin-1").lower(): v.decode("latin-1")
+            for k, v in scope.get("headers", [])
+        }
+        correlation_id = (
+            headers.get("x-request-id")
+            or headers.get("x-correlation-id")
+            or str(uuid.uuid4())
+        )
+        token = set_correlation_id(correlation_id)
+
+        method = scope.get("method", "UNKNOWN")
+        path = scope.get("path", "/")
+        started = time.perf_counter()
+        status_code = 500
+
+        async def wrapped_send(message: dict[str, Any]) -> None:
+            nonlocal status_code
+            if message.get("type") == "http.response.start":
+                status_code = int(message.get("status", 500))
+            await send(message)
+
+        try:
+            await self.app(scope, receive, wrapped_send)
+            self.monitor.log(
+                message=f"{method} {path}",
+                level="INFO" if status_code < 500 else "ERROR",
+                operation="http_request",
+                status=str(status_code),
+                metadata={
+                    "method": method,
+                    "path": path,
+                    "duration_ms": int((time.perf_counter() - started) * 1000),
+                },
+                correlation_id=correlation_id,
+            )
+        except Exception as exc:
+            self.monitor.capture_exception(
+                exc,
+                operation="http_request",
+                metadata={"method": method, "path": path},
+                correlation_id=correlation_id,
+            )
+            raise
+        finally:
+            reset_correlation_id(token)
+
+
+def attach_flask_middleware(app: Any, monitor: Any) -> None:
+    """Attach request logging middleware to a Flask app."""
+
+    try:
+        from flask import g, request
+    except Exception as exc:
+        raise RuntimeError("Flask is not installed. Install flask to use Flask middleware.") from exc
+
+    @app.before_request
+    def _before_request() -> None:
+        correlation_id = (
+            request.headers.get("X-Request-ID")
+            or request.headers.get("X-Correlation-ID")
+            or str(uuid.uuid4())
+        )
+        g._monitor_started = time.perf_counter()
+        g._monitor_token = set_correlation_id(correlation_id)
+        g._monitor_correlation_id = correlation_id
+
+    @app.after_request
+    def _after_request(response: Any) -> Any:
+        started = getattr(g, "_monitor_started", time.perf_counter())
+        correlation_id = getattr(g, "_monitor_correlation_id", None)
+        monitor.log(
+            message=f"{request.method} {request.path}",
+            level="INFO" if response.status_code < 500 else "ERROR",
+            operation="http_request",
+            status=str(response.status_code),
+            metadata={
+                "method": request.method,
+                "path": request.path,
+                "duration_ms": int((time.perf_counter() - started) * 1000),
+            },
+            correlation_id=correlation_id,
+        )
+        token = getattr(g, "_monitor_token", None)
+        if token is not None:
+            reset_correlation_id(token)
+        return response

logiq_sdk-1.0.0/src/logiq_sdk.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: logiq-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the LogIQ AI Observability Platform
+License: MIT
+Keywords: monitoring,observability,logging,apm
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: asgi
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == "flask"
+
+# logiq
+
+Official Python SDK for the [LogIQ](https://logiq.thetechvoyager.in) AI observability platform. Batches structured log/error events on a background thread and ships them to your LogIQ project over HTTP.
+
+## Install
+
+```bash
+pip install logiq-sdk
+```
+
+## Quick start
+
+```python
+from logiq import Monitor
+
+monitor = Monitor(
+    api_key="<YOUR_API_KEY>",
+    base_url="https://your-logiq-backend.example.com",
+    service_name="checkout-service",
+)
+
+monitor.info("Order placed", operation="create_order", metadata={"order_id": 123})
+
+try:
+    ...
+except Exception as exc:
+    monitor.capture_exception(exc, operation="create_order")
+```
+
+Only `WARN` and above are sent by default — pass `min_level="INFO"` (or `"DEBUG"`) to `Monitor(...)` to lower the threshold.
+
+## ASGI / Flask middleware
+
+```python
+from logiq import MonitorASGIMiddleware, attach_flask_middleware
+
+# FastAPI / Starlette
+app.add_middleware(MonitorASGIMiddleware, monitor=monitor)
+
+# Flask
+attach_flask_middleware(app, monitor)
+```
+
+## Correlation IDs
+
+```python
+from logiq import set_correlation_id, reset_correlation_id, get_correlation_id
+
+token = set_correlation_id("req-123")
+try:
+    ...
+finally:
+    reset_correlation_id(token)
+```
+
+## Heartbeats
+
+```python
+monitor.heartbeat()               # one-off
+monitor.start_heartbeat_loop(30)  # periodic, every 30s, stops on monitor.close()
+```
+
+## License
+
+MIT

logiq_sdk-1.0.0/src/logiq_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/logiq/__init__.py
+src/logiq/client.py
+src/logiq/context.py
+src/logiq/middleware.py
+src/logiq_sdk.egg-info/PKG-INFO
+src/logiq_sdk.egg-info/SOURCES.txt
+src/logiq_sdk.egg-info/dependency_links.txt
+src/logiq_sdk.egg-info/requires.txt
+src/logiq_sdk.egg-info/top_level.txt

logiq_sdk-1.0.0/src/logiq_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

logiq_sdk-1.0.0/src/logiq_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+requests>=2.28
+
+[asgi]
+
+[flask]
+flask>=2.0

logiq_sdk-1.0.0/src/logiq_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+logiq