Class: Pagerduty::EventsApiV2

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

Overview

Trigger incidents via the PagerDuty Events API version 2.

See Also:

Defined Under Namespace

Classes: Incident

Instance Method Summary collapse

Constructor Details

#initialize(config = {}) ⇒ EventsApiV2

Rather than using this directly, use the Pagerduty.build method to construct an instance.

Parameters:

  • config (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (config):

  • 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.

See Also:



39
40
41
 
# File 'lib/pagerduty/events_api_v2.rb', line 39

def initialize(config = {})
  @config = config
end

Instance Method Details

#incident(incident_key) ⇒ Pagerduty::EventsApiV2::Incident

Returns The incident referenced by the provided key.

Parameters:

  • incident_key (String) —

    The unique identifier for the incident.

Returns:

Raises:

  • (ArgumentError) —

    If incident_key is nil



133
134
135
136
137
 
# 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) ⇒ Pagerduty::EventsApiV2::Incident

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.

Examples:

Trigger an incident, providing only required details

incident = pagerduty.trigger(
  summary:  "summary",
  source:   "source",
  severity: "critical"
)

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"
)

Parameters:

  • details (Hash) —

    a customizable set of options

Options Hash (details):

  • summary (String) —

    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.

  • source (String) —

    The unique location of the affected system, preferably a hostname or FQDN.

  • severity (String) —

    The perceived severity of the status the event is describing with respect to the affected system. This can be “critical”, “error”, “warning” or “info”.

  • timestamp (Time) —

    The time at which the emitting tool detected or generated the event.

  • component (String) —

    Component of the source machine that is responsible for the event, for example “mysql” or “eth0”.

  • group (String) —

    Logical grouping of components of a service, for example “app-stack”.

  • class (String) —

    The class/type of the event, for example “ping failure” or “cpu load”.

  • custom_details (Hash) —

    Additional details about the event and affected system

  • images (Array) —

    List of images to include.

  • links (Array) —

    List of links to include.

Returns:

Raises:

  • (PagerdutyException) —

    If PagerDuty responds with a status that is not “success”

  • (ArgumentError) —

    If details hash is nil



122
123
124
 
# File 'lib/pagerduty/events_api_v2.rb', line 122

def trigger(details)
  Incident.new(@config).trigger(details)
end