honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/resources/slos.py

@@ -0,0 +1,353 @@
+"""SLOs resource for Honeycomb API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..models.burn_alerts import BurnAlertCreate, BurnAlertRecipient
+from ..models.slos import SLO, SLOCreate
+from .base import BaseResource
+
+if TYPE_CHECKING:
+    from ..client import HoneycombClient
+    from ..models.slo_builder import SLOBundle
+
+
+class SLOsResource(BaseResource):
+    """Resource for managing Honeycomb SLOs (Service Level Objectives).
+
+    SLOs allow you to define and track service level objectives
+    based on your data.
+
+    Example (async):
+        >>> async with HoneycombClient(api_key="...") as client:
+        ...     slos = await client.slos.list(dataset="my-dataset")
+        ...     slo = await client.slos.get(dataset="my-dataset", slo_id="abc123")
+
+    Example (sync):
+        >>> with HoneycombClient(api_key="...", sync=True) as client:
+        ...     slos = client.slos.list(dataset="my-dataset")
+    """
+
+    def __init__(self, client: HoneycombClient) -> None:
+        super().__init__(client)
+
+    def _build_path(self, dataset: str, slo_id: str | None = None) -> str:
+        """Build API path for SLOs."""
+        base = f"/1/slos/{dataset}"
+        if slo_id:
+            return f"{base}/{slo_id}"
+        return base
+
+    # -------------------------------------------------------------------------
+    # Async methods
+    # -------------------------------------------------------------------------
+
+    async def list_async(self, dataset: str) -> list[SLO]:
+        """List all SLOs for a dataset (async).
+
+        Args:
+            dataset: Dataset slug.
+
+        Returns:
+            List of SLO objects.
+        """
+        data = await self._get_async(self._build_path(dataset))
+        return self._parse_model_list(SLO, data)
+
+    async def get_async(self, dataset: str, slo_id: str) -> SLO:
+        """Get a specific SLO (async).
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID.
+
+        Returns:
+            SLO object.
+        """
+        data = await self._get_async(self._build_path(dataset, slo_id))
+        return self._parse_model(SLO, data)
+
+    async def create_async(self, dataset: str, slo: SLOCreate) -> SLO:
+        """Create a new SLO (async).
+
+        Args:
+            dataset: Dataset slug.
+            slo: SLO configuration.
+
+        Returns:
+            Created SLO object.
+        """
+        data = await self._post_async(self._build_path(dataset), json=slo.model_dump_for_api())
+        return self._parse_model(SLO, data)
+
+    async def update_async(self, dataset: str, slo_id: str, slo: SLOCreate) -> SLO:
+        """Update an existing SLO (async).
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID.
+            slo: Updated SLO configuration.
+
+        Returns:
+            Updated SLO object.
+        """
+        data = await self._put_async(
+            self._build_path(dataset, slo_id), json=slo.model_dump_for_api()
+        )
+        return self._parse_model(SLO, data)
+
+    async def delete_async(self, dataset: str, slo_id: str) -> None:
+        """Delete an SLO (async).
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID.
+        """
+        await self._delete_async(self._build_path(dataset, slo_id))
+
+    # -------------------------------------------------------------------------
+    # SLO Bundle creation helpers (async)
+    # -------------------------------------------------------------------------
+
+    async def create_from_bundle_async(self, bundle: SLOBundle) -> dict[str, SLO]:
+        """Create SLO(s) from an SLOBundle with automatic orchestration (async).
+
+        This method handles the full orchestration of creating an SLO bundle:
+        1. Creates derived column if needed (environment-wide or dataset-scoped)
+        2. Creates SLO in each specified dataset
+        3. Creates burn alerts for each SLO (if configured)
+
+        Args:
+            bundle: SLOBundle from SLOBuilder.build()
+
+        Returns:
+            Dictionary mapping dataset slugs to created SLO objects
+
+        Example:
+            >>> bundle = (
+            ...     SLOBuilder("API Availability")
+            ...     .dataset("api-logs")
+            ...     .target_nines(3)
+            ...     .sli(alias="success_rate", expression="IF(LT($status, 400), 1, 0)")
+            ...     .exhaustion_alert(
+            ...         BurnAlertBuilder(BurnAlertType.EXHAUSTION_TIME)
+            ...         .exhaustion_minutes(60)
+            ...         .email("oncall@example.com")
+            ...     )
+            ...     .build()
+            ... )
+            >>> slos = await client.slos.create_from_bundle_async(bundle)
+            >>> api_slo = slos["api-logs"]
+        """
+        created_slos: dict[str, SLO] = {}
+
+        # Step 1: Create derived column if needed
+        if bundle.derived_column:
+            if bundle.derived_column_environment_wide:
+                # Create as environment-wide derived column (use "__all__" dataset)
+                await self._client.derived_columns.create_async("__all__", bundle.derived_column)
+            else:
+                # Create in first dataset (single-dataset SLO)
+                await self._client.derived_columns.create_async(
+                    bundle.datasets[0], bundle.derived_column
+                )
+
+        # Step 2: Create SLO in each dataset
+        for dataset in bundle.datasets:
+            slo = await self.create_async(dataset, bundle.slo)
+            created_slos[dataset] = slo
+
+            # Step 3: Create burn alerts for this SLO
+            for alert_def in bundle.burn_alerts:
+                # Process inline recipients with idempotent handling
+                from ._recipient_utils import process_inline_recipients
+
+                processed_recipients = await process_inline_recipients(
+                    self._client, alert_def.recipients.copy()
+                )
+
+                # Convert recipients to BurnAlertRecipient format
+                recipients = [BurnAlertRecipient(**recipient) for recipient in processed_recipients]
+
+                # Convert budget rate percent to per-million if needed
+                budget_rate_threshold = None
+                if alert_def.budget_rate_decrease_percent is not None:
+                    budget_rate_threshold = int(alert_def.budget_rate_decrease_percent * 10000)
+
+                burn_alert = BurnAlertCreate(
+                    alert_type=alert_def.alert_type,
+                    slo_id=slo.id,
+                    description=alert_def.description,
+                    exhaustion_minutes=alert_def.exhaustion_minutes,
+                    budget_rate_window_minutes=alert_def.budget_rate_window_minutes,
+                    budget_rate_decrease_threshold_per_million=budget_rate_threshold,
+                    recipients=recipients if recipients else [],
+                )
+
+                await self._client.burn_alerts.create_async(dataset, burn_alert)
+
+        return created_slos
+
+    # -------------------------------------------------------------------------
+    # Sync methods
+    # -------------------------------------------------------------------------
+
+    def list(self, dataset: str) -> list[SLO]:
+        """List all SLOs for a dataset.
+
+        Args:
+            dataset: Dataset slug.
+
+        Returns:
+            List of SLO objects.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use list_async() for async mode, or pass sync=True to client")
+        data = self._get_sync(self._build_path(dataset))
+        return self._parse_model_list(SLO, data)
+
+    def get(self, dataset: str, slo_id: str) -> SLO:
+        """Get a specific SLO.
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID.
+
+        Returns:
+            SLO object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use get_async() for async mode, or pass sync=True to client")
+        data = self._get_sync(self._build_path(dataset, slo_id))
+        return self._parse_model(SLO, data)
+
+    def create(self, dataset: str, slo: SLOCreate) -> SLO:
+        """Create a new SLO.
+
+        Args:
+            dataset: Dataset slug.
+            slo: SLO configuration.
+
+        Returns:
+            Created SLO object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use create_async() for async mode, or pass sync=True to client")
+        data = self._post_sync(self._build_path(dataset), json=slo.model_dump_for_api())
+        return self._parse_model(SLO, data)
+
+    def update(self, dataset: str, slo_id: str, slo: SLOCreate) -> SLO:
+        """Update an existing SLO.
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID.
+            slo: Updated SLO configuration.
+
+        Returns:
+            Updated SLO object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use update_async() for async mode, or pass sync=True to client")
+        data = self._put_sync(self._build_path(dataset, slo_id), json=slo.model_dump_for_api())
+        return self._parse_model(SLO, data)
+
+    def delete(self, dataset: str, slo_id: str) -> None:
+        """Delete an SLO.
+
+        Args:
+            dataset: Dataset slug.
+            slo_id: SLO ID.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use delete_async() for async mode, or pass sync=True to client")
+        self._delete_sync(self._build_path(dataset, slo_id))
+
+    # -------------------------------------------------------------------------
+    # SLO Bundle creation helpers (sync)
+    # -------------------------------------------------------------------------
+
+    def create_from_bundle(self, bundle: SLOBundle) -> dict[str, SLO]:
+        """Create SLO(s) from an SLOBundle with automatic orchestration.
+
+        This method handles the full orchestration of creating an SLO bundle:
+        1. Creates derived column if needed (environment-wide or dataset-scoped)
+        2. Creates SLO in each specified dataset
+        3. Creates burn alerts for each SLO (if configured)
+
+        Args:
+            bundle: SLOBundle from SLOBuilder.build()
+
+        Returns:
+            Dictionary mapping dataset slugs to created SLO objects
+
+        Example:
+            >>> bundle = (
+            ...     SLOBuilder("API Availability")
+            ...     .dataset("api-logs")
+            ...     .target_nines(3)
+            ...     .sli(alias="success_rate", expression="IF(LT($status, 400), 1, 0)")
+            ...     .exhaustion_alert(
+            ...         BurnAlertBuilder(BurnAlertType.EXHAUSTION_TIME)
+            ...         .exhaustion_minutes(60)
+            ...         .email("oncall@example.com")
+            ...     )
+            ...     .build()
+            ... )
+            >>> slos = client.slos.create_from_bundle(bundle)
+            >>> api_slo = slos["api-logs"]
+        """
+        if not self._client.is_sync:
+            raise RuntimeError(
+                "Use create_from_bundle_async() for async mode, or pass sync=True to client"
+            )
+
+        created_slos: dict[str, SLO] = {}
+
+        # Step 1: Create derived column if needed
+        if bundle.derived_column:
+            if bundle.derived_column_environment_wide:
+                # Create as environment-wide derived column (use "__all__" dataset)
+                self._client.derived_columns.create("__all__", bundle.derived_column)
+            else:
+                # Create in first dataset (single-dataset SLO)
+                self._client.derived_columns.create(bundle.datasets[0], bundle.derived_column)
+
+        # Step 2: Create SLO in each dataset
+        for dataset in bundle.datasets:
+            slo = self.create(dataset, bundle.slo)
+            created_slos[dataset] = slo
+
+            # Step 3: Create burn alerts for this SLO
+            for alert_def in bundle.burn_alerts:
+                # Process inline recipients with idempotent handling
+                import asyncio
+
+                from ._recipient_utils import process_inline_recipients
+
+                processed_recipients = asyncio.run(
+                    process_inline_recipients(self._client, alert_def.recipients.copy())
+                )
+
+                # Convert recipients to BurnAlertRecipient format
+                recipients = [BurnAlertRecipient(**recipient) for recipient in processed_recipients]
+
+                # Convert budget rate percent to per-million if needed
+                budget_rate_threshold = None
+                if alert_def.budget_rate_decrease_percent is not None:
+                    budget_rate_threshold = int(alert_def.budget_rate_decrease_percent * 10000)
+
+                burn_alert = BurnAlertCreate(
+                    alert_type=alert_def.alert_type,
+                    slo_id=slo.id,
+                    description=alert_def.description,
+                    exhaustion_minutes=alert_def.exhaustion_minutes,
+                    budget_rate_window_minutes=alert_def.budget_rate_window_minutes,
+                    budget_rate_decrease_threshold_per_million=budget_rate_threshold,
+                    recipients=recipients if recipients else [],
+                )
+
+                self._client.burn_alerts.create(dataset, burn_alert)
+
+        return created_slos

honeycomb/resources/triggers.py

@@ -0,0 +1,284 @@
+"""Triggers resource for Honeycomb API."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from ..models.triggers import Trigger, TriggerCreate
+from .base import BaseResource
+
+if TYPE_CHECKING:
+    from ..client import HoneycombClient
+    from ..models.trigger_builder import TriggerBundle
+
+
+class TriggersResource(BaseResource):
+    """Resource for managing Honeycomb triggers.
+
+    Triggers allow you to define alert conditions on your data
+    and receive notifications when those conditions are met.
+
+    Example (async):
+        >>> async with HoneycombClient(api_key="...") as client:
+        ...     triggers = await client.triggers.list(dataset="my-dataset")
+        ...     trigger = await client.triggers.get(dataset="my-dataset", trigger_id="abc123")
+
+    Example (sync):
+        >>> with HoneycombClient(api_key="...", sync=True) as client:
+        ...     triggers = client.triggers.list(dataset="my-dataset")
+    """
+
+    def __init__(self, client: HoneycombClient) -> None:
+        super().__init__(client)
+
+    def _build_path(self, dataset: str, trigger_id: str | None = None) -> str:
+        """Build API path for triggers."""
+        base = f"/1/triggers/{dataset}"
+        if trigger_id:
+            return f"{base}/{trigger_id}"
+        return base
+
+    # -------------------------------------------------------------------------
+    # Async methods
+    # -------------------------------------------------------------------------
+
+    async def list_async(self, dataset: str) -> list[Trigger]:
+        """List all triggers for a dataset (async).
+
+        Args:
+            dataset: Dataset slug.
+
+        Returns:
+            List of Trigger objects.
+        """
+        data = await self._get_async(self._build_path(dataset))
+        return self._parse_model_list(Trigger, data)
+
+    async def get_async(self, dataset: str, trigger_id: str) -> Trigger:
+        """Get a specific trigger (async).
+
+        Args:
+            dataset: Dataset slug.
+            trigger_id: Trigger ID.
+
+        Returns:
+            Trigger object.
+        """
+        data = await self._get_async(self._build_path(dataset, trigger_id))
+        return self._parse_model(Trigger, data)
+
+    async def create_async(self, dataset: str, trigger: TriggerCreate) -> Trigger:
+        """Create a new trigger (async).
+
+        Args:
+            dataset: Dataset slug.
+            trigger: Trigger configuration.
+
+        Returns:
+            Created Trigger object.
+        """
+        data = await self._post_async(self._build_path(dataset), json=trigger.model_dump_for_api())
+        return self._parse_model(Trigger, data)
+
+    async def update_async(self, dataset: str, trigger_id: str, trigger: TriggerCreate) -> Trigger:
+        """Update an existing trigger (async).
+
+        Args:
+            dataset: Dataset slug.
+            trigger_id: Trigger ID.
+            trigger: Updated trigger configuration.
+
+        Returns:
+            Updated Trigger object.
+        """
+        data = await self._put_async(
+            self._build_path(dataset, trigger_id), json=trigger.model_dump_for_api()
+        )
+        return self._parse_model(Trigger, data)
+
+    async def delete_async(self, dataset: str, trigger_id: str) -> None:
+        """Delete a trigger (async).
+
+        Args:
+            dataset: Dataset slug.
+            trigger_id: Trigger ID.
+        """
+        await self._delete_async(self._build_path(dataset, trigger_id))
+
+    # -------------------------------------------------------------------------
+    # Sync methods
+    # -------------------------------------------------------------------------
+
+    def list(self, dataset: str) -> list[Trigger]:
+        """List all triggers for a dataset.
+
+        Args:
+            dataset: Dataset slug.
+
+        Returns:
+            List of Trigger objects.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use list_async() for async mode, or pass sync=True to client")
+        data = self._get_sync(self._build_path(dataset))
+        return self._parse_model_list(Trigger, data)
+
+    def get(self, dataset: str, trigger_id: str) -> Trigger:
+        """Get a specific trigger.
+
+        Args:
+            dataset: Dataset slug.
+            trigger_id: Trigger ID.
+
+        Returns:
+            Trigger object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use get_async() for async mode, or pass sync=True to client")
+        data = self._get_sync(self._build_path(dataset, trigger_id))
+        return self._parse_model(Trigger, data)
+
+    def create(self, dataset: str, trigger: TriggerCreate) -> Trigger:
+        """Create a new trigger.
+
+        Args:
+            dataset: Dataset slug.
+            trigger: Trigger configuration.
+
+        Returns:
+            Created Trigger object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use create_async() for async mode, or pass sync=True to client")
+        data = self._post_sync(self._build_path(dataset), json=trigger.model_dump_for_api())
+        return self._parse_model(Trigger, data)
+
+    def update(self, dataset: str, trigger_id: str, trigger: TriggerCreate) -> Trigger:
+        """Update an existing trigger.
+
+        Args:
+            dataset: Dataset slug.
+            trigger_id: Trigger ID.
+            trigger: Updated trigger configuration.
+
+        Returns:
+            Updated Trigger object.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use update_async() for async mode, or pass sync=True to client")
+        data = self._put_sync(
+            self._build_path(dataset, trigger_id), json=trigger.model_dump_for_api()
+        )
+        return self._parse_model(Trigger, data)
+
+    def delete(self, dataset: str, trigger_id: str) -> None:
+        """Delete a trigger.
+
+        Args:
+            dataset: Dataset slug.
+            trigger_id: Trigger ID.
+        """
+        if not self._client.is_sync:
+            raise RuntimeError("Use delete_async() for async mode, or pass sync=True to client")
+        self._delete_sync(self._build_path(dataset, trigger_id))
+
+    # -------------------------------------------------------------------------
+    # Trigger Bundle creation helpers (async)
+    # -------------------------------------------------------------------------
+
+    async def create_from_bundle_async(self, bundle: TriggerBundle) -> Trigger:
+        """Create trigger from bundle with recipient orchestration (async).
+
+        Orchestrates:
+        1. Create/find inline recipients (idempotent)
+        2. Create trigger with recipient IDs
+
+        Args:
+            bundle: TriggerBundle from TriggerBuilder.build_bundle()
+
+        Returns:
+            Created Trigger object
+
+        Example:
+            >>> bundle = (
+            ...     TriggerBuilder("High Error Rate")
+            ...     .dataset("api-logs")
+            ...     .last_30_minutes()
+            ...     .count()
+            ...     .threshold_gt(100)
+            ...     .email("oncall@example.com")
+            ...     .build_bundle()
+            ... )
+            >>> trigger = await client.triggers.create_from_bundle_async(bundle)
+        """
+        from ._recipient_utils import process_inline_recipients
+
+        # Handle inline recipients with idempotency
+        if bundle.inline_recipients:
+            processed_recipients = await process_inline_recipients(
+                self._client, bundle.inline_recipients
+            )
+
+            # Merge with existing recipients in trigger
+            existing_recipients = bundle.trigger.recipients or []
+            all_recipients = existing_recipients + processed_recipients
+
+            # Create new trigger object with all recipients
+            trigger_with_ids = TriggerCreate(
+                name=bundle.trigger.name,
+                description=bundle.trigger.description,
+                threshold=bundle.trigger.threshold,
+                frequency=bundle.trigger.frequency,
+                query=bundle.trigger.query,
+                disabled=bundle.trigger.disabled,
+                alert_type=bundle.trigger.alert_type,
+                recipients=all_recipients if all_recipients else None,
+                tags=bundle.trigger.tags,
+                baseline_details=bundle.trigger.baseline_details,
+            )
+        else:
+            trigger_with_ids = bundle.trigger
+
+        # Create trigger
+        return await self.create_async(bundle.dataset, trigger_with_ids)
+
+    # -------------------------------------------------------------------------
+    # Trigger Bundle creation helpers (sync)
+    # -------------------------------------------------------------------------
+
+    def create_from_bundle(self, bundle: TriggerBundle) -> Trigger:
+        """Create trigger from bundle with recipient orchestration (sync).
+
+        Orchestrates:
+        1. Create/find inline recipients (idempotent)
+        2. Create trigger with recipient IDs
+
+        Args:
+            bundle: TriggerBundle from TriggerBuilder.build_bundle()
+
+        Returns:
+            Created Trigger object
+
+        Raises:
+            RuntimeError: If client is in async mode
+
+        Example:
+            >>> bundle = (
+            ...     TriggerBuilder("High Error Rate")
+            ...     .dataset("api-logs")
+            ...     .last_30_minutes()
+            ...     .count()
+            ...     .threshold_gt(100)
+            ...     .email("oncall@example.com")
+            ...     .build_bundle()
+            ... )
+            >>> trigger = client.triggers.create_from_bundle(bundle)
+        """
+        if not self._client.is_sync:
+            raise RuntimeError(
+                "Cannot use sync method with async client. "
+                "Use create_from_bundle_async() for async mode, or pass sync=True to client"
+            )
+
+        return asyncio.run(self.create_from_bundle_async(bundle))