Class: Pagerduty::EventsApiV1::Incident

Inherits:
Object
  • Object
show all
Defined in:
lib/pagerduty/events_api_v1.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(config) ⇒ Incident

Returns a new instance of Incident.

Parameters:

  • config (Hash)

    a customizable set of options

Options Hash (config):

  • incident_key (String)

    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.

  • integration_key (String)

    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.

  • http_proxy.host (String)

    The DNS name or IP address of the proxy host. If nil or unprovided an HTTP proxy will not be used.

  • http_proxy.port (String)

    The TCP port to use to access the proxy.

  • http_proxy.username (String)

    username if authorization is required to use the proxy.

  • http_proxy.password (String)

    password if authorization is required to use the proxy.



133
134
135
136
137
138
139
140
141
142
# File 'lib/pagerduty/events_api_v1.rb', line 133

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

Instance Attribute Details

#incident_keyObject (readonly)

Returns the value of attribute incident_key.



120
121
122
# File 'lib/pagerduty/events_api_v1.rb', line 120

def incident_key
  @incident_key
end

Instance Method Details

#acknowledge(description = nil, details = nil) ⇒ Pagerduty::EventsApiV1::Incident

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.

Examples:

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,
  }
)

Parameters:

  • description (String) (defaults to: nil)

    Text that will appear in the incident’s log associated with this event.

  • details (Hash) (defaults to: nil)

    An arbitrary hash containing any data you’d like included in the incident log.

Returns:

Raises:



218
219
220
# File 'lib/pagerduty/events_api_v1.rb', line 218

def acknowledge(description = nil, details = nil)
  modify_incident("acknowledge", description, details)
end

#resolve(description = nil, details = nil) ⇒ Pagerduty::EventsApiV1::Incident

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.

Examples:

Resolve the incident

incident.resolve

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,
  }
)

Parameters:

  • description (String) (defaults to: nil)

    Text that will appear in the incident’s log associated with this event.

  • details (Hash) (defaults to: nil)

    An arbitrary hash containing any data you’d like included in the incident log.

Returns:

Raises:



251
252
253
# File 'lib/pagerduty/events_api_v1.rb', line 251

def resolve(description = nil, details = nil)
  modify_incident("resolve", description, details)
end

#trigger(description, options = {}) ⇒ Object

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.

Examples:

Trigger or update an incident

incident.trigger(
  "<A description of the event or outage>"
)

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,
  },
)

Parameters:

  • description (String)

    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.

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

  • client (String)

    The name of the monitoring client that is triggering this event.

  • client_url (String)

    The URL of the monitoring client that is triggering this event.

  • contexts (Array)

    An array of objects. Contexts to be included with the incident trigger such as links to graphs or images.

  • details (Hash)

    An arbitrary hash containing any data you’d like included in the incident log.



178
179
180
181
182
183
184
185
186
187
188
# File 'lib/pagerduty/events_api_v1.rb', line 178

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