infrawatch-sdk 0.1.0__tar.gz

infrawatch_sdk-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Binaries
+bin/
+/dist/
+infrawatch-agent
+infrawatch-collector
+
+# OCB generated (regenerated by `make generate`)
+/cmd/agent/
+/cmd/collector/
+
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+go.work.sum
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# SDK build artifacts
+sdk/node/node_modules/
+sdk/node/dist/
+sdk/python/*.egg-info/
+sdk/python/.pytest_cache/
+__pycache__/

infrawatch_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: infrawatch-sdk
+Version: 0.1.0
+Summary: Python SDK for the InfraWatch observability platform
+Project-URL: Homepage, https://infrawatchlabs.com
+Project-URL: Documentation, https://docs.infrawatchlabs.com/sdk/python
+Author-email: InfraWatch Labs <support@infrawatchlabs.com>
+License-Expression: LicenseRef-Proprietary
+Keywords: infrawatch,logs,metrics,monitoring,observability,traces
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# InfraWatch Python SDK
+
+Python client library for the [InfraWatch](https://infrawatchlabs.com) observability platform.
+
+## Installation
+
+```bash
+pip install infrawatch-sdk
+```
+
+## Quick Start
+
+```python
+from infrawatch import InfraWatchClient
+
+client = InfraWatchClient(
+    base_url="https://infrawatch.example.com",     # Backend URL for queries
+    collector_url="https://collector.example.com",   # Collector URL for push
+    api_key="iw_sk_a3f8b2c1...",                    # API key for push auth
+    email="admin@example.com",                       # Backend login for queries
+    password="secret",                               # Backend login for queries
+)
+
+# Push traces (uses API key via X-InfraWatch-API-Key header)
+client.traces.push(spans=[
+    {
+        "name": "http.request",
+        "start_time": "2026-01-01T00:00:00Z",
+        "end_time": "2026-01-01T00:00:01Z",
+    }
+])
+
+# Push metrics
+client.metrics.push(metrics=[
+    {"name": "cpu.usage", "value": 72.5, "type": "gauge"}
+])
+
+# Push logs
+client.logs.push(logs=[
+    {"body": "Request processed successfully", "severity": "INFO"}
+])
+
+# Query traces (uses email/password session)
+traces = client.traces.search(service="api-gateway")
+
+# Health check
+status = client.health()
+```
+
+## Authentication
+
+The SDK uses two authentication mechanisms:
+
+- **Push (to collector):** API key via `X-InfraWatch-API-Key` header. Generate your API key in **Admin > Observability** in the InfraWatch UI.
+- **Query (from backend):** Email/password session cookies. The SDK handles login automatically on the first query.
+
+## License
+
+Proprietary. See LICENSE for details.

infrawatch_sdk-0.1.0/README.md

@@ -0,0 +1,59 @@
+# InfraWatch Python SDK
+
+Python client library for the [InfraWatch](https://infrawatchlabs.com) observability platform.
+
+## Installation
+
+```bash
+pip install infrawatch-sdk
+```
+
+## Quick Start
+
+```python
+from infrawatch import InfraWatchClient
+
+client = InfraWatchClient(
+    base_url="https://infrawatch.example.com",     # Backend URL for queries
+    collector_url="https://collector.example.com",   # Collector URL for push
+    api_key="iw_sk_a3f8b2c1...",                    # API key for push auth
+    email="admin@example.com",                       # Backend login for queries
+    password="secret",                               # Backend login for queries
+)
+
+# Push traces (uses API key via X-InfraWatch-API-Key header)
+client.traces.push(spans=[
+    {
+        "name": "http.request",
+        "start_time": "2026-01-01T00:00:00Z",
+        "end_time": "2026-01-01T00:00:01Z",
+    }
+])
+
+# Push metrics
+client.metrics.push(metrics=[
+    {"name": "cpu.usage", "value": 72.5, "type": "gauge"}
+])
+
+# Push logs
+client.logs.push(logs=[
+    {"body": "Request processed successfully", "severity": "INFO"}
+])
+
+# Query traces (uses email/password session)
+traces = client.traces.search(service="api-gateway")
+
+# Health check
+status = client.health()
+```
+
+## Authentication
+
+The SDK uses two authentication mechanisms:
+
+- **Push (to collector):** API key via `X-InfraWatch-API-Key` header. Generate your API key in **Admin > Observability** in the InfraWatch UI.
+- **Query (from backend):** Email/password session cookies. The SDK handles login automatically on the first query.
+
+## License
+
+Proprietary. See LICENSE for details.

infrawatch_sdk-0.1.0/infrawatch/__init__.py

@@ -0,0 +1,23 @@
+"""InfraWatch SDK -- Python client for the InfraWatch observability platform."""
+
+from infrawatch.client import InfraWatchClient
+from infrawatch.exceptions import (
+    InfraWatchError,
+    AuthenticationError,
+    ConnectionError,
+    APIError,
+    TimeoutError,
+    ValidationError,
+)
+from infrawatch.version import __version__
+
+__all__ = [
+    "InfraWatchClient",
+    "InfraWatchError",
+    "AuthenticationError",
+    "ConnectionError",
+    "APIError",
+    "TimeoutError",
+    "ValidationError",
+    "__version__",
+]

infrawatch_sdk-0.1.0/infrawatch/client.py

@@ -0,0 +1,305 @@
+"""Main InfraWatch client — two-layer architecture.
+
+Layer 1 (Push):  OTLP HTTP → Collector (API key auth via X-InfraWatch-API-Key)
+Layer 2 (Query): REST API  → Backend  (session cookie auth via email/password)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from infrawatch.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConnectionError,
+    TimeoutError,
+)
+from infrawatch.traces import TracesAPI
+from infrawatch.metrics import MetricsAPI
+from infrawatch.logs import LogsAPI
+from infrawatch.version import __version__
+
+
+_DEFAULT_TIMEOUT = 30
+
+
+class InfraWatchClient:
+    """Client for the InfraWatch observability platform.
+
+    Provides two communication layers:
+
+    * **Push** — send logs, metrics, and traces to the OTel Collector via
+      OTLP/HTTP (``collector_url``, authenticated with an API key via
+      the ``X-InfraWatch-API-Key`` header).
+    * **Query** — read back data from the InfraWatch backend REST API
+      (``base_url``, authenticated with email/password session cookies).
+
+    Args:
+        base_url: Backend URL for queries (e.g. ``https://infrawatch.example.com``).
+        collector_url: Collector URL for push (e.g. ``https://collector.example.com``).
+            Port 4318 is used for OTLP/HTTP.
+        api_key: API key for the collector (generated in Admin > Observability).
+            Sent as ``X-InfraWatch-API-Key`` header on push requests.
+        email: Email for backend login.
+        password: Password for backend login.
+        timeout: Request timeout in seconds.  Defaults to 30.
+
+    Example::
+
+        client = InfraWatchClient(
+            base_url="https://infrawatch.example.com",
+            collector_url="https://collector.example.com",
+            api_key="iw_sk_a3f8b2c1...",
+            email="admin@example.com",
+            password="secret",
+        )
+
+        # Push (OTLP to collector via API key)
+        client.logs.push([{"body": "msg", "severity": "INFO"}])
+
+        # Query (REST from backend via session)
+        logs = client.logs.search(q="error", severity="ERROR", limit=50)
+    """
+
+    def __init__(
+        self,
+        base_url: str = "",
+        collector_url: str = "",
+        api_key: str = "",
+        email: str = "",
+        password: str = "",
+        timeout: int = _DEFAULT_TIMEOUT,
+    ) -> None:
+        if not base_url and not collector_url:
+            raise ValueError("At least one of base_url or collector_url is required")
+
+        self.base_url = base_url.rstrip("/") if base_url else ""
+        self.collector_url = collector_url.rstrip("/") if collector_url else ""
+        self.api_key = api_key
+        self.email = email
+        self.password = password
+        self.timeout = timeout
+
+        # Collector HTTP client — used for OTLP push
+        collector_headers: dict[str, str] = {
+            "Content-Type": "application/json",
+            "User-Agent": f"infrawatch-python-sdk/{__version__}",
+        }
+        if api_key:
+            collector_headers["X-InfraWatch-API-Key"] = api_key
+
+        self._collector_http = httpx.Client(
+            headers=collector_headers,
+            timeout=self.timeout,
+        )
+
+        # Backend HTTP client — used for REST queries (session cookie auth)
+        self._backend_http = httpx.Client(
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": f"infrawatch-python-sdk/{__version__}",
+            },
+            timeout=self.timeout,
+        )
+        self._authenticated = False
+
+        # Sub-APIs
+        self.traces = TracesAPI(self)
+        self.metrics = MetricsAPI(self)
+        self.logs = LogsAPI(self)
+
+    # ------------------------------------------------------------------
+    # Push helpers (OTLP HTTP to collector)
+    # ------------------------------------------------------------------
+
+    def _push(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST an OTLP JSON payload to the collector.
+
+        Args:
+            path: OTLP endpoint path (e.g. ``/v1/logs``).
+            payload: OTLP JSON body.
+
+        Returns:
+            Parsed JSON response (usually empty ``{}`` on success).
+        """
+        if not self.collector_url:
+            raise ValueError("collector_url is required for push operations")
+
+        url = f"{self.collector_url}:4318{path}"
+        try:
+            response = self._collector_http.post(url, json=payload)
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Push request timed out: {exc}") from exc
+        except httpx.ConnectError as exc:
+            raise ConnectionError(
+                f"Failed to connect to collector at {url}: {exc}"
+            ) from exc
+
+        if response.status_code in (401, 403):
+            raise AuthenticationError(
+                f"Collector auth failed: {response.status_code}",
+                status_code=response.status_code,
+            )
+        if response.status_code >= 400:
+            body = response.json() if response.content else None
+            raise APIError(
+                f"Collector returned {response.status_code}",
+                status_code=response.status_code,
+                response=body,
+            )
+
+        if response.status_code == 200 and response.content:
+            return response.json()
+        return {}
+
+    # ------------------------------------------------------------------
+    # Query helpers (REST API to backend)
+    # ------------------------------------------------------------------
+
+    def _ensure_authenticated(self) -> None:
+        """Login to the backend if we haven't already."""
+        if self._authenticated:
+            return
+        if not self.base_url:
+            raise ValueError("base_url is required for query operations")
+        if not self.email or not self.password:
+            raise ValueError("email and password are required for query operations")
+
+        url = f"{self.base_url}/api/auth/login"
+        try:
+            response = self._backend_http.post(
+                url,
+                json={"email": self.email, "password": self.password},
+            )
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Login timed out: {exc}") from exc
+        except httpx.ConnectError as exc:
+            raise ConnectionError(
+                f"Failed to connect to backend at {url}: {exc}"
+            ) from exc
+
+        if response.status_code in (401, 403):
+            raise AuthenticationError(
+                "Backend login failed — invalid credentials",
+                status_code=response.status_code,
+            )
+        if response.status_code >= 400:
+            raise APIError(
+                f"Backend login returned {response.status_code}",
+                status_code=response.status_code,
+            )
+
+        self._authenticated = True
+
+    def _query(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> Any:
+        """Make an authenticated request to the backend REST API.
+
+        Args:
+            method: HTTP method.
+            path: API path (e.g. ``/api/logs/``).
+            params: Optional query parameters.
+
+        Returns:
+            Parsed JSON response.
+        """
+        self._ensure_authenticated()
+
+        url = f"{self.base_url}{path}"
+        # Strip None values from params
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+
+        try:
+            response = self._backend_http.request(method, url, params=params)
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Query timed out: {exc}") from exc
+        except httpx.ConnectError as exc:
+            raise ConnectionError(
+                f"Failed to connect to backend at {url}: {exc}"
+            ) from exc
+
+        if response.status_code in (401, 403):
+            # Session may have expired — try re-auth once
+            self._authenticated = False
+            self._ensure_authenticated()
+            try:
+                response = self._backend_http.request(method, url, params=params)
+            except httpx.TimeoutException as exc:
+                raise TimeoutError(f"Query timed out: {exc}") from exc
+
+            if response.status_code in (401, 403):
+                raise AuthenticationError(
+                    f"Backend auth failed: {response.status_code}",
+                    status_code=response.status_code,
+                )
+
+        if response.status_code >= 400:
+            body = response.json() if response.content else None
+            raise APIError(
+                f"Backend returned {response.status_code}",
+                status_code=response.status_code,
+                response=body,
+            )
+
+        if response.status_code == 204 or not response.content:
+            return {}
+
+        return response.json()
+
+    # ------------------------------------------------------------------
+    # Health
+    # ------------------------------------------------------------------
+
+    def health(self) -> dict[str, Any]:
+        """Check health of both the collector and backend.
+
+        Returns:
+            Dict with ``collector`` and ``backend`` health status.
+        """
+        result: dict[str, Any] = {}
+
+        if self.collector_url:
+            try:
+                resp = self._collector_http.get(
+                    f"{self.collector_url}:4318/v1/health"
+                )
+                result["collector"] = {
+                    "status": "ok" if resp.status_code < 400 else "error",
+                    "status_code": resp.status_code,
+                }
+            except Exception as exc:
+                result["collector"] = {"status": "error", "error": str(exc)}
+
+        if self.base_url:
+            try:
+                resp = self._backend_http.get(f"{self.base_url}/api/health")
+                result["backend"] = {
+                    "status": "ok" if resp.status_code < 400 else "error",
+                    "status_code": resp.status_code,
+                }
+            except Exception as exc:
+                result["backend"] = {"status": "error", "error": str(exc)}
+
+        return result
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP clients."""
+        self._collector_http.close()
+        self._backend_http.close()
+
+    def __enter__(self) -> InfraWatchClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

infrawatch_sdk-0.1.0/infrawatch/exceptions.py

@@ -0,0 +1,41 @@
+"""Custom exceptions for the InfraWatch SDK."""
+
+
+class InfraWatchError(Exception):
+    """Base exception for all InfraWatch SDK errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, response: dict | None = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+
+
+class AuthenticationError(InfraWatchError):
+    """Raised when API key is invalid or missing."""
+
+    pass
+
+
+class ConnectionError(InfraWatchError):
+    """Raised when the SDK cannot connect to the InfraWatch backend."""
+
+    pass
+
+
+class APIError(InfraWatchError):
+    """Raised when the API returns a non-success status code."""
+
+    pass
+
+
+class TimeoutError(InfraWatchError):
+    """Raised when a request exceeds the configured timeout."""
+
+    pass
+
+
+class ValidationError(InfraWatchError):
+    """Raised when input data fails validation before sending."""
+
+    pass

infrawatch_sdk-0.1.0/infrawatch/logs.py

@@ -0,0 +1,119 @@
+"""Logs API — push (OTLP) and query (REST) methods."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, TYPE_CHECKING
+
+from infrawatch.otlp import build_logs_payload
+
+if TYPE_CHECKING:
+    from infrawatch.client import InfraWatchClient
+
+
+class LogsAPI:
+    """Push and query log data.
+
+    Accessed via ``InfraWatchClient.logs``.
+    """
+
+    def __init__(self, client: InfraWatchClient) -> None:
+        self._client = client
+
+    # ------------------------------------------------------------------
+    # Push (OTLP HTTP → Collector)
+    # ------------------------------------------------------------------
+
+    def push(
+        self,
+        logs: list[dict[str, Any]],
+        resource_attributes: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Push log records to the collector via OTLP/HTTP.
+
+        Args:
+            logs: List of log dicts.  Each may contain:
+                ``body`` (str), ``severity`` (str), ``attributes`` (dict),
+                ``timestamp`` (str, nanosecond epoch).
+            resource_attributes: Optional resource-level attributes attached
+                to the OTLP resource.
+
+        Returns:
+            Collector response (usually empty on success).
+        """
+        payload = build_logs_payload(logs, resource_attributes)
+        return self._client._push("/v1/logs", payload)
+
+    # ------------------------------------------------------------------
+    # Query (REST API → Backend)
+    # ------------------------------------------------------------------
+
+    def search(
+        self,
+        *,
+        q: Optional[str] = None,
+        severity: Optional[str] = None,
+        service: Optional[str] = None,
+        namespace: Optional[str] = None,
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Any:
+        """Search logs.
+
+        All parameters are optional and act as filters.
+        """
+        return self._client._query("GET", "/api/logs/", params={
+            "q": q,
+            "severity": severity,
+            "service": service,
+            "namespace": namespace,
+            "start": start,
+            "end": end,
+            "limit": limit,
+            "cursor": cursor,
+        })
+
+    def histogram(
+        self,
+        *,
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+        service: Optional[str] = None,
+        severity: Optional[str] = None,
+        bucket: Optional[str] = None,
+    ) -> Any:
+        """Get log count histogram."""
+        return self._client._query("GET", "/api/logs/histogram", params={
+            "start": start,
+            "end": end,
+            "service": service,
+            "severity": severity,
+            "bucket": bucket,
+        })
+
+    def tail(
+        self,
+        *,
+        service: Optional[str] = None,
+        severity: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Any:
+        """Live-tail recent logs."""
+        return self._client._query("GET", "/api/logs/tail", params={
+            "service": service,
+            "severity": severity,
+            "limit": limit,
+        })
+
+    def services(self) -> Any:
+        """List services that emit logs."""
+        return self._client._query("GET", "/api/logs/services")
+
+    def namespaces(self) -> Any:
+        """List namespaces."""
+        return self._client._query("GET", "/api/logs/namespaces")
+
+    def clusters(self) -> Any:
+        """List clusters."""
+        return self._client._query("GET", "/api/logs/clusters")