honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/models/triggers.py

@@ -0,0 +1,208 @@
+"""Pydantic models for Honeycomb Triggers."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from honeycomb.models.query_builder import (
+    CalcOp,
+    Calculation,
+    Filter,
+    FilterCombination,
+)
+
+
+class TriggerThresholdOp(str, Enum):
+    """Threshold comparison operators."""
+
+    GREATER_THAN = ">"
+    GREATER_THAN_OR_EQUAL = ">="
+    LESS_THAN = "<"
+    LESS_THAN_OR_EQUAL = "<="
+
+
+class TriggerAlertType(str, Enum):
+    """How often to fire an alert when threshold is crossed."""
+
+    ON_CHANGE = "on_change"
+    ON_TRUE = "on_true"
+
+
+class TriggerThreshold(BaseModel):
+    """Threshold configuration for a trigger."""
+
+    op: TriggerThresholdOp = Field(description="Comparison operator")
+    value: float = Field(description="Threshold value")
+    exceeded_limit: int | None = Field(
+        default=None, description="Number of times threshold must be exceeded"
+    )
+
+
+def _default_calculations() -> list[Calculation | dict[str, Any]]:
+    """Default calculations for TriggerQuery."""
+    return [Calculation(op=CalcOp.COUNT)]
+
+
+class TriggerQuery(BaseModel):
+    """Inline query specification for a trigger.
+
+    Note: time_range must be <= 3600 (1 hour) for triggers.
+
+    Accepts both typed models and dicts for flexibility:
+        >>> # Using typed models
+        >>> TriggerQuery(calculations=[Calculation(op=CalcOp.P99, column="duration_ms")])
+
+        >>> # Using dicts
+        >>> TriggerQuery(calculations=[{"op": "P99", "column": "duration_ms"}])
+    """
+
+    time_range: int = Field(
+        default=3600,
+        le=3600,
+        description="Query time range in seconds (max 3600 for triggers)",
+    )
+    granularity: int | None = Field(default=None, description="Time granularity in seconds")
+    calculations: list[Calculation | dict[str, Any]] | None = Field(
+        default_factory=_default_calculations,
+        description="Calculations to perform",
+    )
+    filters: list[Filter | dict[str, Any]] | None = Field(default=None, description="Query filters")
+    breakdowns: list[str] | None = Field(default=None, description="Columns to group by")
+    filter_combination: FilterCombination | str | None = Field(
+        default=None, description="How to combine filters (AND/OR)"
+    )
+
+
+def _normalize_calculation(calc: Calculation | dict[str, Any]) -> dict[str, Any]:
+    """Convert a Calculation or dict to API dict format."""
+    if isinstance(calc, Calculation):
+        return calc.to_dict()
+    return calc
+
+
+def _normalize_filter(filt: Filter | dict[str, Any]) -> dict[str, Any]:
+    """Convert a Filter or dict to API dict format."""
+    if isinstance(filt, Filter):
+        return filt.to_dict()
+    return filt
+
+
+def _normalize_filter_combination(combo: FilterCombination | str | None) -> str | None:
+    """Convert a FilterCombination or string to API format."""
+    if combo is None:
+        return None
+    if isinstance(combo, FilterCombination):
+        return combo.value
+    return combo
+
+
+class TriggerCreate(BaseModel):
+    """Model for creating a new trigger."""
+
+    name: str = Field(description="Human-readable name for the trigger")
+    description: str | None = Field(default=None, description="Longer description")
+    threshold: TriggerThreshold = Field(description="Threshold configuration")
+    frequency: int = Field(
+        default=900,
+        ge=60,
+        le=86400,
+        description="Check frequency in seconds (60-86400)",
+    )
+    query: TriggerQuery | None = Field(default=None, description="Inline query")
+    query_id: str | None = Field(default=None, description="Reference to saved query")
+    disabled: bool = Field(default=False, description="Whether trigger is disabled")
+    alert_type: TriggerAlertType = Field(
+        default=TriggerAlertType.ON_CHANGE,
+        description="When to send alerts",
+    )
+    recipients: list[dict] | None = Field(default=None, description="Notification recipients")
+    tags: list[dict[str, str]] | None = Field(
+        default=None, description="Tags for organizing triggers (max 10)"
+    )
+    baseline_details: dict[str, Any] | None = Field(
+        default=None,
+        description="Baseline threshold configuration for comparing against historical data",
+    )
+
+    def model_dump_for_api(self) -> dict[str, Any]:
+        """Serialize for API request, handling nested models."""
+        data: dict[str, Any] = {
+            "name": self.name,
+            "threshold": {
+                "op": self.threshold.op.value,
+                "value": self.threshold.value,
+            },
+            "frequency": self.frequency,
+            "disabled": self.disabled,
+            "alert_type": self.alert_type.value,
+        }
+
+        if self.description:
+            data["description"] = self.description
+
+        if self.threshold.exceeded_limit is not None:
+            data["threshold"]["exceeded_limit"] = self.threshold.exceeded_limit
+
+        if self.query:
+            query_data: dict[str, Any] = {"time_range": self.query.time_range}
+            if self.query.granularity:
+                query_data["granularity"] = self.query.granularity
+            if self.query.calculations:
+                query_data["calculations"] = [
+                    _normalize_calculation(c) for c in self.query.calculations
+                ]
+            if self.query.filters:
+                query_data["filters"] = [_normalize_filter(f) for f in self.query.filters]
+            if self.query.breakdowns:
+                query_data["breakdowns"] = self.query.breakdowns
+            if self.query.filter_combination:
+                query_data["filter_combination"] = _normalize_filter_combination(
+                    self.query.filter_combination
+                )
+            data["query"] = query_data
+
+        if self.query_id:
+            data["query_id"] = self.query_id
+
+        if self.recipients:
+            data["recipients"] = self.recipients
+
+        if self.tags:
+            data["tags"] = self.tags
+
+        if self.baseline_details:
+            data["baseline_details"] = self.baseline_details
+
+        return data
+
+
+class Trigger(BaseModel):
+    """A Honeycomb trigger (response model)."""
+
+    id: str = Field(description="Unique identifier")
+    name: str = Field(description="Human-readable name")
+    description: str | None = Field(default=None, description="Longer description")
+    dataset_slug: str = Field(description="Dataset this trigger belongs to")
+    threshold: TriggerThreshold = Field(description="Threshold configuration")
+    frequency: int = Field(description="Check frequency in seconds")
+    query: dict | None = Field(default=None, description="Inline query")
+    query_id: str | None = Field(default=None, description="Reference to saved query")
+    disabled: bool = Field(default=False, description="Whether trigger is disabled")
+    triggered: bool = Field(default=False, description="Whether currently triggered")
+    alert_type: str = Field(default="on_change", description="When to send alerts")
+    recipients: list[dict] | None = Field(default=None, description="Notification recipients")
+    tags: list[dict[str, str]] | None = Field(
+        default=None, description="Tags for organizing triggers"
+    )
+    baseline_details: dict[str, Any] | None = Field(
+        default=None, description="Baseline threshold configuration"
+    )
+    evaluation_schedule_type: str | None = Field(default=None)
+    created_at: datetime | None = Field(default=None, description="Creation timestamp")
+    updated_at: datetime | None = Field(default=None, description="Last update timestamp")
+
+    model_config = {"extra": "allow"}

honeycomb/resources/__init__.py

@@ -0,0 +1,35 @@
+"""Resource clients for Honeycomb API."""
+
+from .api_keys import ApiKeysResource
+from .base import BaseResource
+from .boards import BoardsResource
+from .burn_alerts import BurnAlertsResource
+from .columns import ColumnsResource
+from .datasets import DatasetsResource
+from .environments import EnvironmentsResource
+from .events import EventsResource
+from .markers import MarkersResource
+from .queries import QueriesResource
+from .query_results import QueryResultsResource
+from .recipients import RecipientsResource
+from .service_map_dependencies import ServiceMapDependenciesResource
+from .slos import SLOsResource
+from .triggers import TriggersResource
+
+__all__ = [
+    "BaseResource",
+    "TriggersResource",
+    "SLOsResource",
+    "DatasetsResource",
+    "BoardsResource",
+    "QueriesResource",
+    "QueryResultsResource",
+    "ColumnsResource",
+    "MarkersResource",
+    "RecipientsResource",
+    "BurnAlertsResource",
+    "EventsResource",
+    "ApiKeysResource",
+    "EnvironmentsResource",
+    "ServiceMapDependenciesResource",
+]

honeycomb/resources/_recipient_utils.py

@@ -0,0 +1,156 @@
+"""Shared utilities for recipient handling across resources."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from honeycomb.client import HoneycombClient
+
+
+async def process_inline_recipients(
+    client: HoneycombClient,
+    recipients_input: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Process inline recipients with idempotency.
+
+    For each recipient without 'id':
+    1. Check if matching recipient exists (by type + target)
+    2. Reuse existing ID if found
+    3. Create new recipient if not found
+    4. Handle 409 conflicts (race conditions)
+
+    Recipients with existing 'id' fields are returned unchanged.
+
+    Args:
+        client: HoneycombClient for API calls
+        recipients_input: List of recipient specs (may have inline recipients)
+
+    Returns:
+        Updated recipients list with all IDs resolved
+
+    Example:
+        >>> recipients = [
+        ...     {"type": "email", "target": "oncall@example.com"},
+        ...     {"id": "existing-recip-id"}
+        ... ]
+        >>> resolved = await process_inline_recipients(client, recipients)
+        >>> # First recipient now has an ID, second unchanged
+    """
+    from honeycomb.exceptions import HoneycombAPIError
+    from honeycomb.models.recipients import RecipientCreate, RecipientType
+
+    # List existing recipients once for idempotent checks
+    existing_recipients = await client.recipients.list_async()
+
+    result: list[dict[str, Any]] = []
+
+    for recip in recipients_input:
+        if "id" in recip:
+            # Already has ID - keep as is
+            result.append(recip)
+            continue
+
+        # Inline recipient - find existing or create new
+        recip_type = RecipientType(recip["type"])
+        target = recip["target"]
+
+        # Check if recipient with matching type and target already exists
+        existing = None
+        for existing_recip in existing_recipients:
+            if existing_recip.type == recip_type:
+                # Check target match based on type
+                existing_target = None
+                if recip_type == RecipientType.EMAIL:
+                    existing_target = existing_recip.details.get("email_address")
+                elif recip_type == RecipientType.SLACK:
+                    existing_target = existing_recip.details.get("slack_channel")
+                elif recip_type == RecipientType.WEBHOOK or recip_type in (
+                    RecipientType.MSTEAMS_WORKFLOW,
+                    RecipientType.MSTEAMS,
+                ):
+                    existing_target = existing_recip.details.get("webhook_url")
+                elif recip_type == RecipientType.PAGERDUTY:
+                    existing_target = existing_recip.details.get("pagerduty_integration_key")
+
+                if existing_target == target:
+                    existing = existing_recip
+                    break
+
+        if existing:
+            # Reuse existing recipient
+            result.append({"id": existing.id})
+        else:
+            # Create new recipient - build details based on type (matching API spec)
+            details = recip.get("details", {})
+            if recip_type == RecipientType.EMAIL:
+                if "email_address" not in details:
+                    details = {"email_address": target}
+            elif recip_type == RecipientType.SLACK:
+                if "slack_channel" not in details:
+                    details = {"slack_channel": target}
+            elif recip_type == RecipientType.PAGERDUTY:
+                if "pagerduty_integration_key" not in details:
+                    details = {
+                        "pagerduty_integration_key": target,
+                        "pagerduty_integration_name": "PagerDuty Integration",
+                    }
+            elif recip_type == RecipientType.WEBHOOK:
+                if "webhook_url" not in details:
+                    details = {
+                        "webhook_url": target,
+                        "webhook_name": recip.get("name", "Webhook"),
+                    }
+            elif (
+                recip_type
+                in (
+                    RecipientType.MSTEAMS_WORKFLOW,
+                    RecipientType.MSTEAMS,
+                )
+                and "webhook_url" not in details
+            ):
+                details = {
+                    "webhook_url": target,
+                    "webhook_name": "MS Teams",
+                }
+
+            # Create recipient via Recipients API
+            try:
+                recipient_obj = RecipientCreate(type=recip_type, details=details)
+                created_recip = await client.recipients.create_async(recipient_obj)
+                result.append({"id": created_recip.id})
+            except HoneycombAPIError as e:
+                if e.status_code == 409:
+                    # Conflict - recipient exists but we didn't find it (race condition)
+                    # Re-fetch and try to find it
+                    existing_recipients = await client.recipients.list_async()
+                    found = False
+                    for existing_recip in existing_recipients:
+                        if existing_recip.type == recip_type:
+                            check_target = None
+                            if recip_type == RecipientType.EMAIL:
+                                check_target = existing_recip.details.get("email_address")
+                            elif recip_type == RecipientType.SLACK:
+                                check_target = existing_recip.details.get("slack_channel")
+                            elif recip_type == RecipientType.WEBHOOK or recip_type in (
+                                RecipientType.MSTEAMS_WORKFLOW,
+                                RecipientType.MSTEAMS,
+                            ):
+                                check_target = existing_recip.details.get("webhook_url")
+                            elif recip_type == RecipientType.PAGERDUTY:
+                                check_target = existing_recip.details.get(
+                                    "pagerduty_integration_key"
+                                )
+
+                            if check_target == target:
+                                result.append({"id": existing_recip.id})
+                                found = True
+                                break
+
+                    if not found:
+                        # Still not found - re-raise original error
+                        raise
+                else:
+                    raise
+
+    return result