• Stars
    star
    287
  • Rank 144,232 (Top 3 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 8 years ago
  • Updated 28 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

go client library for PagerDuty v2 API

GoDoc Go Report Card License

go-pagerduty

go-pagerduty is a CLI and go client library for the PagerDuty API.

Installation

To add the latest stable version to your project:

go get github.com/PagerDuty/[email protected]

If you instead wish to work with the latest code from main:

go get github.com/PagerDuty/go-pagerduty@latest

Usage

CLI

The CLI requires an authentication token, which can be specified in .pd.yml file in the home directory of the user, or passed as a command-line argument. Example of config file:

---
authtoken: fooBar

Commands

pd command provides a single entrypoint for all the API endpoints, with individual API represented by their own sub commands. For an exhaustive list of sub-commands, try:

pd --help

An example of the service sub-command

pd service list

Client Library

NOTICE: Breaking API Changes in v1.5.0

As part of the v1.5.0 release, we have fixed features that have never worked correctly and require a breaking API change to fix. One example is the issue reported in #232, as well as a handful of other examples within the v1.5.0 milestone.

If you are impacted by a breaking change in this release, you should audit the functionality you depended on as it may not have been working. If you cannot upgrade for some reason, the v1.4.x line of releases should still work. At the time of writing v1.4.3 was the latest, and we intend to backport any critical fixes for the time being.

Example Usage

package main

import (
	"fmt"
	"github.com/PagerDuty/go-pagerduty"
)

var	authtoken = "" // Set your auth token here

func main() {
	var opts pagerduty.ListEscalationPoliciesOptions
	client := pagerduty.NewClient(authtoken)
	eps, err := client.ListEscalationPolicies(opts)
	if err != nil {
		panic(err)
	}
	for _, p := range eps.EscalationPolicies {
		fmt.Println(p.Name)
	}
}

The PagerDuty API client also exposes its HTTP client as the HTTPClient field. If you need to use your own HTTP client, for doing things like defining your own transport settings, you can replace the default HTTP client with your own by simply by setting a new value in the HTTPClient field.

API Error Responses

For cases where your request results in an error from the API, you can use the errors.As() function from the standard library to extract the pagerduty.APIError error value and inspect more details about the error, including the HTTP response code and PagerDuty API Error Code.

package main

import (
	"fmt"
	"github.com/PagerDuty/go-pagerduty"
)

var	authtoken = "" // Set your auth token here

func main() {
	client := pagerduty.NewClient(authtoken)
	user, err := client.GetUser("NOTREAL", pagerduty.GetUserOptions{})
	if err != nil {
		var aerr pagerduty.APIError

		if errors.As(err, &aerr) {
			if aerr.RateLimited() {
				fmt.Println("rate limited")
				return
			}

			fmt.Println("unknown status code:", aerr.StatusCode)

			return
		}

		panic(err)
	}
	fmt.Println(user)
}

Extending and Debugging Client

Extending The Client

The *pagerduty.Client has a Do method which allows consumers to wrap the client, and make their own requests to the PagerDuty API. The method signature is similar to that of the http.Client.Do method, except it also includes a bool to incidate whether the API endpoint is authenticated (i.e., the REST API). When the API is authenticated, the client will annotate the request with the appropriate headers to be authenticated by the API.

If the PagerDuty client doesn't natively expose functionality that you wish to use, such as undocumented JSON fields, you can use the Do() method to issue your own request that you can parse the response of.

Likewise, you can use it to issue requests to the API for the purposes of debugging. However, that's not the only mechanism for debugging.

Debugging the Client

The *pagerduty.Client has a method that allows consumers to enable debug functionality, including interception of PagerDuty API responses. This is done by using the SetDebugFlag() method using the pagerduty.DebugFlag unsigned integer type. There are also exported constants to help consumers enable specific debug behaviors.

Capturing Last PagerDuty Response

If you're not getting the response you expect from the PagerDuty Go client, you can enable the DebugCaptureLastResponse debug flag to capture the HTTP responses. You can then use one of the methods to make an API call, and then inspect the API response received. For example:

client := pagerduty.NewClient("example")

client.SetDebugFlag(pagerduty.DebugCaptureLastResponse)

oncalls, err := client.ListOnCallsWithContext(ctx, pagerduty.ListOnCallOptions{})

resp, ok := client.LastAPIResponse()
if ok { // resp is an *http.Response we can inspect
	body, err := httputil.DumpResponse(resp, true)
    // ...
}

Included Packages

webhookv3

Support for V3 of PagerDuty Webhooks is provided via the webhookv3 package. The intent is for this package to provide signature verification and decoding helpers.

Contributing

  1. Fork it ( https://github.com/PagerDuty/go-pagerduty/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

License

Apache 2

More Repositories

1

incident-response-docs

PagerDuty's Incident Response Documentation.
Dockerfile
1,020
star
2

security-training

Public version of PagerDuty's employee security training courses.
Shell
409
star
3

scheduler

A Scala library for scheduling arbitrary code to run at an arbitrary time.
Scala
214
star
4

terraform-provider-pagerduty

Terraform PagerDuty provider
Go
203
star
5

blender

A modular orchestration engine
Ruby
183
star
6

pdpyras

Low-level PagerDuty REST/Events API client for Python
Python
131
star
7

pd-oncall-chat-topic

AWS Lambda Function that updates a Chat Room topic (eg, Slack)
Python
86
star
8

public-support-scripts

Python
85
star
9

pagerduty-api-python-client

A python client for PagerDuty's API, v2.0+
Python
81
star
10

postmortem-docs

PagerDuty's Public Postmortem Documentation
Dockerfile
66
star
11

chrome-notifier

Google Chrome extension for PagerDuty desktop notifications.
JavaScript
60
star
12

pdjs

JavaScript wrapper for the PagerDuty API
TypeScript
59
star
13

API_Python_Examples

Examples of using the REST API endpoints in Python
Python
50
star
14

pdagent

The PagerDuty Agent is a program that lets you easily integrate your monitoring system with PagerDuty.
Python
33
star
15

api-schema

PagerDuty OpenAPI schemas
30
star
16

lita-pagerduty

A PagerDuty plugin for Lita
Ruby
25
star
17

backstage-plugin

PagerDuty plugin for Backstage
TypeScript
25
star
18

full-service-ownership-docs

PagerDuty's Full Service Ownership Documentation
Dockerfile
22
star
19

cronner

cron job runner; statsd metrics with optional DogStatsd event emissions
Go
20
star
20

operational-review-docs

PagerDuty's public operational review documentation.
Dockerfile
20
star
21

pagerduty-zabbix-py

Zabbix Integration for PagerDuty via Python Wrapper
Python
15
star
22

dnsmetrics

DNSmetrics connects to your accounts at multiple managed DNS providers using their APIs and emits standardized metrics in statsd format for easy ingestion into your monitoring solution of choice.
Go
14
star
23

devsecops-docs

DevSecOps Guide, located devsecops.pagerduty.com
Dockerfile
13
star
24

chef_example

This is a snapshot of the way we organized our Chef repo at the end of 2013, referenced by a PagerDuty Blog post.
Ruby
12
star
25

pdagent-integrations

Shell
12
star
26

go-pdagent

A new PagerDuty agent.
Go
11
star
27

pagerduty-nagios-pl

Nagios Integration for PagerDuty via Perl Wrapper
Perl
11
star
28

developer-docs

PagerDuty's developer documentation
11
star
29

PD-IP-Checker

Shell
9
star
30

pd-sync-chef

A knife plugin that supports the PagerDuty Chef workflow
Ruby
9
star
31

retrospectives-docs

PagerDuty's Retrospectives Documentation.
Dockerfile
9
star
32

blender-chef

Chef search based host discovery for blender.
Ruby
9
star
33

pagerduty-change-events-action

A GitHub action that creates a PagerDuty change event.
JavaScript
9
star
34

chef-sumologic

Recipe for an unattended install of Sumo Logic's sumocollector via chef
Ruby
9
star
35

stakeholder-comms-docs

PagerDuty's Stakeholder Communications Documentation.
Dockerfile
9
star
36

business-response-docs

PagerDuty's Business Incident Response Documentation -
Dockerfile
8
star
37

automated-remediation-docs

PagerDuty's Automated Remediation Ops Guide Docs
Dockerfile
7
star
38

mixduty

An elixir client for PagerDuty's API v2
Elixir
7
star
39

goingoncall-docs

Repository for the Best Practices for On Call Teams Ops Guide
Dockerfile
7
star
40

SwiftCompactCalendar

A compact calendar view for managing dates of a Calendar in Swift.
Swift
6
star
41

API_Ruby_Examples

Examples of using the REST API endpoints in Ruby
Ruby
6
star
42

API_PHP_Examples

Examples of using the PagerDuty API endpoints in PHP
PHP
5
star
43

full-case-ownership-docs

PagerDuty's Ops Guide for Customer Service Operations and Full Case Ownership
Dockerfile
5
star
44

ZenPacks.PagerDuty.APINotification

PagerDuty's Zenoss Zenpack
Python
4
star
45

chef-search-stresser

A utility in Go to stress a chef-server with wide searches
Go
4
star
46

mkdocs-theme-pagerduty

A custom MkDocs theme for all our public Ops Guide websites.
CSS
3
star
47

backstage-plugin-backend

PagerDuty plugin for Backstage - Backend
TypeScript
3
star
48

twitter-trend-alert-system

Python
3
star
49

app-documentation-templates

This is a public repository of documentation templates which PagerDuty app and integration builders can use to document what they build.
3
star
50

backstage-plugin-scaffolder-actions

Backstage scaffolder actions for PagerDuty
TypeScript
2
star
51

pd-bizops-aether

salesforce to redshift replication
Ruby
2
star
52

backstage-plugin-common

This project exposes common types and objects to PagerDuty's frontend and backend plugins for Backstage
TypeScript
2
star
53

postincident-howie-docs

Dockerfile
2
star
54

state-history-validator

Ruby
2
star
55

pagerduty-icinga-pl

Icinga Integration for PagerDuty via Perl Wrapper
Perl
2
star
56

interview-skeleton

Public sample code for a variety of languages for the API interview coding exercise
Elixir
1
star
57

scom-powershell-integration

PowerShell
1
star
58

plug_datadog_stats

Elixir
1
star
59

interview-java-skeleton

Java
1
star
60

security-hub-cloudformation

Contains PagerDuty's CloudFormation Template for Security Hub Integration
1
star
61

pd-feature-cookbook

This is a library cookbook that adds support for rule-based feature flags to Chef recipes.
Ruby
1
star
62

whazzup

A health check daemon for datastore services (MySQL, Zookeeper) that exposes health as an HTTP endpoint.
Ruby
1
star
63

cookbooks-vagrant-ohai

Ohai plugin for improvements to Vagrant network addresses. Forked from bryanwb/cookbooks-vagrant-ohai
Ruby
1
star
64

backstage-plugin-docs

Documentation for PagerDuty plugin for Backstage
HTML
1
star
65

servicenow-updatesets

This repo contains update sets to be used with creating Clone Data Preservers in ServiceNow. These are compatible with versions 5 and 6 of the PagerDuty app.
1
star