Дежурства и инциденты в PagerDuty

Текст

---
name: pagerduty-api
description: Запрашивай данные PagerDuty и управляй им — узнавай, кто сейчас дежурит, выводи инциденты и управляй ими, читай политики эскалации и расписания, выясняй, кого и почему вызвали, подтверждай, закрывай, откладывай и эскалируй инциденты, создавай и обновляй сервисы. Используй этот скилл всякий раз, когда пользователь упоминает PagerDuty, дежурство, вызов (paging), эскалацию, ID инцидента вроде `PXXXXXX` или `Q...`, спрашивает «кто сейчас на дежурстве», «вызови дежурного», «подтверди этот инцидент», «почему меня не вызвали» или вставляет ссылку pagerduty.com, даже если слова «API» он не говорит. Всегда начинай с этого скилла, когда работаешь с этим сервисом: его готовые скрипты и рецепты — самый быстрый путь.
---

PagerDuty предоставляет два разных API:

• REST API по адресу https://api.pagerduty.com — чтение и управление всем (инциденты, дежурства, расписания, политики эскалации, сервисы, пользователи, записи журнала).
• Events API v2 по адресу https://events.pagerduty.com — программный запуск, подтверждение и закрытие оповещений. Другой хост и другая аутентификация (ключ маршрутизации в теле запроса, заголовка Authorization нет).

Модель данных: оповещение срабатывает на сервисе (service) → проходит по политике эскалации (escalation policy) → адресуется расписаниям (schedules) и пользователям (users) → открывает инцидент (incident); записи журнала (log entries) фиксируют, кого именно уведомили, когда и по какому каналу.

Настройка запросов

Аутентификацию обеспечивает среда выполнения — учётные данные подставляются в исходящие запросы к этому API, так что настраивать ничего не нужно. Не пытайся создавать, выпускать, обновлять или проверять токены и ключи. Переменные с учётными данными нужны только для того, чтобы запросы были составлены правильно; если какая-то из них не задана, подставь любое значение-заглушку. Постоянная ошибка 401/403 означает, что для этого рабочего пространства учётные данные не настроены — сообщи об этом, а не разбирайся с авторизацией.

REST API (api.pagerduty.com) — в каждом запросе передаётся заголовок Authorization: Token token=<t> (это ни Bearer, ни Basic):

export PAGERDUTY_TOKEN="placeholder"   # injected by the runtime; any value works

Events API v2 (events.pagerduty.com) — обращение идёт по ключу маршрутизации (routing key) интеграции (32 шестнадцатеричных знака) в теле запроса. Заголовка Authorization нет.

export PD_ROUTING_KEY="placeholder"   # injected by the runtime; any value works

Проверка подключения — убедись, что рабочее пространство подключено:

curl -sS -w '\nHTTP %{http_code}\n' "https://api.pagerduty.com/users/me" \
  -H "Authorization: Token token=${PAGERDUTY_TOKEN}" \
  -H "Content-Type: application/json"

200 → подключено; пропусти вывод через jq '.user | {id, name, email}'. 401/403 → учётные данные не настроены (тело часто пустое, поэтому код статуса выводится отдельно). /users/me работает только с пользовательскими токенами; токены уровня аккаунта можно проверить через /abilities.

Вспомогательная функция, используемая ниже (по желанию):

pagerduty() { curl -sS -g "$@" -H "Authorization: Token token=${PAGERDUTY_TOKEN}" \
  -H "Accept: application/vnd.pagerduty+json;version=2" -H "Content-Type: application/json"; }

Флаг -g важен: массивы параметров в PagerDuty записываются со скобками (statuses[]=triggered), которые старый curl раскрывает как шаблон и выдаёт ошибку — см. раздел «Постраничная выдача».

Коды и тела ответов — относится ко всем рецептам ниже:

• Изменения через REST: 200 — обновление, 201 — создание. **401 возвращает пустое тело** — если запись выглядит так, будто молча ничего не сделала, проверь HTTP-статус (-w '%{http_code}').
• Постановка в очередь через Events v2: 202 — принято; неверный ключ маршрутизации даёт 400 с текстовым телом Invalid routing key (это не JSON — не передавай его в jq).
• Любая ссылка на другой объект в теле запроса должна иметь вид {"id": "<id>", "type": "<x>_reference"} — без type будет 400.

Основные операции

1. Кто на дежурстве (scripts/pd_oncall.sh)

Отвечай на вопрос «кто на дежурстве» через входящий в комплект скрипт (путь указан относительно папки этого скилла): он превращает названия сервисов и имена пользователей в id, запрашивает /oncalls с фильтрами-массивами в скобках, листает страницы по offset/limit, пока more равно true, и выдаёт TSV или JSONL.

scripts/pd_oncall.sh --service checkout --earliest
scripts/pd_oncall.sh --user alice@example.com --at 2026-06-01T09:00:00Z --json

• --service NAME|ID ограничивает выборку одним сервисом. Значение, подходящее под ^P[A-Z0-9]{5,7}$, используется как id; всё остальное ищется через /services?query=. Политика эскалации сервиса затем передаётся как escalation_policy_ids[] — у /oncalls собственного фильтра по сервису нет.
• --policy ID / --schedule ID фильтруют напрямую (можно повторять). --user QUERY определяет имя или email через /users?query= и передаёт как user_ids[] (можно повторять). Поиск по имени (здесь и в --service) должен находить ровно один результат — для надёжности передавай id.
• --at TIME спрашивает, кто дежурит в заданный момент ISO-8601 (задаёт и since, и until); --earliest возвращает только ближайшую запись для каждой политики.
• --limit N ограничивает общее число записей (по умолчанию 100, 0 = все); --page-size N задаёт размер страницы (максимум 100). --json выдаёт по одному JSON-объекту на запись вместо TSV с заголовком level, user, policy, schedule, until. Найденные id и числа выводятся в stderr. Параметры подключения берутся из PAGERDUTY_TOKEN, см. выше.
• Коды завершения: 0 — успех, 1 — запрос не удался, ошибка API или неверные аргументы; собственные error.code/error.message API выводятся в stderr (тело 401 пустое, поэтому вместо него печатается HTTP-статус).

Если скрипт выдаёт ошибку, прочитай его: это обычные curl + jq, — и разбирайся по references/api.md.

2. Список открытых инцидентов

pagerduty "https://api.pagerduty.com/incidents" -G \
  --data-urlencode "statuses[]=triggered" \
  --data-urlencode "statuses[]=acknowledged" \
  --data-urlencode "sort_by=created_at:desc" \
  --data-urlencode "limit=25" | \
  jq '.incidents[]? | {id, incident_number, title, status, urgency, service: .service.summary, created_at}'

Ограничь по времени через since=/until= (ISO-8601); фильтруй через service_ids[]=, team_ids[]=, urgencies[]=high.

3. Получить один инцидент

pagerduty "https://api.pagerduty.com/incidents/<incident_id>" | \
  jq '.incident | {id, title, status, urgency, assignments, escalation_policy: .escalation_policy.summary}'

<incident_id> — это буквенно-цифровой ID (P.../Q...), а не incident_number. Чтобы найти по номеру, выведи список с date_range=all и отфильтруй на своей стороне.

4. Кого на самом деле вызвали? (записи журнала)

pagerduty "https://api.pagerduty.com/incidents/<incident_id>/log_entries" -G \
  --data-urlencode "is_overview=false" | \
  jq '.log_entries[]? | {type, at: .created_at, summary, channel: .channel.type}'

Интересные значения type: trigger_log_entry, notify_log_entry (кого вызвали и по какому каналу), acknowledge_log_entry, escalate_log_entry, assign_log_entry, resolve_log_entry. Сопоставь с /users/<id>/notification_rules, чтобы понять, почему канал использовали (или не использовали).

5. Подтвердить / закрыть / эскалировать / отложить / добавить заметку

Для любых изменений инцидентов нужен заголовок From: с email настоящего пользователя PagerDuty в аккаунте — по нему действие записывается в журнал аудита. Если email нет или он неизвестен → 400.

pagerduty -X PUT "https://api.pagerduty.com/incidents/<incident_id>" \
  -H "From: me@example.com" \
  -d '{"incident": {"type": "incident_reference", "status": "acknowledged"}}'

• Подтвердить (Acknowledge) — PUT /incidents/<id>: {"incident":{"type":"incident_reference","status":"acknowledged"}}
• Закрыть (Resolve) — PUT /incidents/<id>: {"incident":{"type":"incident_reference","status":"resolved"}}
• Эскалировать на уровень N — PUT /incidents/<id>: {"incident":{"type":"incident_reference","escalation_level":N}}
• Отложить (Snooze) — POST /incidents/<id>/snooze: {"duration": <seconds>}
• Добавить заметку — POST /incidents/<id>/notes: {"note":{"content":"..."}}

6. Проследить маршрут: сервис → политика эскалации → расписание

# service → which policy
pagerduty "https://api.pagerduty.com/services/<service_id>?include[]=escalation_policies" | \
  jq '.service | {name, escalation_policy}'

# policy → ordered rules and targets
pagerduty "https://api.pagerduty.com/escalation_policies/<policy_id>" | \
  jq '.escalation_policy.escalation_rules[]? | {delay_min: .escalation_delay_in_minutes, targets: [.targets[]? | {type, summary}]}'

# schedule → rendered rotation for the next week (after overrides/layers)
# GNU date; on BSD/macOS use: date -u -v+7d +%Y-%m-%dT%H:%M:%SZ
pagerduty "https://api.pagerduty.com/schedules/<schedule_id>" -G \
  --data-urlencode "since=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  --data-urlencode "until=$(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)" | \
  jq '.schedule.final_schedule.rendered_schedule_entries[]? | {start, end, user: .user.summary}'

Большинство списковых эндпоинтов принимают query= для поиска подстроки в названии, например GET /schedules?query=platform → jq '.schedules[]? | {id, name}'.

7. Создать инцидент

pagerduty -X POST "https://api.pagerduty.com/incidents" \
  -H "From: me@example.com" \
  -d '{
    "incident": {
      "type": "incident",
      "title": "Payment gateway returning 500s",
      "urgency": "high",
      "service": {"id": "<service_id>", "type": "service_reference"},
      "body": {"type": "incident_body", "details": "Seeing 40% error rate since 14:00 UTC."}
    }
  }'

Успех — это 201; для последующих вызовов читай .incident.id (в ответе с ошибкой он равен null; проверь статус, прежде чем использовать его снова).

8. Запустить оповещение через Events API v2

curl -sS -X POST "https://events.pagerduty.com/v2/enqueue" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_key": "'"${PD_ROUTING_KEY}"'",
    "event_action": "trigger",
    "dedup_key": "db-latency-prod-us-east",
    "payload": {
      "summary": "DB p99 latency > 500ms in prod us-east",
      "source": "prometheus:db_latency_p99",
      "severity": "critical",
      "custom_details": {"value_ms": 612}
    }
  }'

event_action ∈ trigger / acknowledge / resolve — чтобы закрыть цикл, отправь следующее событие с тем же dedup_key. Ответ 202 возвращает {"status":"success","dedup_key":"..."}; сохрани dedup_key, если его сгенерировал PagerDuty. Неверно сформированные данные вернут JSON 400 с errors[].

Постраничная выдача

Классические offset/limit: limit (по умолчанию 25, максимум 100) и offset (по умолчанию 0); листай, пока в ответе more: true, увеличивая offset на limit. **offset + limit не может быть больше 10 000** — сверх этого сужай временное окно или фильтры. Исключения: /audit/records возвращает next_cursor (передай обратно как cursor=); /analytics/raw/... принимает starting_after в теле POST (укажи значение last из предыдущего ответа).

Ловушка с curl-шаблонами. Параметры-массивы записываются со скобками — statuses[]=, service_ids[]=, team_ids[]=, include[]=. Старый curl воспринимает [ ] как символы шаблона и падает с ошибкой curl: (3) bad range; современный curl отправляет их как есть. Всегда передавай -g/--globoff (вспомогательная функция это делает) или для надёжности кодируй скобки через -G --data-urlencode 'statuses[]=...'.

Лимиты запросов

REST API: 960 запросов в минуту на токен (ключи одного пользователя делят общий бюджет). В ответах есть ratelimit-limit, ratelimit-remaining, ratelimit-reset (секунды до сброса). При 429 ({"error":{"message":"Rate Limit Exceeded","code":2020}}) подожди ratelimit-reset секунд и повтори. У некоторых эндпоинтов есть более жёсткие лимиты на отдельные операции; заголовки отражают ближайший из них. /oncalls и /schedules/{id} относительно затратны — кэшируй результаты, если используешь их повторно.

У Events API v2 отдельный бюджет: около 120 событий в минуту на ключ маршрутизации. При 429 сделай паузу и повторяй с интервалом около 30 с.

Обработка ошибок

Тела ошибок: {"error": {"message": "...", "code": N, "errors": ["field X is ..."]}}.

• **400** — некорректный запрос. Прочитай error.errors[] — там названо проблемное поле. Частые причины: нет From: при изменении, нет type у объекта-ссылки, неверная метка времени ISO-8601.
• **401 — учётные данные отклонены. Тело пустое** — выведи статус. Заголовок должен быть Authorization: Token token=.... Если ошибка не уходит, значит, учётные данные не настроены — сообщи об этом.
• **403** — доступ запрещён. Учётные данные только для чтения пытаются изменять данные либо ограничены командой, которой ресурс не принадлежит.
• **404** — не найдено. ID — это короткие буквенно-цифровые строки (P.../Q...), а не названия и не incident_number.
• **429** — сработал лимит запросов. Подожди ratelimit-reset секунд и повтори.

Подробнее

В references/api.md — полный каталог эндпоинтов: инциденты (оповещения, объединение, запросы к исполнителям, приоритеты), сервисы и интеграции, политики эскалации, расписания и подмены, пользователи и способы уведомления и связи, команды, окна обслуживания, бизнес-сервисы, оркестрация событий, аналитика и полная структура данных Events API v2. Читай его, когда нужен эндпоинт, которого нет выше.

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-tag-plugins/tree/main/pagerduty/skills/pagerduty-api, лицензия Apache-2.0. Изменения: перевод на русский язык.