Note: This project is currently in beta, for the current Python-based agent see: https://github.com/PagerDuty/pdagent

PagerDuty Agent

An agent daemon to aid in creating PagerDuty events.

Goals of this project include providing:

• A command-line interface for creating PagerDuty events.
• A local entry point for PagerDuty's Events API.
• Ensuring that events are properly ordered for each integration.
• Handling back pressure or when PagerDuty is inaccessible.

If you're looking for a more comprehensive PagerDuty API Go client library and CLI, see: https://github.com/PagerDuty/go-pagerduty

About this fork

This is CU Boulder OIT Platform Engineering's fork of PagerDuty/go-pdagent, maintained to route Naemon alerts into PagerDuty. Upstream's last release was v0.5.1 in August 2021.

Changes made relative to upstream, per Apache License 2.0 section 4(b):

• Events API v2 for the Nagios integration. Upstream's Nagios integration is hardcoded to EventV1, so incidents carry no dedup key and a RECOVERY cannot resolve the incident its PROBLEM opened. v2 is now the default, with a stable dedup_key, severity mapping, and client_url for a link back to the monitoring UI. --events-api-version=1 restores the previous behaviour, and --service-key / --incident-key remain as deprecated aliases. This addresses upstream issue #34.
• Modernized toolchain and dependencies. Upstream pinned go 1.13 with a 2020-era dependency set that govulncheck reported as 25 reachable vulnerabilities.
• Release config ported to goreleaser v2. The v0.x config is rejected by current goreleaser, so no packages could be built at all.
• CI added. See below.

Installation

Binaries for our officially supported platforms can be found on the releases page.

Usage

On first run we recommend running pdagent init to generate a default config file. By default this file will live in ~/.pdagent along with any other artifacts.

Once the config has been created, to start the daemon:

pdagent server

There are a number of other commands available that are listed as part of the command's help command:

pdagent help

Perhaps the most common command, sending events:

pdagent enqueue \
  -k your_key_goes_here \
  -t trigger \
  -d "This is only a test" \
  -u "http://pagerduty.com" \
  -e "error" \
  -f some_field=some_value

Architecture

At a high level, the agent has three key components:

• Server: The daemon itself where most of the heavy lifting occurs.
• Client: An HTTP client to simplify making requests against the server.
• CLI: A command line tool for working with both the server and client commands.

Development

Looking to contribute? See development for some helpful tips.

Build Pipeline

build.yml runs on every push:

test ── build-packages ── verify-package ── publish (tags only)

• test — go build, go vet, go test, and govulncheck. The vulnerability gate is deliberate: clearing 25 reachable CVEs is why this fork moved off the original dependency set, and we want to know if that regresses.
• build-packages — goreleaser snapshot build, producing RPMs, DEBs and tarballs as workflow artifacts.
• verify-package — asserts the packaged binary path matches the path the systemd unit and wrapper scripts actually invoke. goreleaser v2 defaults nfpm's bindir to /usr/bin while everything here expects /usr/local/bin; when those disagree the RPM installs cleanly and then fails to start, which is easy to miss without an explicit check.
• publish — runs only on tag pushes, and creates a GitHub Release with the built artifacts attached.

Packages are not GPG signed.

How to Release

Tags must be semver for goreleaser to derive a version. Use a -cu.N suffix so CU builds are distinguishable from upstream releases.

Bump the version above the upstream tag you diverged from. A -cu.N suffix is a semver prerelease identifier, so v0.5.1-cu.1 sorts below upstream's v0.5.1 — which would misrepresent a build that is v0.5.1 plus everything in this fork. Tagging v0.6.0-cu.1 instead sorts above it and, since this fork added Events API v2 support, a minor bump is the honest description anyway.

1. Create a branch, make your changes, push and iterate until CI is green.
2. Merge your PR into main.
3. Tag and push from main:

git checkout main
git pull
git tag v0.6.0-cu.1
git push origin v0.6.0-cu.1

4. Watch Actions to confirm the build and publish succeed.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Third-Party Dependencies

This project includes third-party software components with different licenses. See THIRD-PARTY-LICENSES.md for complete attribution.