PagerDuty

Bigeye's PagerDuty integration keeps a Bigeye issue and a PagerDuty incident in step in both
directions. When an issue opens, Bigeye creates an incident on your service with the metric context,
thresholds, and query that triggered it. From then on, whichever side someone works in, the other
follows: status, comments, assignee, and threshold feedback all sync.

Setup

Setup is done once per Bigeye workspace. Steps 1–3 are yours; step 4 hands off to Bigeye, which
provisions the reverse-sync connection for you — you never have to create a webhook or handle a signing
secret.

Allow about 20 minutes. You need admin access in PagerDuty (to create an incident type and register
an app) and a PagerDuty plan that includes incident custom fields (Business or higher).

Step 1 — Create the Bigeye incident type and its custom fields

Bigeye writes four custom fields onto the incidents it creates. They live on a dedicated incident
type so they appear only on Bigeye incidents and not on every incident in your account.

In PagerDuty, go to Incidents → Settings → Incident Types and create a type named Bigeye Incident. Then add these four custom fields to it:

Use the field names exactly as written — the integration looks them up by name. The option values on the two select fields must match exactly too.

This step cannot be automated. PagerDuty does not allow an installed app to create incident types,
so an admin has to do it in the UI. Everything else is handled for you.

Step 2 — Register Bigeye as an app in PagerDuty

Go to Integrations → App Registration → New App, give it a name (for example Bigeye), and add the
Scoped OAuth functionality with these permissions:

• Incidents — read and write
• Incident Types — read
• Priorities — read
• Users — read
• Webhook Subscriptions — read and write

Save, then copy the Client ID and Client Secret. The secret is shown once.

The first four permissions are what the running integration uses. Webhook Subscriptions is used only
once, during step 4, to create the reverse-sync connection on your behalf; the integration does not use
it afterwards.

Step 3 — Collect the remaining details

• Account URL — https://<your-subdomain>.pagerduty.com
• Service ID — open the PagerDuty service you want Bigeye incidents on. The ID is the P… value in
  the page URL. All Bigeye incidents for this workspace are created on this service.
• From email — any valid PagerDuty user's email address. PagerDuty attributes the integration's
  writes (notes, status changes, assignments) to this user.

Step 4 — Send the details to Bigeye

Share the following with your Bigeye contact:

{
  "pagerduty_account_url": "https://<your-subdomain>.pagerduty.com",
  "pagerduty_oauth_client_id": "<client id from step 2>",
  "pagerduty_oauth_client_secret": "<client secret from step 2>",
  "pagerduty_service_id": "<service id from step 3>",
  "pagerduty_from_email": "<from email from step 3>",
  "bigeye_workspace_id": "<your Bigeye workspace id>",
  "bigeye_api_key": "<service_account_api_key>"
}

Bigeye then finishes the setup: it verifies your incident type and fields, creates the webhook
subscription that carries changes from PagerDuty back to Bigeye, and enables the integration for your
workspace. Nothing further is needed from you.

If you have several Bigeye workspaces, send one set of details per workspace. Each workspace can point
at a different PagerDuty service.

Step 5 — Verify

Open a Bigeye issue and choose Create ticket. Within a few seconds you should see a new incident on
your service, with:

• the metric, table and column in the title
• the thresholds, observed value and the query in the incident's Custom Details
• all four bigeye_* custom fields populated, and Bigeye Status reading Triage

Add a note to the incident in PagerDuty; it should appear as a comment on the Bigeye issue shortly
after, attributed to you.

Using the integration

What syncs

Status, and why Monitoring shows as acknowledged

Bigeye has four issue states; PagerDuty has three incident states. Monitoring has no PagerDuty
equivalent, so it maps onto acknowledged:

Because two Bigeye states collapse into one, the Bigeye Status custom field carries the real
state — that is what it is for. An incident showing acknowledged with Bigeye Status = Monitoring
means Bigeye considers the issue resolved-but-watched, not still being worked. Check that field rather
than the incident status when you need the distinction.

Coming back the other way, acknowledging an incident that Bigeye already considers Monitoring does
not pull the issue back to Acknowledged. PagerDuty cannot express the difference, so an
acknowledgement is treated as "no change" rather than as a downgrade.

Reopening. Closing an issue resolves the incident; reopening the issue reopens that same
incident rather than creating a new one, so the link from the Bigeye issue stays valid and the
incident keeps its full history.

Assignment

An assignee set in Bigeye is pushed to PagerDuty only once the issue has left Triage.

The reason is that assigning a PagerDuty incident to someone automatically acknowledges it. If Bigeye
pushed the assignee while the issue was still in Triage, the incident would be acknowledged the moment
it was created — which would skip your escalation policy entirely, so nobody would be paged. So a
new incident is left to the escalation policy, and the Bigeye assignee is shown in the incident body
instead.

Once the issue is Acknowledged or Monitoring, the incident is already acknowledged and there is nothing
left to skip, so the assignee is applied normally.

Reassigning in PagerDuty always flows back to the Bigeye issue.

Comments

Comments sync both ways and are labelled with their origin — Comment by Bigeye user … on the
PagerDuty side, Comment by PagerDuty user … on the Bigeye side. That labelling is also how the
integration recognizes its own writes, so a comment is never copied back and forth.

A resolution note added when resolving an incident arrives in Bigeye as its own comment, alongside
the closing note Bigeye records.

Threshold feedback

For issues on autothresholds, feedback flows both ways:

• Set Bigeye Threshold Feedback on the incident before resolving it, and Bigeye uses it as the
  closing label — Normal marks the alert a false positive, Anomalous a true positive.
• Supply feedback in Bigeye when moving an issue to Monitoring or Closed, and it is written to that
  field on the incident.

If the field is left empty, closing defaults to Anomalous (a true positive), which keeps the
threshold trained as-is.

Merged issues

When Bigeye issues are merged into an incident, PagerDuty has no equivalent parent/child structure to
express it. Instead:

• the Bigeye incident's PagerDuty incident lists its merged issues in the incident body, and
• the relationship is recorded as a note on both incidents — each child's incident names the
  parent, and the parent's incident names each child, with links.

Note that PagerDuty's own Related Incidents tab is a separate PagerDuty feature and stays empty;
the relationship is in the notes.

Troubleshooting

"Failed to create ticket" in Bigeye. Almost always the incident type or its custom fields. Confirm
the type is named exactly as configured and that all four fields exist on it, with the field names and
option values exactly as in step 1.

Changes in PagerDuty stop reaching Bigeye. PagerDuty expects a response within 5 seconds and will
temporarily disable a subscription after repeated delivery failures — a subscription can report itself
as active while PagerDuty has paused it. Contact Bigeye; this is diagnosed and cleared on our side.

Comments or statuses sync one way only. Usually means the incident is on a service other than the
one configured for that workspace. Only incidents on the configured service are watched.