PagerDuty Events Client for Java

PagerDuty Events Client aims to provide a full-fledged Java client which is easy to use and integrates seamlessly with PagerDuty Events API v2. Note that the library does not integrate with PagerDuty REST Api - it is only meant for PagerDuty Events API v2. Please refer to the following link to see the differences between PagerDuty REST API and Events API:

What is the difference between PagerDuty APIs? PagerDuty APIs: Events API and REST API Using the Events API V2 to send events to PagerDuty

| |

Getting started

PagerDutyEventsClient is really easy to create. The static method exposed with no parameters will create a new client which internally will default the API calls to PagerDuty Events API (events.pagerduty.com). Please note that as per PagerDUty Events documentation there is no need to use an ApiAccessKey to make calls to the events API - the service token is sufficient to trigger/acknowledge/resolve incidents.

An example on how to create the clients is as follows:

PagerDutyEventsClient pagerDutyEventsClient = PagerDutyEventsClient.create();

The library supports the creation of Alert and Change type events. For your reference, below are examples on how to create each incident type as well as how to use PagerDutyEventsClient to perform the according operation.

Alert events

Alert type events are used to notify a problem in a machine monitored system using the trigger event. Follow up events can be sent to acknowledge or resolve an existing alert.

Examples of these alerts may include high error rate, CPU usage exceeded limit, deployment failed, etc.

Trigger:

This will send a new 'trigger' incident to PagerDuty's Alert Events Endpoint containing the details specified in the IncidentBuilder. A helper IncidentBuilder is provided for the sake of simplicity to ease with the creation of trigger incidents. The trigger event requires two mandatory parameters:

• routingKey: The GUID of one of your "Generic API" services. This is the "Integration Key" listed on a Generic API's service detail page.
• payload: The payload class contains mandatory fields that are required to trigger an event. See below to see how to construct payload field.

More details can be provided to the incident as previously mentioned by calling the available methods offered by the IncidentBuilder.

Payload:

The PagerDuty Events API v2 requires that every incident to contain a payload structure, though payload is only supported for trigger incident. The Payload can be created similar to other trigger using a builder. Below contains a list of mandatory fields to build a payload instance.

• summary: A brief text summary of the event, used to generate the summaries/titles of any associated alerts.
• source: The unique location of the affected system, preferably a hostname or FQDN.
• severity: The perceived severity of the status the event is describing with respect to the affected system. This can be Severity.CRTICAL, Severity.ERROR, Severity.WARNING, or Severity.INFO.

More details can be provided to the payload by calling the available methods offered by the Payload builder.

Payload payload = Payload.Builder.newBuilder()
        .setSummary("Summary of this incident")
        .setSource("testing host")
        .setSeverity(Severity.INFO)
        .setTimestamp(OffsetDateTime.now())
        .build();

TriggerIncident incident = TriggerIncident.TriggerIncidentBuilder
        .newBuilder("ROUTING_KEY", payload)
        .setDedupKey("DEDUP_KEY")
        .build();
pagerDutyEventsClient.trigger(incident);

Acknowledge:

This will send a new acknowledge incident to PagerDuty based upon the 'routingKey' and 'dedupKey' provided. Please note that PagerDuty does not support payload added to the acknowledge event, so by default, filler context will be used to popular the payload instance.

AcknowledgeIncident ack = AcknowledgeIncident.AcknowledgeIncidentBuilder
        .newBuilder("ROUTING_KEY", "DEDUP_KEY")
        .build();
pagerDutyEventsClient.acknowledge(ack);

Resolve:

This will send a new resolve incident to PagerDuty based upon the 'service_key' and 'dedup_key' provided. Payload is also not supported by resolve incident.

ResolveIncident resolve = ResolveIncident.ResolveIncidentBuilder
        .newBuilder("ROUTING_KEY", "DEDUP_KEY")
        .build();
pagerDutyEventsClient.resolve(resolve);

Change events

Change type events are used to notify a change in a system that does not represent a problem.

Examples may include a pull request merged, secret successfully rotated, configuration update applied, etc.

Track:

This will send a change event to PagerDuty's Change Events Endpoint and associate it with the corresponding service based on the "ROUTING_KEY" provided and including the information specified in the change event payload.

ChangeEventPayload changeEventPayload = ChangeEventPayload.Builder.
        newBuilder()
        .setSummary("Pull request merged")
        .setTimestamp(OffsetDateTime.now())
        .setCustomDetails(new JSONObject("{\"build_state\":\"passed\",\"build_number\":\"2\",\"run_time\":\"1236s\"}"))
        .build();

ChangeEvent changeEvent = ChangeEvent.ChangeEventBuilder
        .newBuilder("ROUTING_KEY", changeEventPayload)
        .build();
pagerDutyEventsClient.trackChange(changeEvent);

Integration:

PagerDuty Events Api v2 client

PagerDuty Events Client can be easily integrated in other projects by adding the following snippet to the pom:

<dependency>
  <groupId>com.github.dikhan</groupId>
  <artifactId>pagerduty-client</artifactId>
  <version>3.0.0</version>
</dependency>

The library uses SL4J facade for logging purposes. Thus, making it fully flexible for integration with other projects whereby a specific logging implementation is already being used (e,g: log4j, logback, etc).

Snapshots of dev versions can be found at oss.sonatype.org

PagerDuty Events Api v1 client

This library has evolved from supporting PagerDuty Events v1 api to support PagerDuty Events v2 in the most recent release. If you are interested in integrating with PagerDuty Events v1 you can still do so by using the last release version that supported v1:

<dependency>
  <groupId>com.github.dikhan</groupId>
  <artifactId>pagerduty-client</artifactId>
  <version>2.0.4</version>
</dependency>

Please refer to the following tag for more information about the release: pagerduty-client-2.0.4

For more information about the differentes between the different PagerDuty Events Apis refer to the following link: PagerDuty APIs: Events API and REST API

Contributing

• Fork it!
• Create your feature branch: git checkout -b my-new-feature
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request :D

Authors

Daniel I. Khan Ramiro - Cisco Systems

See also the list of contributors who participated in this project.

Acknowledgements:

• ApiService calls: http://unirest.io/java.html
• Java objects serialization: https://github.com/FasterXML/jackson
• Testing: http://www.mock-server.com/