heimdall-sdk 0.1.0__tar.gz

heimdall_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: heimdall-sdk
+Version: 0.1.0
+Summary: Python SDK for Heimdall observability platform
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.95; extra == "fastapi"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: respx>=0.20; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: fastapi>=0.95; extra == "dev"
+Requires-Dist: httpx>=0.24; extra == "dev"
+
+# Heimdall Python SDK
+
+Synchronous, fail-safe Python client for the [Heimdall](https://heimdall-ob.com) ingest API. Send telemetry events, errors, and performance metrics from any Python application.
+
+## Installation
+
+```bash
+pip install heimdall-sdk
+```
+
+With FastAPI middleware support:
+
+```bash
+pip install heimdall-sdk[fastapi]
+```
+
+## Quick Start
+
+```python
+from heimdall import HeimdallClient
+
+client = HeimdallClient(
+    api_key="your-api-key",
+    service_name="payments-api",
+    environment="production",
+)
+
+# Send telemetry events
+client.success("payment_processed", metadata={"amount": 150, "currency": "USD"})
+client.error("payment_failed", metadata={"reason": "insufficient_funds"})
+client.warning("retry_attempt", metadata={"attempt": 2})
+client.info("user_login", tags={"region": "us-east"})
+client.timeout("external_api_call")
+client.canceled("bulk_import")
+```
+
+## Error Capture
+
+```python
+try:
+    process_payment(order)
+except Exception as exc:
+    client.capture_exception(exc, endpoint="/checkout")
+    # exc is NOT re-raised by the SDK
+```
+
+Manual error reporting:
+
+```python
+client.send_error(
+    "PaymentGatewayError",
+    "Gateway returned 503",
+    endpoint="/api/payments",
+    stacktrace=traceback.format_exc(),
+)
+```
+
+## Performance Tracking
+
+Direct call:
+
+```python
+client.send_performance(
+    "db_query",
+    target_type="database",
+    target_name="users",
+    duration_ms=45,
+)
+```
+
+Decorator (automatically measures duration):
+
+```python
+@client.track("transfer", target_type="function", include_exceptions=True)
+def process_transfer(amount: float) -> dict:
+    ...
+```
+
+Context manager:
+
+```python
+with client.timing("bank_sync", target_type="job", target_name="nightly_sync"):
+    sync_with_bank()
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from heimdall import HeimdallClient
+from heimdall.integrations.fastapi import setup_heimdall
+
+app = FastAPI()
+client = HeimdallClient(api_key="your-api-key", service_name="my-api")
+
+setup_heimdall(app, client)
+```
+
+Every HTTP request automatically gets a `request_duration` performance metric using the route path template (e.g. `GET /users/{user_id}`).
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Heimdall API key |
+| `base_url` | `str` | `https://heimdall-ob.com/api/v1` | Override for local development |
+| `enabled` | `bool` | `True` | Set `False` to disable all network calls |
+| `raise_on_error` | `bool` | `False` | Raise `HeimdallTransportError` on failures |
+| `timeout` | `float` | `5.0` | HTTP request timeout in seconds |
+| `service_name` | `str` | `None` | Injected into every event's tags |
+| `environment` | `str` | `None` | Injected into every event's tags |
+| `default_metadata` | `dict` | `None` | Merged into every event's metadata |
+| `default_tags` | `dict` | `None` | Merged into every event's tags |
+
+## Fail-Safe by Default
+
+All send methods return `True` on success and `False` on any failure — the SDK never raises into your application unless `raise_on_error=True`.
+
+```python
+result = client.success("order_placed")
+if not result:
+    logger.warning("Heimdall telemetry unavailable")
+```
+
+## Development
+
+```bash
+git clone <repo>
+cd heimdall-sdk
+pip install -e ".[dev]"
+pytest
+```
+
+For more examples see [`specs/001-heimdall-python-sdk/quickstart.md`](specs/001-heimdall-python-sdk/quickstart.md).

heimdall_sdk-0.1.0/README.md

@@ -0,0 +1,134 @@
+# Heimdall Python SDK
+
+Synchronous, fail-safe Python client for the [Heimdall](https://heimdall-ob.com) ingest API. Send telemetry events, errors, and performance metrics from any Python application.
+
+## Installation
+
+```bash
+pip install heimdall-sdk
+```
+
+With FastAPI middleware support:
+
+```bash
+pip install heimdall-sdk[fastapi]
+```
+
+## Quick Start
+
+```python
+from heimdall import HeimdallClient
+
+client = HeimdallClient(
+    api_key="your-api-key",
+    service_name="payments-api",
+    environment="production",
+)
+
+# Send telemetry events
+client.success("payment_processed", metadata={"amount": 150, "currency": "USD"})
+client.error("payment_failed", metadata={"reason": "insufficient_funds"})
+client.warning("retry_attempt", metadata={"attempt": 2})
+client.info("user_login", tags={"region": "us-east"})
+client.timeout("external_api_call")
+client.canceled("bulk_import")
+```
+
+## Error Capture
+
+```python
+try:
+    process_payment(order)
+except Exception as exc:
+    client.capture_exception(exc, endpoint="/checkout")
+    # exc is NOT re-raised by the SDK
+```
+
+Manual error reporting:
+
+```python
+client.send_error(
+    "PaymentGatewayError",
+    "Gateway returned 503",
+    endpoint="/api/payments",
+    stacktrace=traceback.format_exc(),
+)
+```
+
+## Performance Tracking
+
+Direct call:
+
+```python
+client.send_performance(
+    "db_query",
+    target_type="database",
+    target_name="users",
+    duration_ms=45,
+)
+```
+
+Decorator (automatically measures duration):
+
+```python
+@client.track("transfer", target_type="function", include_exceptions=True)
+def process_transfer(amount: float) -> dict:
+    ...
+```
+
+Context manager:
+
+```python
+with client.timing("bank_sync", target_type="job", target_name="nightly_sync"):
+    sync_with_bank()
+```
+
+## FastAPI Integration
+
+```python
+from fastapi import FastAPI
+from heimdall import HeimdallClient
+from heimdall.integrations.fastapi import setup_heimdall
+
+app = FastAPI()
+client = HeimdallClient(api_key="your-api-key", service_name="my-api")
+
+setup_heimdall(app, client)
+```
+
+Every HTTP request automatically gets a `request_duration` performance metric using the route path template (e.g. `GET /users/{user_id}`).
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_key` | `str` | required | Heimdall API key |
+| `base_url` | `str` | `https://heimdall-ob.com/api/v1` | Override for local development |
+| `enabled` | `bool` | `True` | Set `False` to disable all network calls |
+| `raise_on_error` | `bool` | `False` | Raise `HeimdallTransportError` on failures |
+| `timeout` | `float` | `5.0` | HTTP request timeout in seconds |
+| `service_name` | `str` | `None` | Injected into every event's tags |
+| `environment` | `str` | `None` | Injected into every event's tags |
+| `default_metadata` | `dict` | `None` | Merged into every event's metadata |
+| `default_tags` | `dict` | `None` | Merged into every event's tags |
+
+## Fail-Safe by Default
+
+All send methods return `True` on success and `False` on any failure — the SDK never raises into your application unless `raise_on_error=True`.
+
+```python
+result = client.success("order_placed")
+if not result:
+    logger.warning("Heimdall telemetry unavailable")
+```
+
+## Development
+
+```bash
+git clone <repo>
+cd heimdall-sdk
+pip install -e ".[dev]"
+pytest
+```
+
+For more examples see [`specs/001-heimdall-python-sdk/quickstart.md`](specs/001-heimdall-python-sdk/quickstart.md).

heimdall_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "heimdall-sdk"
+version = "0.1.0"
+description = "Python SDK for Heimdall observability platform"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+fastapi = [
+    "fastapi>=0.95",
+]
+dev = [
+    "pytest>=7.0",
+    "respx>=0.20",
+    "ruff>=0.4",
+    "mypy>=1.0",
+    "fastapi>=0.95",
+    "httpx>=0.24",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["heimdall*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.mypy]
+strict = true
+warn_no_return = true
+warn_unreachable = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["F", "E", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]

heimdall_sdk-0.1.0/setup.cfg

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

heimdall_sdk-0.1.0/src/heimdall/__init__.py

@@ -0,0 +1,29 @@
+"""Heimdall Python SDK."""
+
+from heimdall._exceptions import (
+    HeimdallConfigError,
+    HeimdallError,
+    HeimdallTransportError,
+    HeimdallValidationError,
+)
+from heimdall.client import (
+    HeimdallClient,
+    _DEFAULT_BASE_URL as DEFAULT_BASE_URL,
+    _ENV_API_KEY as ENV_API_KEY,
+    _ENV_BASE_URL as ENV_BASE_URL,
+    _ENV_ENABLED as ENV_ENABLED,
+)
+
+__all__ = [
+    "HeimdallClient",
+    "HeimdallError",
+    "HeimdallConfigError",
+    "HeimdallTransportError",
+    "HeimdallValidationError",
+    "DEFAULT_BASE_URL",
+    "ENV_API_KEY",
+    "ENV_BASE_URL",
+    "ENV_ENABLED",
+]
+
+__version__ = "0.1.0"

heimdall_sdk-0.1.0/src/heimdall/_enums.py

@@ -0,0 +1,39 @@
+"""Internal enumerations for event status and level.
+
+These enums are NEVER part of the public API. Developers interact with
+them implicitly through the named methods on HeimdallClient.
+"""
+
+from enum import Enum
+
+
+class EventStatus(str, Enum):
+    """Allowed values for the event/error status field."""
+
+    SUCCESS = "success"
+    ERROR = "error"
+    WARNING = "warning"
+    INFO = "info"
+    TIMEOUT = "timeout"
+    CANCELED = "canceled"
+
+
+class EventLevel(str, Enum):
+    """Allowed values for the event/error/performance level field."""
+
+    DEBUG = "debug"
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+# Default level for each status method — determined by method called, not developer.
+STATUS_LEVEL_MAP: dict[EventStatus, EventLevel] = {
+    EventStatus.SUCCESS: EventLevel.INFO,
+    EventStatus.ERROR: EventLevel.ERROR,
+    EventStatus.WARNING: EventLevel.WARNING,
+    EventStatus.INFO: EventLevel.INFO,
+    EventStatus.TIMEOUT: EventLevel.WARNING,
+    EventStatus.CANCELED: EventLevel.INFO,
+}

heimdall_sdk-0.1.0/src/heimdall/_exceptions.py

@@ -0,0 +1,21 @@
+"""SDK-specific exception hierarchy."""
+
+
+class HeimdallError(Exception):
+    """Base exception for all Heimdall SDK errors."""
+
+
+class HeimdallConfigError(HeimdallError):
+    """Raised for invalid SDK configuration (e.g., empty api_key)."""
+
+
+class HeimdallTransportError(HeimdallError):
+    """Raised for HTTP transport failures when raise_on_error=True."""
+
+
+class HeimdallValidationError(HeimdallError):
+    """Raised for obviously invalid method arguments (empty names, negative duration, etc.).
+
+    Always raised regardless of raise_on_error setting because these are
+    programmer errors, not runtime conditions.
+    """

heimdall_sdk-0.1.0/src/heimdall/_formatter.py

@@ -0,0 +1,27 @@
+"""Exception formatter — extracts type, message, and stacktrace from Python exceptions."""
+
+import traceback
+from typing import Any
+
+
+class ExceptionFormatter:
+    """Formats Python exception objects into error payload dicts.
+
+    Never makes HTTP calls or calls the SDK client.
+    Only responsibility: extract structured data from exceptions.
+    """
+
+    @staticmethod
+    def format(exc: BaseException) -> dict[str, Any]:
+        """Extract error_type, message, and stacktrace from a Python exception.
+
+        Works correctly when called inside or outside an except block.
+        Handles chained exceptions gracefully.
+        """
+        return {
+            "error_type": exc.__class__.__name__,
+            "message": str(exc),
+            "stacktrace": "".join(
+                traceback.format_exception(type(exc), exc, exc.__traceback__)
+            ),
+        }