superkick 0.1.0

data/lib/superkick/integrations/datadog/alert_monitor.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Datadog
+      # Polls a specific Datadog monitor for status changes and injects events
+      # when the alert state transitions (e.g. Alert → OK, Warn → Alert).
+      #
+      # Typically auto-configured by the AlertSpawner — the monitor_id
+      # is passed through the spawn event context.
+      #
+      # Config keys:
+      #   monitor_id       (required) — the Datadog monitor ID to watch
+      #   site             (optional) — Datadog site, default "datadoghq.com"
+      #   api_key          (optional) — API key, falls back to $DD_API_KEY
+      #   application_key  (optional) — Application key, falls back to $DD_APP_KEY
+      #
+      # Events emitted:
+      #   alert_recovered  — monitor transitioned to OK
+      #   alert_escalated  — monitor transitioned from Warn to Alert
+      #   alert_changed    — any other status change
+      class AlertMonitor < Superkick::Monitor
+        attr_reader :conn
+
+        DEFAULT_SITE = "datadoghq.com"
+
+        def self.type = :datadog_alert
+
+        def self.description
+          "Monitors a specific Datadog monitor for alert status changes. " \
+            "Injects events when the alert recovers, escalates, or changes state."
+        end
+
+        def self.required_config = %i[monitor_id]
+
+        def self.setup_label = "Datadog Alert"
+
+        def self.setup_config
+          <<~YAML
+            datadog_alert:
+              monitor_id: 12345678               # your Datadog monitor ID
+              # site: datadoghq.com              # Datadog site (default)
+              # api_key: <%= env("DD_API_KEY") %>
+              # application_key: <%= env("DD_APP_KEY") %>
+          YAML
+        end
+
+        def self.templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def initialize(name:, config:, handler:, agent: nil, server_context: {}, connection: nil)
+          super(name:, config:, handler:, agent:, server_context:)
+          @conn = connection
+        end
+
+        def tick
+          monitor = fetch_monitor
+          return unless monitor
+
+          current_status = monitor["overall_state"].to_s
+          monitor_name = monitor["name"].to_s
+
+          if @last_status.nil?
+            # First tick — record baseline, don't dispatch
+            @last_status = current_status
+            Superkick.logger.info(log_tag) { "Initial status: #{current_status}" }
+            return
+          end
+
+          return if current_status == @last_status
+
+          previous = @last_status
+          @last_status = current_status
+
+          event_type = classify_transition(previous, current_status)
+
+          dispatch(
+            event_type:,
+            monitor_id: self[:monitor_id],
+            name: monitor_name,
+            status: current_status,
+            previous_status: previous,
+            alert_type: monitor["type"].to_s,
+            query: monitor["query"].to_s,
+            tags: monitor["tags"] || [],
+            url: monitor_url
+          )
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @last_status = nil
+        end
+
+        private
+
+        def classify_transition(previous, current)
+          if current == "OK"
+            :alert_recovered
+          elsif current == "Alert" && previous == "Warn"
+            :alert_escalated
+          else
+            :alert_changed
+          end
+        end
+
+        # -- Datadog Monitor API ---------------------------------------------------
+
+        def fetch_monitor
+          monitor_id = self[:monitor_id]
+          resp = get("/api/v1/monitor/#{monitor_id}")
+          return nil unless resp
+
+          resp.body
+        end
+
+        # -- URL helpers ----------------------------------------------------------
+
+        def monitor_url
+          site = self[:site] || DEFAULT_SITE
+          "https://app.#{site}/monitors/#{self[:monitor_id]}"
+        end
+
+        # -- HTTP -----------------------------------------------------------------
+
+        def get(path)
+          resp = @conn.get(path)
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then true
+          when 401, 403 then raise FatalError, "Datadog auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Datadog rate limited"
+          when 404
+            Superkick.logger.warn(log_tag) { "Datadog monitor #{self[:monitor_id]} not found" }
+            false
+          else
+            Superkick.logger.warn(log_tag) { "Datadog HTTP #{resp.status}" }
+            false
+          end
+        end
+
+        def build_connection
+          site = self[:site] || DEFAULT_SITE
+          api_key = self[:api_key] || ENV["DD_API_KEY"]
+          app_key = self[:application_key] || ENV["DD_APP_KEY"]
+
+          Faraday.new(url: "https://api.#{site}") do |f|
+            f.headers["DD-API-KEY"] = api_key if api_key
+            f.headers["DD-APPLICATION-KEY"] = app_key if app_key
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/datadog/alert_spawner.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Superkick
+  module Integrations
+    module Datadog
+      # Watches Datadog Monitors for triggered alerts and spawns AI coding agents
+      # to triage them.
+      #
+      # Polls the Datadog Monitors Search API for monitors in an alerting state.
+      # Tracks dispatched monitor IDs in-memory; monitors that recover and re-alert
+      # are re-dispatched as new agents.
+      #
+      # Config keys:
+      #   site             (optional) — Datadog site, default "datadoghq.com"
+      #   api_key          (optional) — API key, falls back to $DD_API_KEY
+      #   application_key  (optional) — Application key, falls back to $DD_APP_KEY
+      #   statuses         (optional) — array of statuses to match, default ["Alert"]
+      #   tags             (optional) — array of tags to filter (AND)
+      #   monitor_types    (optional) — array of monitor types to include
+      #   priority         (optional) — array of priority levels (1-5)
+      #   query            (optional) — raw search query string
+      class AlertSpawner < Superkick::Spawner
+        attr_reader :conn
+
+        DEFAULT_SITE = "datadoghq.com"
+        DEFAULT_STATUSES = ["Alert"].freeze
+        PER_PAGE = 25
+
+        def self.type = :datadog_alerts
+
+        def self.description
+          "Watches Datadog monitors for triggered alerts and spawns AI coding " \
+            "agents to triage them. Supports filtering by status, tags, " \
+            "monitor type, and priority."
+        end
+
+        def self.required_config = %i[]
+
+        def self.spawn_templates_dir
+          File.join(__dir__, "templates")
+        end
+
+        def self.agent_id(event)
+          "datadog-alert-#{event[:monitor_id]}"
+        end
+
+        def self.setup_label = "Datadog Alerts"
+
+        def self.setup_config
+          <<~YAML
+            datadog_alerts:
+              type: datadog_alerts
+              # api_key: <%= env("DD_API_KEY") %>
+              # application_key: <%= env("DD_APP_KEY") %>
+              # site: datadoghq.com              # Datadog site (default)
+              # statuses:                        # alert statuses to watch (default: [Alert])
+              #   - Alert
+              # tags:                            # filter by tags (AND)
+              #   - "team:backend"
+              # monitor_types:                   # filter by monitor type
+              #   - metric
+              # max_duration: 3600
+          YAML
+        end
+
+        def initialize(name:, config:, handler:, connection: nil)
+          super(name:, config:, handler:)
+          @conn = connection
+        end
+
+        def tick
+          monitors = fetch_alerting_monitors
+
+          # Clear recovered monitors so re-alerts spawn new agents
+          current_ids = monitors.map { it["id"] }.to_set
+          @seen_monitor_ids &= current_ids
+
+          new_monitors = monitors.reject { @seen_monitor_ids.include?(it["id"]) }
+
+          new_monitors.each do |monitor|
+            @seen_monitor_ids.add(monitor["id"])
+
+            dispatch(
+              event_type: :alert_triggered,
+              monitor_id: monitor["id"],
+              name: monitor["name"].to_s,
+              status: monitor["overall_state"].to_s,
+              alert_type: monitor["type"].to_s,
+              query: monitor["query"].to_s,
+              message: monitor["message"].to_s,
+              tags: monitor["tags"] || [],
+              priority: monitor["priority"],
+              creator: monitor.dig("creator", "name") || monitor.dig("creator", "email"),
+              url: monitor_url(monitor["id"])
+            )
+          end
+        end
+
+        def on_start
+          @conn ||= build_connection
+          @seen_monitor_ids = Set.new
+        end
+
+        private
+
+        # -- Datadog Monitors Search API -------------------------------------------
+
+        def fetch_alerting_monitors
+          query = build_query
+          params = {
+            "query" => query,
+            "per_page" => PER_PAGE.to_s,
+            "sort" => "status,asc"
+          }
+
+          Superkick.logger.debug(log_tag) { "Searching monitors: #{params.inspect}" }
+
+          resp = get("/api/v1/monitor/search", params)
+          return [] unless resp
+
+          body = resp.body
+          monitors = body["monitors"]
+          return [] unless monitors.is_a?(Array)
+
+          Superkick.logger.info(log_tag) { "Found #{monitors.size} alerting monitors" }
+          monitors
+        end
+
+        def build_query
+          parts = []
+
+          statuses = self[:statuses] || DEFAULT_STATUSES
+          status_clause = statuses.map { it.to_s }.join(" OR ")
+          parts << "status:(#{status_clause})"
+
+          if self[:tags]&.any?
+            self[:tags].each { parts << "tag:\"#{it}\"" }
+          end
+
+          if self[:monitor_types]&.any?
+            types = self[:monitor_types].map { "\"#{it}\"" }
+            parts << "type:(#{types.join(" OR ")})"
+          end
+
+          if self[:priority]&.any?
+            parts << "priority:(#{self[:priority].join(" OR ")})"
+          end
+
+          parts << self[:query].to_s if self[:query] && !self[:query].to_s.empty?
+
+          parts.join(" ")
+        end
+
+        # -- URL helpers ----------------------------------------------------------
+
+        def monitor_url(monitor_id)
+          site = self[:site] || DEFAULT_SITE
+          "https://app.#{site}/monitors/#{monitor_id}"
+        end
+
+        # -- HTTP -----------------------------------------------------------------
+
+        def get(path, params = {})
+          resp = @conn.get(path) do |req|
+            params.each { |k, v| req.params[k] = v }
+          end
+          return nil unless handle_response!(resp)
+          resp
+        end
+
+        def handle_response!(resp)
+          case resp.status
+          when 200..299 then true
+          when 401, 403 then raise FatalError, "Datadog auth failed (HTTP #{resp.status})"
+          when 429 then raise RateLimited, "Datadog rate limited"
+          when 404
+            Superkick.logger.warn(log_tag) { "Datadog 404: resource not found" }
+            false
+          else
+            Superkick.logger.warn(log_tag) { "Datadog HTTP #{resp.status}" }
+            false
+          end
+        end
+
+        def build_connection
+          site = self[:site] || DEFAULT_SITE
+          api_key = self[:api_key] || ENV["DD_API_KEY"]
+          app_key = self[:application_key] || ENV["DD_APP_KEY"]
+
+          Faraday.new(url: "https://api.#{site}") do |f|
+            f.headers["DD-API-KEY"] = api_key if api_key
+            f.headers["DD-APPLICATION-KEY"] = app_key if app_key
+            f.response :json
+          end
+        end
+      end
+    end
+  end
+end

data/lib/superkick/integrations/datadog/notification_templates/default.liquid

@@ -0,0 +1,10 @@
+{% event_title %}Superkick: {{ event_type | format_title }}{% endevent_title %}
+{% event_text %}{{ message }}{% endevent_text %}
+{% alert_type %}{{ event_type | datadog_alert_type }}{% endalert_type %}
+{% tag %}event_type:{{ event_type }}{% endtag %}
+{% if agent_id %}{% tag %}agent_id:{{ agent_id }}{% endtag %}{% endif %}
+{% if monitor %}{% tag %}monitor_type:{{ monitor.type }}{% endtag %}
+{% tag %}monitor_name:{{ monitor.name }}{% endtag %}{% endif %}
+{% if team %}{% tag %}team_id:{{ team.id }}{% endtag %}{% endif %}
+{% if agent.role %}{% tag %}team_role:{{ agent.role }}{% endtag %}{% endif %}
+{% if spawner %}{% tag %}spawner_name:{{ spawner.name }}{% endtag %}{% endif %}

data/lib/superkick/integrations/datadog/notifier.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "socket"
+require "time"
+
+module Superkick
+  module Integrations
+    module Datadog
+      # Sends events and metrics to Datadog via DogStatsD (UDP).
+      #
+      # DogStatsD is the native way to get custom events and metrics into Datadog
+      # without going through the HTTP API. It requires a local Datadog Agent
+      # running with DogStatsD enabled (the default).
+      #
+      # Events appear in the Datadog Event Explorer; metrics appear in Metrics
+      # Explorer and can power dashboards and monitors.
+      #
+      # Stateful: tracks `spawned_at` per agent to compute duration on terminal
+      # events, and emits a timing metric when agents finish.
+      #
+      # Template support:
+      #   Event formatting (title, text, alert type, tags) is defined via Liquid
+      #   templates with custom block tags. Users can override per-event-type
+      #   or the default template.
+      #
+      #   Block tags: {% event_title %}, {% event_text %}, {% alert_type %}, {% tag %}
+      #   Filters: `datadog_alert_type`, `format_title`
+      #
+      #   Templates are resolved from:
+      #     1. ~/.superkick/templates/notifications/datadog/<event_type>.liquid
+      #     2. <bundled>/notification_templates/<event_type>.liquid
+      #     3. ~/.superkick/templates/notifications/datadog/default.liquid
+      #     4. <bundled>/notification_templates/default.liquid
+      #
+      # Configuration:
+      #
+      #   notifications:
+      #     - type: datadog
+      #       statsd_host: localhost        # default
+      #       statsd_port: 8125            # default
+      #       prefix: superkick            # metric name prefix (default)
+      #       tags:                        # additional global tags
+      #         - "env:production"
+      #
+      # Emitted metrics (tagged with low-cardinality dimensions only):
+      #   - <prefix>.event          — counter, incremented on every event
+      #   - <prefix>.agent.duration — gauge (seconds), on terminal events only
+      #   - <prefix>.agent.cost_usd — gauge (dollars), when cost data is present
+      #
+      # Tag cardinality: Events include all tags (agent_id, team_id, etc.) since
+      # Datadog events don't create custom metric time series. Metrics only include
+      # low-cardinality tags (event_type, monitor_type, monitor_name, team_role,
+      # spawner_name) to avoid billing explosions from unbounded dimensions.
+      class Notifier < Superkick::Notifier
+        def self.type = :datadog
+
+        def self.templates_dir = File.expand_path("notification_templates", __dir__)
+
+        def self.setup_label = "Datadog"
+
+        def self.setup_config
+          <<~YAML
+            - type: datadog
+              # statsd_host: localhost            # DogStatsD host (default)
+              # statsd_port: 8125                # DogStatsD port (default)
+              # prefix: superkick                # metric name prefix (default)
+              # tags:                            # additional global tags
+              #   - "env:production"
+          YAML
+        end
+
+        ALERT_TYPE_MAP = {
+          "agent_completed" => "success",
+          "agent_failed" => "error",
+          "agent_timed_out" => "warning",
+          "agent_blocked" => "warning",
+          "agent_stalled" => "warning",
+          "agent_terminated" => "warning",
+          "agent_spawned" => "info",
+          "agent_claimed" => "info",
+          "agent_unclaimed" => "info",
+          "agent_pending_approval" => "info",
+          "workflow_triggered" => "info",
+          "workflow_iterations_exceeded" => "warning",
+          "budget_warning" => "warning",
+          "budget_exceeded" => "error",
+          "team_created" => "info",
+          "team_completed" => "success",
+          "team_failed" => "error",
+          "team_timed_out" => "warning",
+          "worker_spawned" => "info",
+          "teammate_message" => "info",
+          "teammate_blocker" => "warning",
+          "attach_promoted" => "info",
+          "attach_demoted" => "info",
+          "attach_idle_timeout" => "warning",
+          "attach_force_takeover" => "warning",
+          "agent_update" => "info",
+          "artifact_published" => "info"
+        }.freeze
+
+        liquid do
+          context do
+            attribute :title
+            attribute :text
+            attribute :tags, default: -> { [] }
+            attribute :alert_type
+          end
+
+          filter :datadog_alert_type do |event_type|
+            Superkick::Integrations::Datadog::Notifier::ALERT_TYPE_MAP.fetch(event_type.to_s, "info")
+          end
+
+          filter :format_title do |event_type|
+            event_type.to_s.tr("_", " ").gsub(/\b\w/, &:upcase)
+          end
+
+          block :event_title do |ctx, text, _attrs|
+            ctx.title = text
+          end
+
+          block :event_text do |ctx, text, _attrs|
+            ctx.text = text
+          end
+
+          block :alert_type do |ctx, text, _attrs|
+            ctx.alert_type = text
+          end
+
+          block :tag do |ctx, text, _attrs|
+            ctx.tags << text unless text.empty?
+          end
+        end
+
+        def initialize(statsd_host: "localhost", statsd_port: 8125, prefix: "superkick", tags: [], **opts)
+          super(**opts)
+          @host = statsd_host
+          @port = Integer(statsd_port)
+          @prefix = prefix
+          @global_tags = Array(tags)
+        end
+
+        def stateful? = true
+
+        def agent_finished(agent_id:)
+          @state_store.delete(:datadog, agent_id.to_s)
+        end
+
+        def notify(payload)
+          event_type = payload[:event_type]
+          agent_id = payload[:agent_id]
+          metric_tags = build_metric_tags(payload)
+
+          # Track spawn time for duration computation
+          if event_type == "agent_spawned" && agent_id && !agent_id.empty?
+            @state_store.put(:datadog, agent_id, {spawned_at: Process.clock_gettime(Process::CLOCK_MONOTONIC)}) unless @state_store.get(:datadog, agent_id)
+          end
+
+          # Send the DogStatsD event (template-driven)
+          send_event(payload)
+
+          # Always increment the event counter (low-cardinality tags only)
+          send_metric("#{@prefix}.event", 1, :counter, metric_tags)
+
+          # On terminal events, emit duration — prefer agent.spawned_at, fall back to local tracking
+          if terminal_event?(event_type) && agent_id && !agent_id.empty?
+            agent_drop = payload.dig(:context, :agent)
+            duration = if agent_drop&.spawned_at
+              (Time.now.utc - Time.parse(agent_drop.spawned_at)).round(1)
+            else
+              state = @state_store.get(:datadog, agent_id)
+              (Process.clock_gettime(Process::CLOCK_MONOTONIC) - state[:spawned_at]).round(1) if state&.dig(:spawned_at)
+            end
+            send_metric("#{@prefix}.agent.duration", duration, :gauge, metric_tags) if duration
+
+            # Emit cost gauge when available
+            if agent_drop&.cost_usd
+              send_metric("#{@prefix}.agent.cost_usd", agent_drop.cost_usd, :gauge, metric_tags)
+            end
+          end
+        rescue => e
+          Superkick.logger.warn("notifier:datadog") { "Failed: #{e.message}" }
+        end
+
+        private
+
+        def send_event(payload)
+          template_result = render_notification(payload)
+
+          if template_result && template_result[:structured]
+            structured = template_result[:structured]
+            title = structured.title || "Superkick: #{format_title(payload[:event_type])}"
+            text = structured.text || payload[:message].to_s
+            alert_type = structured.alert_type || ALERT_TYPE_MAP.fetch(payload[:event_type], "info")
+            tags = @global_tags + structured.tags
+          else
+            title = "Superkick: #{format_title(payload[:event_type])}"
+            text = payload[:message].to_s
+            alert_type = ALERT_TYPE_MAP.fetch(payload[:event_type], "info")
+            tags = @global_tags + build_event_tags_fallback(payload)
+          end
+
+          # DogStatsD event datagram format:
+          # _e{<TITLE_UTF8_LENGTH>,<TEXT_UTF8_LENGTH>}:<TITLE>|<TEXT>|t:<ALERT_TYPE>|#<TAGS>
+          tag_str = tags.join(",")
+          datagram = "_e{#{title.bytesize},#{text.bytesize}}:#{title}|#{text}|t:#{alert_type}"
+          datagram += "|##{tag_str}" unless tag_str.empty?
+          send_udp(datagram)
+        end
+
+        def send_metric(name, value, type, tags)
+          # DogStatsD metric datagram format:
+          # <METRIC_NAME>:<VALUE>|<TYPE>|#<TAGS>
+          type_char = (type == :counter) ? "c" : "g"
+          tag_str = tags.join(",")
+          datagram = "#{name}:#{value}|#{type_char}"
+          datagram += "|##{tag_str}" unless tag_str.empty?
+          send_udp(datagram)
+        end
+
+        def send_udp(datagram)
+          socket = UDPSocket.new
+          socket.send(datagram, 0, @host, @port)
+        ensure
+          socket&.close
+        end
+
+        # Fallback event tags when no template is available.
+        def build_event_tags_fallback(payload)
+          tags = []
+          tags << "event_type:#{payload[:event_type]}" unless payload[:event_type].to_s.empty?
+          tags << "agent_id:#{payload[:agent_id]}" unless payload[:agent_id].to_s.empty?
+
+          monitor = payload[:monitor]
+          if monitor
+            tags << "monitor_type:#{monitor.type}" unless monitor.type.to_s.empty?
+            tags << "monitor_name:#{monitor.name}" unless monitor.name.to_s.empty?
+          end
+
+          ctx = payload[:context] || {}
+          team = ctx[:team]
+          tags << "team_id:#{team.id}" if team&.id
+          agent = ctx[:agent]
+          tags << "team_role:#{agent.role}" if agent&.role
+          spawner = ctx[:spawner]
+          tags << "spawner_name:#{spawner.name}" if spawner
+
+          tags
+        end
+
+        # Low-cardinality tags only — used on counters and gauges where each unique
+        # tag combination creates a custom metric time series in Datadog.
+        #
+        # Safe dimensions:
+        #   event_type   — ~20 values (lifecycle + monitor events)
+        #   monitor_type — ~5 values (github, circleci, shortcut, shell, bugsnag)
+        #   monitor_name — bounded by config keys
+        #   team_role    — 2 values (lead, worker)
+        #   spawner_name — bounded by config keys
+        #
+        # Excluded from metrics (unbounded cardinality):
+        #   agent_id — unique per agent session
+        #   team_id  — unique per team session
+        def build_metric_tags(payload)
+          tags = @global_tags.dup
+          tags << "event_type:#{payload[:event_type]}" unless payload[:event_type].to_s.empty?
+
+          monitor = payload[:monitor]
+          if monitor
+            tags << "monitor_type:#{monitor.type}" unless monitor.type.to_s.empty?
+            tags << "monitor_name:#{monitor.name}" unless monitor.name.to_s.empty?
+          end
+
+          ctx = payload[:context] || {}
+          agent = ctx[:agent]
+          tags << "team_role:#{agent.role}" if agent&.role
+          spawner = ctx[:spawner]
+          tags << "spawner_name:#{spawner.name}" if spawner
+
+          tags
+        end
+
+        def format_title(event_type)
+          event_type.to_s.tr("_", " ").gsub(/\b\w/, &:upcase)
+        end
+
+        def terminal_event?(event_type)
+          %w[agent_completed agent_failed agent_timed_out agent_terminated
+            team_completed team_failed team_timed_out].include?(event_type)
+        end
+      end
+    end
+  end
+end