pagerduty 2.1.1 → 4.0.0

data/README.md

@@ -1,12 +1,14 @@
 # pagerduty
 
+[![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/envato/pagerduty/blob/HEAD/LICENSE.txt)
+[![Gem Version](https://img.shields.io/gem/v/pagerduty.svg?maxAge=2592000)](https://rubygems.org/gems/pagerduty)
+[![Gem Downloads](https://img.shields.io/gem/dt/pagerduty.svg?maxAge=2592000)](https://rubygems.org/gems/pagerduty)
+[![Build Status](https://github.com/envato/pagerduty/workflows/build/badge.svg?branch=main)](https://github.com/envato/pagerduty/actions?query=workflow%3Abuild+branch%3Amain)
 
-[![License MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/envato/pagerduty/blob/master/LICENSE.txt)
-[![Gem Version](https://badge.fury.io/rb/pagerduty.svg)](http://badge.fury.io/rb/pagerduty)
-[![Build Status](https://travis-ci.org/envato/pagerduty.svg?branch=master)](https://travis-ci.org/envato/pagerduty)
+Provides a lightweight Ruby interface for calling the [PagerDuty Events
+API][events-v2-docs].
 
-Provides a lightweight Ruby interface for calling the [PagerDuty
-Integration API](http://developer.pagerduty.com/documentation/integration/events).
+[events-v2-docs]: https://developer.pagerduty.com/docs/ZG9jOjExMDI5NTgw-events-api-v2-overview
 
 ## Installation
 
@@ -26,58 +28,178 @@ Or install it yourself as:
 
 ## Usage
 
+First, obtain an Events API integration key from PagerDuty. Follow the
+[instructions][integration-key-documentation] in PagerDuty's documentation to
+procure one.
+
+[integration-key-documentation]: https://support.pagerduty.com/docs/services-and-integrations#create-a-generic-events-api-integration
+
+
+### Events API V2
+
 ```ruby
-# Don't forget to require the library
-require "pagerduty"
+# Instantiate a Pagerduty service object providing an integration key and the
+# desired API version: 2
+pagerduty = Pagerduty.build(
+  integration_key: "<integration-key>",
+  api_version:     2
+)
 
-# Instantiate a Pagerduty with your specific service key
-pagerduty = Pagerduty.new("<my-service-key>")
+# Trigger an incident providing minimal details
+incident = pagerduty.trigger(
+  summary:  "summary",
+  source:   "source",
+  severity: "critical"
+)
 
-# Trigger an incident
-incident = pagerduty.trigger("incident description")
+# Trigger an incident providing full context
+incident = pagerduty.trigger(
+  summary:        "Example alert on host1.example.com",
+  source:         "monitoringtool:cloudvendor:central-region-dc-01:852559987:cluster/api-stats-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://www.pagerduty.com/wp-content/uploads/2016/05/pagerduty-logo-green.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"
+)
 
 # Acknowledge and/or resolve the incident
 incident.acknowledge
 incident.resolve
 
-# Acknowledge and/or resolve an existing incident
-incident = pagerduty.get_incident("<unique-incident-key>")
+# Provide a client-defined incident key
+# (this can be used to update existing incidents)
+incident = pagerduty.incident("<incident-key>")
+incident.trigger(
+  summary:  "summary",
+  source:   "source",
+  severity: "critical"
+)
 incident.acknowledge
 incident.resolve
 ```
 
-There are a whole bunch of properties you can send to PagerDuty when triggering
-an incident. See the [PagerDuty
-documentation](http://developer.pagerduty.com/documentation/integration/events/trigger)
-for the specifics.
+See the [PagerDuty Events API V2 documentation][events-v2-docs] for a
+detailed description on the parameters you can send when triggering an
+incident.
+
+### Events API V1
+
+The following code snippet shows how to use the [Pagerduty Events API version
+1](https://v2.developer.pagerduty.com/docs/events-api).
 
 ```ruby
-pagerduty.trigger(
-  "incident description",
-  incident_key: "my unique incident identifier",
-  client:       "server in trouble",
-  client_url:   "http://server.in.trouble",
-  details:      { my: "extra details" }
+# Instantiate a Pagerduty with a service integration key
+pagerduty = Pagerduty.build(
+  integration_key: "<integration-key>",
+  api_version:     1,
+)
+
+# Trigger an incident
+incident = pagerduty.trigger(
+  "FAILURE for production/HTTP on machine srv01.acme.com",
+)
+
+# Trigger an incident providing context and details
+incident = pagerduty.trigger(
+  "FAILURE for production/HTTP on machine srv01.acme.com",
+  client:     "Sample Monitoring Service",
+  client_url: "https://monitoring.service.com",
+  contexts:   [
+    {
+      type: "link",
+      href: "http://acme.pagerduty.com",
+      text: "View the incident on PagerDuty",
+    },
+    {
+      type: "image",
+      src:  "https://chart.googleapis.com/chart?chs=600x400&chd=t:6,2,9,5,2,5,7,4,8,2,1&cht=lc&chds=a&chxt=y&chm=D,0033FF,0,0,5,1",
+    }
+  ],
+  details:    {
+    ping_time: "1500ms",
+    load_avg:  0.75,
+  },
+)
+
+# Acknowledge the incident
+incident.acknowledge
+
+# Acknowledge, providing a description and extra details
+incident.acknowledge(
+  "Engineers are investigating the incident",
+  {
+    ping_time: "1700ms",
+    load_avg:  0.71,
+  }
 )
+
+# Resolve the incident
+incident.resolve
+
+# Resolve, providing a description and extra details
+incident.acknowledge(
+  "A fix has been deployed and the service has recovered",
+  {
+    ping_time: "120ms",
+    load_avg:  0.23,
+  }
+)
+
+# Provide a client defined incident key
+# (this can be used to update existing incidents)
+incident = pagerduty.incident("<incident-key>")
+incident.trigger("Description of the event")
+incident.acknowledge
+incident.resolve
 ```
 
+See the [PagerDuty Events API V1
+documentation](https://v2.developer.pagerduty.com/docs/trigger-events) for a
+detailed description of the parameters you can send when triggering an
+incident.
+
 ### HTTP Proxy Support
 
 One can explicitly define an HTTP proxy like this:
 
 ```ruby
-# Instantiate a Pagerduty with your specific service key and proxy details
-pagerduty = Pagerduty.new(
-  "<my-service-key>",
-  proxy_host: "my.http.proxy.local",
-  proxy_port: 3128,
-  proxy_username: "<my-proxy-username>",
-  proxy_password: "<my-proxy-password>",
+pagerduty = Pagerduty.build(
+  integration_key: "<integration-key>",
+  api_version:     2, # The HTTP proxy settings work with either API version
+  http_proxy:      {
+    host:     "my.http.proxy.local",
+    port:     3128,
+    username: "<my-proxy-username>",
+    password: "<my-proxy-password>",
+  }
 )
 
-# Then proceed to trigger your incident
-# (sends the request to PagerDuty via the HTTP proxy)
-incident = pagerduty.trigger("incident description")
+# Subsequent API calls will then be sent via the HTTP proxy
+incident = pagerduty.trigger(
+  summary:  "summary",
+  source:   "source",
+  severity: "critical"
+)
 ```
 
 ### Debugging Error Responses
@@ -87,38 +209,18 @@ go about debugging these unhappy cases:
 
 ```ruby
 begin
-  pagerduty.trigger("incident description")
-rescue Net::HTTPServerException => error
+  pagerduty.trigger(
+    summary:  "summary",
+    source:   "source",
+    severity: "critical"
+  )
+rescue Net::HTTPClientException => error
   error.response.code    #=> "400"
   error.response.message #=> "Bad Request"
   error.response.body    #=> "{\"status\":\"invalid event\",\"message\":\"Event object is invalid\",\"errors\":[\"Service key is the wrong length (should be 32 characters)\"]}"
 end
 ```
 
-### Upgrading to Version 2.0.0
-
-The API has changed in three ways that you need to be aware of:
-
-1. `Pagerduty` class initialiser no longer accepts an `incident_key`. This
-attribute can now be provided when calling the `#trigger` method (see above).
-
-2. `Pagerduty#trigger` arguments have changed to accept all available options
-rather than just details.
-
-    ```ruby
-    # This no longer works post v2.0.0. If you're
-    # providing details in this form, please migrate.
-    pagerduty.trigger("desc", key: "value")
-
-    # Post v2.0.0 this is how to send details (migrate to this please).
-    pagerduty.trigger("desc", details: { key: "value" })
-    ```
-
-3. `PagerdutyException` now extends from `StandardError` rather than
-`Exception`. This may affect how you rescue the error. i.e. `rescue
-StandardError` will now rescue a `PagerdutyException` where it did not
-before.
-
 ## Contributing
 
 1. Fork it ( https://github.com/envato/pagerduty/fork )

data/lib/pagerduty/events_api_v1.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+module Pagerduty
+  # Trigger incidents via the PagerDuty Events API version 1.
+  #
+  # @see https://v2.developer.pagerduty.com/docs/events-api PagerDuty Events
+  #   API V1 documentation
+  #
+  # @see Pagerduty.build
+  #
+  # @see Pagerduty::EventsApiV1::Incident
+  #
+  class EventsApiV1
+    # 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.
+    #
+    # @example Trigger an incident
+    #   incident = pagerduty.trigger(
+    #     "<A description of the event or outage>"
+    #   )
+    #
+    # @example Trigger an incident, providing more context and details
+    #   incident = pagerduty.trigger(
+    #     "FAILURE for production/HTTP on machine srv01.acme.com",
+    #     client:     "Sample Monitoring Service",
+    #     client_url: "https://monitoring.service.com",
+    #     contexts:   [
+    #       {
+    #         type: "link",
+    #         href: "http://acme.pagerduty.com",
+    #         text: "View the incident on PagerDuty",
+    #       },
+    #       {
+    #         type: "image",
+    #         src:  "https://chart.googleapis.com/chart.png",
+    #       }
+    #     ],
+    #     details:    {
+    #       ping_time: "1500ms",
+    #       load_avg:  0.75,
+    #     },
+    #   )
+    #
+    # @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] 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 [Array] contexts An array of objects. Contexts to be
+    #   included with the incident trigger such as links to graphs or images.
+    #
+    # @option options [Hash] details An arbitrary hash containing any data you'd
+    #   like included in the incident log.
+    #
+    # @return [Pagerduty::EventsApiV1::Incident] The triggered incident.
+    #
+    # @raise [PagerdutyException] If PagerDuty responds with a status that is
+    #   not "success"
+    #
+    def trigger(description, options = {})
+      config = @config.merge(incident_key: options[:incident_key])
+      options = options.reject { |key| key == :incident_key }
+      Incident.new(config).trigger(description, options)
+    end
+
+    # @param [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.
+    #
+    # @return [Pagerduty::EventsApiV1::Incident] The incident referenced by the
+    #   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:  "/generic/2010-04-15/create_event.json",
+          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
+      # provided incident_key.
+      #
+      # @example Trigger or update an incident
+      #   incident.trigger(
+      #     "<A description of the event or outage>"
+      #   )
+      #
+      # @example Trigger or update an incident, providing more context
+      #   incident.trigger(
+      #     "FAILURE for production/HTTP on machine srv01.acme.com",
+      #     client:     "Sample Monitoring Service",
+      #     client_url: "https://monitoring.service.com",
+      #     contexts:   [
+      #       {
+      #         type: "link",
+      #         href: "http://acme.pagerduty.com",
+      #         text: "View the incident on PagerDuty",
+      #       },
+      #       {
+      #         type: "image",
+      #         src:  "https://chart.googleapis.com/chart.png",
+      #       }
+      #     ],
+      #     details:    {
+      #       ping_time: "1500ms",
+      #       load_avg:  0.75,
+      #     },
+      #   )
+      #
+      # @param (see Pagerduty::EventsApiV1#trigger)
+      # @option (see Pagerduty::EventsApiV1#trigger)
+      def trigger(description, options = {})
+        if options.key?(:incident_key)
+          raise ArgumentError, "incident_key provided"
+        end
+
+        options = options.merge(description: description)
+        options[:incident_key] = @incident_key unless @incident_key.nil?
+        response = api_call("trigger", options)
+        @incident_key = response["incident_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.
+      #
+      # @example Acknowledge the incident
+      #   incident.acknowledge
+      #
+      # @example Acknowledge, providing a description and extra details
+      #   incident.acknowledge(
+      #     "Engineers are investigating the incident",
+      #     {
+      #       ping_time: "1700ms",
+      #       load_avg:  0.71,
+      #     }
+      #   )
+      #
+      # @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 [Pagerduty::EventsApiV1::Incident] 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.
+      #
+      # @example Resolve the incident
+      #   incident.resolve
+      #
+      # @example Resolve, providing a description and extra details
+      #   incident.resolve(
+      #     "A fix has been deployed and the service has recovered",
+      #     {
+      #       ping_time: "130ms",
+      #       load_avg:  0.23,
+      #     }
+      #   )
+      #
+      # @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 [Pagerduty::EventsApiV1::Incident] self
+      #
+      # @raise [PagerdutyException] If PagerDuty responds with a status that is
+      #   not "success"
+      #
+      def resolve(description = nil, details = nil)
+        modify_incident("resolve", description, details)
+      end
+
+      private
+
+      def modify_incident(event_type, description, details)
+        options = { incident_key: incident_key }
+        options[:description] = description if description
+        options[:details] = details if details
+        api_call(event_type, options)
+        self
+      end
+
+      def api_call(event_type, args)
+        args = args.merge(
+          service_key: @integration_key,
+          event_type:  event_type,
+        )
+        response = @transport.send_payload(args)
+        unless response["status"] == "success"
+          raise PagerdutyException.new(self, response, response["message"])
+        end
+
+        response
+      end
+    end
+  end
+end