NAME

PagerDuty::Agent - A perl PagerDuty client

VERSION

Version 0.02

SYNOPSIS

  use PagerDuty::Agent;

  my $agent = PagerDuty::Agent->new( routing_key => '3fcc9112463424b599f996f9e780dfc6' );

  # trigger an event, then resolve it
  my $dedup_key = $agent->trigger_event( 'something is terribly wrong!' );

  if ( $dedup_key ) {
    print "Event created, dedup_key = $dedup_key\n";

    print "Event successfully resolved\n"
      if $agent->resolve_event( $dedup_key );
  } else {
    warn "Failed to submit event: $@\n";
  }

  # additional context can be passed in
  $agent->trigger_event(
    summary   => 'something is terribly wrong!',
    severity  => 'critical',
    dedup_key => 'abc123',
  );

DESCRIPTION

This module implements the Events API for submitting events to PagerDuty.

CONSTRUCTOR

my $agent = PagerDuty::Agent->new( %options )

routing_key => '3fcc9112463424b599f996f9e780dfc6'

The routing key or integration key associated with the API integration, found when viewing the service integration on the PagerDuty site.

timeout => 5

Do not wait longer than this number of seconds when attempting to send an event.

api_version => 2

Only version 2 is supported.

EVENT API

These methods are designed to create and manipulate events.

my $dedup_key = $agent->trigger_event( $event_summary or %event )

Trigger an event. The simple form accepts an $event_summary string with textual details of the event. The long form accepts additional event context.

When successful, returns the dedup_key. On error, returns undef and sets $@.

Event parameters when using the long form:

summary => 'Server is on fire'

Required. A textual description of the event.

class => 'cpu load'

The type of event.

component => 'mysql'

The mechanism responsible for the event.

custom_details => { user => 'me' }

A hash-ref of key value pairs containing any additional details.

dedup_key => 'my unique identifier'

This is used for threading like events as well as identifying events already triggered. If this is not given, one will be generated by the upstream API.

group => 'app-stack'

The grouping of components.

images => [ { src => 'https://img.memecdn.com/silly-humans_o_842106.jpg' } ]

One or more images, each specified as a hash-ref containing:

src => 'image url'

Required. Must be HTTPS.

href => 'link url'

Make the image link click-able.

alt => 'some alt text'

Add alt text to the image.

links => [ { text => 'see the docs', href => 'https://google.com' } ]

One or more links, each specified as a hash-ref containing:

href => 'https://google.com'

Required. Link destination.

text => 'click here'

Required. Link text.

severity => 'error'

The severity of the event. Can be one of critical, error, warning, or info. Defaults to error.

source => 'google.com'

The hostname from which this event was triggered. Defaults to the current hostname.

timestamp => '2017-07-12T12:50:22.000-0700'

The event timestamp. This must be a valid ISO 8601 in the complete long form such as the example. This defaults to the current local time.

my $success = $agent->acknowledge_event( $dedup_key or %event )

Acknowledge an existing event. The simple form accepts a $dedup_key. The long form accepts the same event parameters as trigger_event except summary is interpreted as the reason for acknowledging and dedup_key is required.

When successful, returns the dedup_key. On error, returns undef and sets $@.

my $success = $agent->resolve_event( $dedup_key or %event )

This accepts the same parameters as acknowledge_event and returns the same values.

See Also

https://v2.developer.pagerduty.com/docs/events-api-v2 - The PagerDuty Events V2 API documentation

WebService::PagerDuty - Another module implementing most of the PagerDuty Events V1 API.

LICENSE

Copyright (C) 2019 by Matt Harrington

The full text of this license can be found in the LICENSE file included with this module.