pagerduty 2.1.1 → 4.0.0

data/lib/pagerduty/events_api_v2.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Pagerduty
+  # Trigger incidents via the PagerDuty Events API version 2.
+  #
+  # @see https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview
+  #   PagerDuty Events API V2 documentation
+  #
+  # @see Pagerduty.build
+  #
+  # @see Pagerduty::EventsApiV2::Incident
+  #
+  class EventsApiV2
+    # Rather than using this directly, use the {Pagerduty.build} method to
+    # construct an instance.
+    #
+    # @option config [String] integration_key Authentication key for connecting
+    #   to PagerDuty. A UUID expressed as a 32-digit hexadecimal number.
+    #   Integration keys are generated by creating a new service, or creating a
+    #   new integration for an existing service in PagerDuty, and can be found
+    #   on a service's Integrations tab. This option is required.
+    #
+    # @option config [String] http_proxy.host The DNS name or IP address of the
+    #   proxy host. If nil or unprovided an HTTP proxy will not be used.
+    #
+    # @option config [String] http_proxy.port The TCP port to use to access the
+    #   proxy.
+    #
+    # @option config [String] http_proxy.username username if authorization is
+    #   required to use the proxy.
+    #
+    # @option config [String] http_proxy.password password if authorization is
+    #   required to use the proxy.
+    #
+    # @see Pagerduty.build
+    #
+    def initialize(config = {})
+      @config = config
+    end
+
+    # Send PagerDuty a trigger event to report a new or ongoing problem. When
+    # PagerDuty receives a trigger event, it will either open a new incident, or
+    # add a new trigger log entry to an existing incident, depending on the
+    # incident key.
+    #
+    # @example Trigger an incident, providing only required details
+    #   incident = pagerduty.trigger(
+    #     summary:  "summary",
+    #     source:   "source",
+    #     severity: "critical"
+    #   )
+    #
+    # @example Trigger an incident providing full context
+    #    incident = pagerduty.trigger(
+    #      summary:        "Example alert on host1.example.com",
+    #      source:         "monitoringtool:host1.example.com/prod-003",
+    #      severity:       %w[critical error warning info].sample,
+    #      timestamp:      Time.now,
+    #      component:      "postgres",
+    #      group:          "prod-datapipe",
+    #      class:          "deploy",
+    #      custom_details: {
+    #                        ping_time: "1500ms",
+    #                        load_avg:  0.75
+    #                      },
+    #      images:         [
+    #                        {
+    #                          src:  "https://chart.googleapis.com/chart.png",
+    #                          href: "https://example.com/",
+    #                          alt:  "Example text",
+    #                        },
+    #                      ],
+    #      links:          [
+    #                        {
+    #                          href: "https://example.com/",
+    #                          text: "Link text",
+    #                        },
+    #                      ],
+    #      client:         "Sample Monitoring Service",
+    #      client_url:     "https://monitoring.example.com"
+    #    )
+    #
+    # @option details [String] summary A brief text summary of the event,
+    #   used to generate the summaries/titles of any associated alerts.
+    #   The maximum permitted length of this property is 1024 characters.
+    #
+    # @option details [String] source The unique location of the affected
+    #   system, preferably a hostname or FQDN.
+    #
+    # @option details [String] severity The perceived severity of the status
+    #   the event is describing with respect to the affected system. This can
+    #   be "critical", "error", "warning" or "info".
+    #
+    # @option details [Time] timestamp The time at which the emitting tool
+    #   detected or generated the event.
+    #
+    # @option details [String] component Component of the source machine
+    #   that is responsible for the event, for example "mysql" or "eth0".
+    #
+    # @option details [String] group Logical grouping of components of a
+    #   service, for example "app-stack".
+    #
+    # @option details [String] class The class/type of the event, for
+    #   example "ping failure" or "cpu load".
+    #
+    # @option details [Hash] custom_details Additional details about the
+    #   event and affected system
+    #
+    # @option details [Array] images List of images to include.
+    #
+    # @option details [Array] links List of links to include.
+    #
+    # @return [Pagerduty::EventsApiV2::Incident] The triggered incident.
+    #
+    # @raise [PagerdutyException] If PagerDuty responds with a status that is
+    #   not "success"
+    #
+    # @raise [ArgumentError] If details hash is nil
+    #
+    def trigger(details)
+      Incident.new(@config).trigger(details)
+    end
+
+    # @param [String] incident_key The unique identifier for the incident.
+    #
+    # @return [Pagerduty::EventsApiV2::Incident] The incident referenced by the
+    #   provided key.
+    #
+    # @raise [ArgumentError] If incident_key is nil
+    #
+    def incident(incident_key)
+      raise ArgumentError, "incident_key is nil" if incident_key.nil?
+
+      Incident.new(@config.merge(incident_key: incident_key))
+    end
+
+    class Incident
+      attr_reader :incident_key
+
+      # @option (see Pagerduty::EventsApiV1#initialize)
+      #
+      # @option config [String] incident_key Identifies the incident to which
+      #   this trigger event should be applied. If there's no open
+      #   (i.e. unresolved) incident with this key, a new one will be created.
+      #   If there's already an open incident with a matching key, this event
+      #   will be appended to that incident's log. The event key provides an
+      #   easy way to "de-dup" problem reports. If this field isn't provided,
+      #   PagerDuty will automatically open a new incident with a unique key.
+      #   The maximum length is 255 characters.
+      #
+      def initialize(config = {})
+        @integration_key = config.fetch(:integration_key) do
+          raise ArgumentError "integration_key not provided"
+        end
+        @incident_key = config[:incident_key]
+        @transport = Pagerduty::HttpTransport.new(
+          path:  "/v2/enqueue",
+          proxy: config[:http_proxy],
+        )
+      end
+
+      # Send PagerDuty a trigger event to report a new or ongoing problem. When
+      # PagerDuty receives a trigger event, it will either open a new incident,
+      # or add a new trigger log entry to an existing incident, depending on
+      # the incident key.
+      #
+      # @example Trigger an incident, providing only required details
+      #   incident = pagerduty.trigger(
+      #     summary:  "summary",
+      #     source:   "source",
+      #     severity: "critical"
+      #   )
+      #
+      # @example Trigger an incident providing full context
+      #    incident = pagerduty.trigger(
+      #      summary:        "Example alert on host1.example.com",
+      #      source:         "monitoringtool:host1.example.com/prod-003",
+      #      severity:       %w[critical error warning info].sample,
+      #      timestamp:      Time.now,
+      #      component:      "postgres",
+      #      group:          "prod-datapipe",
+      #      class:          "deploy",
+      #      custom_details: {
+      #                        ping_time: "1500ms",
+      #                        load_avg:  0.75
+      #                      },
+      #      images:         [
+      #                        {
+      #                          src:  "https://chart.googleapis.com/chart.png",
+      #                          href: "https://example.com/",
+      #                          alt:  "Example text",
+      #                        },
+      #                      ],
+      #      links:          [
+      #                        {
+      #                          href: "https://example.com/",
+      #                          text: "Link text",
+      #                        },
+      #                      ],
+      #      client:         "Sample Monitoring Service",
+      #      client_url:     "https://monitoring.example.com"
+      #    )
+      #
+      # @param (see Pagerduty::EventsApiV2#trigger)
+      # @option (see Pagerduty::EventsApiV2#trigger)
+      def trigger(details)
+        if details.key?(:dedup_key) || details.key?(:incident_key)
+          raise ArgumentError, "incident_key or dedup_key provided, "\
+                               "please use the EventsApiv2::incident method "\
+                               "to specify an incident key"
+        end
+
+        response = api_call("trigger", trigger_request(details))
+        @incident_key = response["dedup_key"]
+        self
+      end
+
+      # Acknowledge the referenced incident. While an incident is acknowledged,
+      # it won't generate any additional notifications, even if it receives new
+      # trigger events. Send PagerDuty an acknowledge event when you know
+      # someone is presently working on the problem.
+      #
+      # @return [Pagerduty::EventsApiV2::Incident] self
+      #
+      # @raise [PagerdutyException] If PagerDuty responds with a status that is
+      #   not "success"
+      #
+      def acknowledge
+        api_call("acknowledge")
+        self
+      end
+
+      # Resolve the referenced incident. Once an incident is resolved, it won't
+      # generate any additional notifications. New trigger events with the same
+      # incident_key as a resolved incident won't re-open the incident. Instead,
+      # a new incident will be created. Send PagerDuty a resolve event when the
+      # problem that caused the initial trigger event has been fixed.
+      #
+      # @return [Pagerduty::EventsApiV2::Incident] self
+      #
+      # @raise [PagerdutyException] If PagerDuty responds with a status that is
+      #   not "success"
+      #
+      def resolve
+        api_call("resolve")
+        self
+      end
+
+      private
+
+      PAYLOAD_ATTR = %i[summary timestamp source severity
+                        component group class custom_details].freeze
+      private_constant :PAYLOAD_ATTR
+
+      def trigger_request(details)
+        payload = details.select { |key| PAYLOAD_ATTR.include?(key) }
+        payload[:timestamp] &&= payload[:timestamp].iso8601
+        request = details.merge(payload: payload)
+        request.reject! { |key| PAYLOAD_ATTR.include?(key) }
+        request
+      end
+
+      def api_call(event_action, payload = {})
+        payload = payload.merge(
+          dedup_key:    incident_key,
+          routing_key:  @integration_key,
+          event_action: event_action,
+        )
+        response = @transport.send_payload(payload)
+        unless response["status"] == "success"
+          raise PagerdutyException.new(self, response, response["message"])
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/pagerduty/http_transport.rb

@@ -1,28 +1,30 @@
+# frozen_string_literal: true
 
 require "json"
 require "net/https"
 
-class Pagerduty
-  # @api private
+module Pagerduty
+  # @private
   class HttpTransport
-    HOST = "events.pagerduty.com".freeze
+    HOST = "events.pagerduty.com"
     PORT = 443
-    PATH = "/generic/2010-04-15/create_event.json".freeze
+    private_constant :HOST, :PORT
 
-    def initialize(options = {})
-      @options = options
+    def initialize(config)
+      @path = config.fetch(:path)
+      @proxy = config[:proxy] || {}
     end
 
-    def send_payload(payload = {})
-      response = post payload.to_json
+    def send_payload(payload)
+      response = post(payload.to_json)
       response.error! unless transported?(response)
       JSON.parse(response.body)
     end
 
-  private
+    private
 
     def post(payload)
-      post = Net::HTTP::Post.new(PATH)
+      post = Net::HTTP::Post.new(@path)
       post.body = payload
       http.request(post)
     end
@@ -38,10 +40,10 @@ class Pagerduty
 
     def http_proxy
       Net::HTTP.Proxy(
-        @options[:proxy_host],
-        @options[:proxy_port],
-        @options[:proxy_username],
-        @options[:proxy_password],
+        @proxy[:host],
+        @proxy[:port],
+        @proxy[:username],
+        @proxy[:password],
       )
     end
 

data/lib/pagerduty/version.rb

@@ -1,3 +1,5 @@
-class Pagerduty
-  VERSION = "2.1.1".freeze
+# frozen_string_literal: true
+
+module Pagerduty
+  VERSION = "4.0.0"
 end

data/lib/pagerduty.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
 require "pagerduty/version"
 require "pagerduty/http_transport"
+require "pagerduty/events_api_v1"
+require "pagerduty/events_api_v2"
 
 class PagerdutyException < StandardError
   attr_reader :pagerduty_instance, :api_response
@@ -11,178 +15,73 @@ class PagerdutyException < StandardError
   end
 end
 
-class Pagerduty
-  attr_reader :service_key
-
-  # @param [String] service_key The GUID of one of your "Generic API" services.
-  #   This is the "service key" listed on a Generic API's service detail page.
-  #
-  # @option options [String] :proxy_host The DNS name or IP address of the
-  #   proxy host. If nil or unprovided a proxy will not be used.
-  #
-  # @option options [String] :proxy_port The port to use to access the proxy.
-  #
-  # @option options [String] :proxy_username username if authorization is
+module Pagerduty
+  # Build an instance that will send API calls to the specified Pagerduty
+  # Events API version.
+  #
+  # @example Build an instance for the Events API version 1
+  #   pagerduty = Pagerduty.build(
+  #     integration_key: "<integration-key>",
+  #     api_version:     1,
+  #   )
+  #
+  # @example Build an instance using an HTTP proxy for API requests
+  #   pagerduty = Pagerduty.build(
+  #     integration_key: "<integration-key>",
+  #     api_version:     1,
+  #     http_proxy:      {
+  #       host:     "my.http.proxy.local",
+  #       port:     3128,
+  #       username: "<my-proxy-username>",
+  #       password: "<my-proxy-password>",
+  #     }
+  #   )
+  #
+  # @option config [String] integration_key Authentication key for connecting
+  #   to PagerDuty. A UUID expressed as a 32-digit hexadecimal number.
+  #   Integration keys are generated by creating a new service, or creating a
+  #   new integration for an existing service in PagerDuty, and can be found on
+  #   a service's Integrations tab. This option is required.
+  #
+  # @option config [String] api_version The version of the Pagerduty events API.
+  #  The gem currently supports version 1 (`1`). This option is required.
+  #
+  # @option config [String] http_proxy.host The DNS name or IP address of the
+  #   proxy host. If nil or unprovided an HTTP proxy will not be used.
+  #
+  # @option config [String] http_proxy.port The TCP port to use to access the
+  #   proxy.
+  #
+  # @option config [String] http_proxy.username username if authorization is
   #   required to use the proxy.
   #
-  # @option options [String] :proxy_password password if authorization is
+  # @option config [String] http_proxy.password password if authorization is
   #   required to use the proxy.
   #
-  def initialize(service_key, options = {})
-    @service_key = service_key
-    @transport = transport_from_options(options)
-  end
-
-  # Send PagerDuty a trigger event to report a new or ongoing problem. When
-  # PagerDuty receives a trigger event, it will either open a new incident, or
-  # add a new trigger log entry to an existing incident, depending on the
-  # provided incident_key.
-  #
-  # @param [String] description A short description of the problem that led to
-  #   this trigger. This field (or a truncated version) will be used when
-  #   generating phone calls, SMS messages and alert emails. It will also appear
-  #   on the incidents tables in the PagerDuty UI. The maximum length is 1024
-  #   characters.
-  #
-  # @option options [String] :incident_key Identifies the incident to which
-  #   this trigger event should be applied. If there's no open (i.e. unresolved)
-  #   incident with this key, a new one will be created. If there's already an
-  #   open incident with a matching key, this event will be appended to that
-  #   incident's log. The event key provides an easy way to "de-dup" problem
-  #   reports. If this field isn't provided, PagerDuty will automatically open a
-  #   new incident with a unique key.
-  #
-  # @option options [String] :client The name of the monitoring client that is
-  #   triggering this event.
-  #
-  # @option options [String] :client_url The URL of the monitoring client that
-  #   is triggering this event.
-  #
-  # @option options [Hash] :details An arbitrary hash containing any data you'd
-  #   like included in the incident log.
-  #
-  # @return [PagerdutyIncident] The triggered incident.
+  # @return [Pagerduty::EventsApiV1] the built instance.
   #
-  # @raise [PagerdutyException] If PagerDuty responds with a status that is not
-  #   "success"
+  # @raise [ArgumentError] If integration_key or api_version options are not
+  #   provided. Or if the provided api_version is unsupported.
   #
-  def trigger(description, options = {})
-    resp = api_call("trigger", options.merge(description: description))
-    ensure_success(resp)
-    PagerdutyIncident.new(
-      service_key,
-      resp["incident_key"],
-      transport: @transport,
-    )
-  end
-
-  # @param [String] incident_key The unique identifier for the incident.
-  #
-  # @return [PagerdutyIncident] The incident referenced by the key.
-  #
-  # @raise [ArgumentError] If incident_key is nil
-  #
-  def get_incident(incident_key)
-    raise ArgumentError, "incident_key is nil" if incident_key.nil?
-    PagerdutyIncident.new(
-      service_key,
-      incident_key,
-      transport: @transport,
-    )
-  end
-
-protected
-
-  def api_call(event_type, args)
-    args = args.merge(
-      service_key: service_key,
-      event_type: event_type,
-    )
-    @transport.send_payload(args)
-  end
-
-  def ensure_success(response)
-    unless response["status"] == "success"
-      raise PagerdutyException.new(self, response, response["message"])
+  def self.build(config)
+    unless config.key?(:integration_key)
+      raise ArgumentError, "integration_key not provided"
     end
-  end
-
-private
+    raise ArgumentError, "incident_key provided" if config.key?(:incident_key)
 
-  # @api private
-  def transport_from_options(options = {})
-    options[:transport] || Pagerduty::HttpTransport.new(options)
-  end
-end
-
-class PagerdutyIncident < Pagerduty
-  attr_reader :incident_key
-
-  # @param [String] service_key The GUID of one of your "Generic API" services.
-  #   This is the "service key" listed on a Generic API's service detail page.
-  #
-  # @param [String] incident_key The unique identifier for the incident.
-  #
-  def initialize(service_key, incident_key, options = {})
-    super service_key, options
-    @incident_key = incident_key
-  end
-
-  # @param (see Pagerduty#trigger)
-  # @option (see Pagerduty#trigger)
-  def trigger(description, options = {})
-    super(description, { incident_key: incident_key }.merge(options))
-  end
-
-  # Acknowledge the referenced incident. While an incident is acknowledged, it
-  # won't generate any additional notifications, even if it receives new
-  # trigger events. Send PagerDuty an acknowledge event when you know someone
-  # is presently working on the problem.
-  #
-  # @param [String] description Text that will appear in the incident's log
-  #   associated with this event.
-  #
-  # @param [Hash] details An arbitrary hash containing any data you'd like
-  #   included in the incident log.
-  #
-  # @return [PagerdutyIncident] self
-  #
-  # @raise [PagerdutyException] If PagerDuty responds with a status that is not
-  #   "success"
-  #
-  def acknowledge(description = nil, details = nil)
-    modify_incident("acknowledge", description, details)
-  end
-
-  # Resolve the referenced incident. Once an incident is resolved, it won't
-  # generate any additional notifications. New trigger events with the same
-  # incident_key as a resolved incident won't re-open the incident. Instead, a
-  # new incident will be created. Send PagerDuty a resolve event when the
-  # problem that caused the initial trigger event has been fixed.
-  #
-  # @param [String] description Text that will appear in the incident's log
-  #   associated with this event.
-  #
-  # @param [Hash] details An arbitrary hash containing any data you'd like
-  #   included in the incident log.
-  #
-  # @return [PagerdutyIncident] self
-  #
-  # @raise [PagerdutyException] If PagerDuty responds with a status that is not
-  #   "success"
-  #
-  def resolve(description = nil, details = nil)
-    modify_incident("resolve", description, details)
+    version = config.fetch(:api_version) do
+      raise ArgumentError, "api_version not provided"
+    end
+    events_api_class(version).new(config)
   end
 
-private
-
-  def modify_incident(event_type, description, details)
-    options = { incident_key: incident_key }
-    options[:description] = description if description
-    options[:details] = details if details
-    resp = api_call(event_type, options)
-    ensure_success(resp)
-    self
+  def self.events_api_class(version)
+    class_name = "Pagerduty::EventsApiV#{version}"
+    if const_defined?(class_name)
+      const_get(class_name)
+    else
+      raise ArgumentError, "api_version #{version.inspect} not supported"
+    end
   end
+  private_class_method :events_api_class
 end