class Pagerduty::EventsApiV2

Trigger incidents via the PagerDuty Events API version 2.

@see v2.developer.pagerduty.com/docs/events-api-v2 PagerDuty Events

API V2 documentation

@see Pagerduty.build

@see Pagerduty::EventsApiV2::Incident

Public Class Methods

new(config = {}) click to toggle source

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

# File lib/pagerduty/events_api_v2.rb, line 39
def initialize(config = {})
  @config = config
end

Public Instance Methods

incident(incident_key) click to toggle source

@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

# File lib/pagerduty/events_api_v2.rb, line 133
def incident(incident_key)
  raise ArgumentError, "incident_key is nil" if incident_key.nil?

  Incident.new(@config.merge(incident_key: incident_key))
end
trigger(details) click to toggle source

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

# File lib/pagerduty/events_api_v2.rb, line 122
def trigger(details)
  Incident.new(@config).trigger(details)
end