Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(warehouse-sources): add pagerduty incident notes and analytics tables (#124000)

Tom Owersec229df131dc
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
index 01e3158bfcdc..4b82075f66e9 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
@@ -9085,10 +9085,10 @@ Diffed against: <https://raw.githubusercontent.com/PagerDuty/api-schema/main/ref
- [x] `/incidents/{id}/alerts` — alert-level rows under each incident; the actual monitoring events, and where dedup/noise analysis happens (high)
- [x] `/teams/{id}/members` — membership lookup joining users to the teams we already sync (high)
- [x] `/change_events` — deploy/change events, the standard correlate-incidents-to-deploys join (high)
-- [ ] `/analytics/raw/incidents (POST)` — precomputed per-incident MTTA/MTTR, engaged seconds, and escalation counts (high)
-- [ ] `/incidents/{id}/notes` — responder notes attached to incidents, for postmortem/context analysis (medium)
-- [ ] `/schedules/{id}/users` — membership lookup resolving which users belong to each schedule we already sync (medium)
-- [ ] `/v3/schedules/{id}/rotations (and /overrides)` — rotation and override rows - the actual shift structure behind a schedule (medium)
+- [x] `/analytics/raw/incidents (POST)` — precomputed per-incident MTTA/MTTR, engaged seconds, and escalation counts (high). Added as `incident_analytics` (incremental on `updated_at`)
+- [x] `/incidents/{id}/notes` — responder notes attached to incidents, for postmortem/context analysis (medium). Added as `incident_notes` (fan-out over `incidents`)
+- [ ] `/schedules/{id}/users` — skipped: the endpoint lists the users on call in a time window, not schedule membership; membership is already in the `users` column of `schedules`, and who is on call is in `oncalls` (medium)
+- [ ] `/v3/schedules/{id}/rotations (and /overrides)` — skipped: these belong to the separate v3 shift-based schedules API, not the REST v2 API this source implements; v3 schedules need their own `/v3/schedules` parent, and overrides require a `since`/`until` shift window, so a synced table would silently drop history outside it (medium)
- [ ] `/business_services` — business service layer plus /business_services/impacts, needed to roll incidents up to business impact (medium)
- [ ] `/maintenance_windows` — suppression windows; without them uptime and alert-volume math is wrong (medium)
- [ ] `/audit/records` — state/transition history across services, schedules, and policies (medium)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/canonical_descriptions.py
index 744c02df916d..1094fc387f80 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/canonical_descriptions.py
@@ -195,4 +195,55 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"end": "End of the on-call period. Empty when the user does not go off call.",
},
},
+ "incident_notes": {
+ "description": "A note a responder added to an incident, such as a status update or postmortem context.",
+ "docs_url": "https://developer.pagerduty.com/api-reference",
+ "columns": {
+ "id": "Unique identifier for the note within its incident.",
+ "incident_id": "ID of the incident the note is attached to.",
+ "user_id": "ID of the user who wrote the note.",
+ "user": "Reference to the user who wrote the note.",
+ "channel": "The means by which the note was created.",
+ "content": "The note content.",
+ "created_at": "Time at which the note was submitted.",
+ "updated_at": "Time at which the note was last updated.",
+ },
+ },
+ "incident_analytics": {
+ "description": "Per-incident metrics from the PagerDuty Analytics API, such as time to acknowledge, time to resolve, engaged time, and escalation counts.",
+ "docs_url": "https://developer.pagerduty.com/api-reference",
+ "columns": {
+ "id": "ID of the incident.",
+ "incident_number": "The PagerDuty incident number.",
+ "created_at": "Time at which the incident was created.",
+ "updated_at": "Time at which the analytics process last updated the row; the incremental cursor. It differs from the incident's own updated_at.",
+ "resolved_at": "Time at which the incident was resolved.",
+ "status": "The incident status: triggered, acknowledged, or resolved.",
+ "urgency": "Notification level of the incident.",
+ "major": "Whether the incident is a major incident.",
+ "service_id": "ID of the service that the incident triggered on.",
+ "team_id": "ID of the team the incident was assigned to.",
+ "escalation_policy_id": "ID of the escalation policy the incident was assigned to.",
+ "priority_id": "ID of the incident's priority level.",
+ "seconds_to_first_ack": "Seconds from the start of the incident to the first acknowledgement.",
+ "seconds_to_engage": "Seconds from the first engagement of a user to the last added responder engaging.",
+ "seconds_to_mobilize": "Seconds from the start of the incident to the last additional responder acknowledging.",
+ "seconds_to_resolve": "Seconds from when the incident was triggered until it was resolved.",
+ "engaged_seconds": "Total engaged time across all responders for the incident.",
+ "snoozed_seconds": "Total seconds the incident was snoozed.",
+ "user_defined_effort_seconds": "Total response effort in seconds, as defined by the user.",
+ "escalation_count": "Number of times the incident escalated between responders on an escalation policy.",
+ "timeout_escalation_count": "Number of timeout escalations in the incident.",
+ "manual_escalation_count": "Number of manual escalations in the incident.",
+ "assignment_count": "Number of times responders were assigned the incident, including through reassignment or escalation.",
+ "reassignment_count": "Number of reassignments in the incident.",
+ "acknowledgement_count": "Number of acknowledgements in the incident.",
+ "total_interruptions": "Number of unique interruptions in the incident.",
+ "business_hour_interruptions": "Number of unique interruptions during business hours (8am-6pm Mon-Fri, in the user's time zone).",
+ "off_hour_interruptions": "Number of unique interruptions during off hours (6pm-10pm Mon-Fri and all day Sat-Sun, in the user's time zone).",
+ "sleep_hour_interruptions": "Number of unique interruptions during sleep hours (10pm-8am every day, in the user's time zone).",
+ "total_notifications": "Number of notifications sent for the incident.",
+ "auto_resolved": "Whether the incident resolved automatically.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/pagerduty.py b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/pagerduty.py
index b1bd4ecd121f..9c3ac4a95cf0 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/pagerduty.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/pagerduty.py
@@ -18,7 +18,10 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.res
from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.fanout import (
rename_parent_fields,
)
-from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.paginators import BasePaginator
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.paginators import (
+ BasePaginator,
+ JSONResponseCursorPaginator,
+)
from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.resource import Resource
from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.typing import EndpointResource
from products.warehouse_sources.backend.temporal.data_imports.sources.common.resumable import ResumableSourceManager
@@ -34,6 +37,9 @@ PAGERDUTY_BASE_URL = "https://api.pagerduty.com"
# PagerDuty's max page size is 100; the default is 25.
PAGE_SIZE = 100
+# The Analytics API pages with a body cursor and accepts up to 1,000 rows per page.
+ANALYTICS_PAGE_SIZE = 1000
+
# PagerDuty rejects requests where `offset + limit` exceeds 10,000 with an HTTP 400.
# Stop paginating before we cross it. Incremental endpoints stay well under this because
# the `since` filter bounds the window; full-refresh endpoints could in theory truncate
@@ -53,6 +59,8 @@ class PagerDutyResumeConfig:
# Framework fan-out checkpoint ({"completed": [...], "current": ..., "child_state": ...}) for
# endpoints that read one child list per parent row.
fanout_state: Optional[dict[str, Any]] = None
+ # `starting_after` cursor of the next unfetched page, for the cursor-paged Analytics API.
+ cursor: Optional[str] = None
def _format_incremental_value(value: Any) -> str:
@@ -139,6 +147,27 @@ class PagerDutyPaginator(BasePaginator):
self._has_next_page = True
+class PagerDutyAnalyticsPaginator(JSONResponseCursorPaginator):
+ """Body cursor paginator for the Analytics API.
+
+ Each response carries the cursor of its last row in ``last`` even when it is the final page, so the
+ body-level ``more`` flag decides whether another page exists.
+ """
+
+ def __init__(self) -> None:
+ super().__init__(cursor_path="last", cursor_param="starting_after", param_location="json")
+
+ def update_state(self, response: Response, data: Optional[list[Any]] = None) -> None:
+ try:
+ more = bool(response.json().get("more", False))
+ except Exception:
+ more = False
+ if not data or not more:
+ self._has_next_page = False
+ return
+ super().update_state(response, data)
+
+
def _non_secret_headers() -> dict[str, str]:
# Auth (the `Token token=...` Authorization header) is supplied via the framework auth config so
# its value is redacted from logs and errors; only the non-secret headers are set here.
@@ -164,14 +193,15 @@ def _shape_oncall(row: dict[str, Any]) -> dict[str, Any]:
return row
-def _shape_team_member(row: dict[str, Any]) -> dict[str, Any]:
+def _shape_user_reference(row: dict[str, Any]) -> dict[str, Any]:
row["user_id"] = _reference_id(row, "user")
return row
_ROW_SHAPERS: dict[str, Callable[[dict[str, Any]], dict[str, Any]]] = {
"oncalls": _shape_oncall,
- "team_members": _shape_team_member,
+ "team_members": _shape_user_reference,
+ "incident_notes": _shape_user_reference,
}
@@ -212,6 +242,20 @@ def _list_params(config: PagerDutyEndpointConfig, should_use_incremental_field:
return params
+def _analytics_body(should_use_incremental_field: bool, db_incremental_field_last_value: Any) -> dict[str, Any]:
+ # Without a created_at range the API answers its default window. UTC keeps timestamps comparable
+ # with the other tables.
+ body: dict[str, Any] = {
+ "limit": ANALYTICS_PAGE_SIZE,
+ "order": "asc",
+ "order_by": "created_at",
+ "time_zone": "Etc/UTC",
+ }
+ if should_use_incremental_field and db_incremental_field_last_value is not None:
+ body["filters"] = {"updated_after": _format_incremental_value(db_incremental_field_last_value)}
+ return body
+
+
def _skip_when_plan_gated(
items: Iterable[Any],
endpoint: str,
@@ -230,6 +274,25 @@ def _skip_when_plan_gated(
)
+ANALYTICS_READ_ONLY_KEY_ERROR = (
+ "The PagerDuty Analytics API only accepts POST requests, so a read-only API key can't sync the "
+ "incident_analytics table. Use a full access API key, or turn off syncing for this table."
+)
+ANALYTICS_PERSONAL_KEY_ERROR = (
+ "The PagerDuty Analytics API needs an account-level API key. A personal API key can't sync the "
+ "incident_analytics table. Use an account-level key, or turn off syncing for this table."
+)
+
+
+def _probe_analytics(api_token: str, url: str) -> tuple[bool, int | None]:
+ try:
+ session = make_tracked_session(redact_values=(api_token,))
+ response = session.post(url, headers=_get_headers(api_token), json={"limit": 1}, timeout=10.0)
+ except Exception: # noqa: BLE001 — a credential probe must never raise; any failure means "not validated"
+ return False, None
+ return response.status_code == 200, response.status_code
+
+
def validate_credentials(api_token: str, endpoint: Optional[str] = None) -> tuple[bool, int, str | None]:
"""Probe PagerDuty with a cheap single-row request.
@@ -241,17 +304,26 @@ def validate_credentials(api_token: str, endpoint: Optional[str] = None) -> tupl
# A fan-out path carries an `{id}` placeholder. The parent list needs the same access scope.
config = PAGERDUTY_ENDPOINTS[config.parent]
path = config.path if config else "/users"
- url = f"{PAGERDUTY_BASE_URL}{path}?{urlencode({'limit': 1})}"
- ok, status = validate_via_probe(
- lambda: make_tracked_session(redact_values=(api_token,)),
- url,
- headers=_get_headers(api_token),
- )
+ is_post = config is not None and config.method == "POST"
+ if is_post:
+ ok, status = _probe_analytics(api_token, f"{PAGERDUTY_BASE_URL}{path}")
+ else:
+ ok, status = validate_via_probe(
+ lambda: make_tracked_session(redact_values=(api_token,)),
+ f"{PAGERDUTY_BASE_URL}{path}?{urlencode({'limit': 1})}",
+ headers=_get_headers(api_token),
+ )
if ok:
return True, status if status is not None else 200, None
if status is None:
return False, 0, "Could not reach PagerDuty"
+ # Read-only keys can only make GET requests, and personal keys must filter Analytics requests by
+ # team or service, which this source does not do.
+ if is_post and status == 403:
+ return False, 403, ANALYTICS_READ_ONLY_KEY_ERROR
+ if is_post and status == 400:
+ return False, 400, ANALYTICS_PERSONAL_KEY_ERROR
if status == 401:
return False, 401, "Invalid PagerDuty API key"
if status == 403:
@@ -273,7 +345,19 @@ def pagerduty_source(
endpoint_resource: EndpointResource
resources: list[str | EndpointResource]
- if config.parent is None:
+ if config.method == "POST":
+ endpoint_resource = {
+ "name": endpoint,
+ "endpoint": {
+ "method": "POST",
+ "path": config.path,
+ "json": _analytics_body(should_use_incremental_field, db_incremental_field_last_value),
+ "data_selector": config.envelope_key,
+ "paginator": PagerDutyAnalyticsPaginator(),
+ },
+ }
+ resources = [endpoint_resource]
+ elif config.parent is None:
endpoint_resource = {
"name": endpoint,
"endpoint": {
@@ -331,13 +415,20 @@ def pagerduty_source(
if resumable_source_manager.can_resume():
resume = resumable_source_manager.load_state()
if resume is not None:
- initial_paginator_state = resume.fanout_state if config.parent else {"offset": resume.offset}
+ if config.parent:
+ initial_paginator_state = resume.fanout_state
+ elif config.method == "POST":
+ initial_paginator_state = {"cursor": resume.cursor} if resume.cursor else None
+ else:
+ initial_paginator_state = {"offset": resume.offset}
def save_checkpoint(state: Optional[dict[str, Any]]) -> None:
if not state:
return
if config.parent is not None:
resumable_source_manager.save_state(PagerDutyResumeConfig(fanout_state=state))
+ elif state.get("cursor") is not None:
+ resumable_source_manager.save_state(PagerDutyResumeConfig(cursor=str(state["cursor"])))
# Persist only when a next page remains; save AFTER a page is yielded so a crash re-yields the
# last page (merge dedupes) rather than skipping it.
elif state.get("offset") is not None:
@@ -380,9 +471,9 @@ def pagerduty_source(
name=endpoint,
items=items,
primary_keys=config.primary_keys,
- # We always request created_at ascending where a sort is available, and full-refresh endpoints
- # replace wholesale, so ascending is correct everywhere.
- sort_mode="asc",
+ # We request created_at ascending where a sort is available, and full-refresh endpoints replace
+ # wholesale. Endpoints whose incremental field the API can't sort by declare no order.
+ sort_mode=config.sort_mode,
partition_count=1,
partition_size=1,
partition_mode="datetime" if config.partition_key else None,
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/settings.py
index 1f559a6a64c8..1a8b57b42fe2 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/settings.py
@@ -1,5 +1,5 @@
from dataclasses import field
-from typing import Optional
+from typing import Literal, Optional
from posthog.dataclasses import frozen
@@ -33,6 +33,9 @@ class PagerDutyEndpointConfig:
# their parent, so the parent id belongs in the child's primary key.
parent: Optional[str] = None
parent_id_column: Optional[str] = None
+ method: Literal["GET", "POST"] = "GET"
+ # None when rows do not arrive in ascending order of the endpoint's incremental field.
+ sort_mode: Optional[Literal["asc"]] = "asc"
_CREATED_AT_INCREMENTAL: list[IncrementalField] = [
@@ -44,6 +47,15 @@ _CREATED_AT_INCREMENTAL: list[IncrementalField] = [
},
]
+_UPDATED_AT_INCREMENTAL: list[IncrementalField] = [
+ {
+ "label": "updated_at",
+ "type": IncrementalFieldType.DateTime,
+ "field": "updated_at",
+ "field_type": IncrementalFieldType.DateTime,
+ },
+]
+
PAGERDUTY_ENDPOINTS: dict[str, PagerDutyEndpointConfig] = {
"incidents": PagerDutyEndpointConfig(
@@ -69,6 +81,27 @@ PAGERDUTY_ENDPOINTS: dict[str, PagerDutyEndpointConfig] = {
parent="incidents",
parent_id_column="incident_id",
),
+ "incident_notes": PagerDutyEndpointConfig(
+ path="/incidents/{id}/notes",
+ envelope_key="notes",
+ primary_keys=["incident_id", "id"],
+ partition_key="created_at",
+ # Full refresh only, like incident_alerts: responders add notes to an incident long after it
+ # was created, and the child endpoint has no `since` filter.
+ parent="incidents",
+ parent_id_column="incident_id",
+ ),
+ "incident_analytics": PagerDutyEndpointConfig(
+ path="/analytics/raw/incidents",
+ envelope_key="data",
+ partition_key="created_at",
+ incremental_fields=_UPDATED_AT_INCREMENTAL,
+ method="POST",
+ # The metrics change while an incident is open and after it resolves, and `filters.updated_after`
+ # selects the rows the analytics process recomputed. The API sorts only by created_at or
+ # seconds_to_resolve, so rows do not arrive in updated_at order.
+ sort_mode=None,
+ ),
"log_entries": PagerDutyEndpointConfig(
path="/log_entries",
envelope_key="log_entries",
@@ -140,8 +173,8 @@ PAGERDUTY_ENDPOINTS: dict[str, PagerDutyEndpointConfig] = {
ENDPOINTS = tuple(PAGERDUTY_ENDPOINTS.keys())
-# Per-endpoint incremental fields for build_endpoint_schemas; only `incidents` exposes a
-# server-side `since` filter with a controllable sort, so only it is incremental-capable.
+# Per-endpoint incremental fields for build_endpoint_schemas; only `incidents` and
+# `incident_analytics` expose a server-side filter on their incremental field.
INCREMENTAL_FIELDS: dict[str, list[IncrementalField]] = {
name: cfg.incremental_fields for name, cfg in PAGERDUTY_ENDPOINTS.items()
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/source.py
index 199894ccea7b..622f6cf98ee0 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/source.py
@@ -23,6 +23,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.generated_
PagerDutySourceConfig,
)
from products.warehouse_sources.backend.temporal.data_imports.sources.pagerduty.pagerduty import (
+ ANALYTICS_PERSONAL_KEY_ERROR,
+ ANALYTICS_READ_ONLY_KEY_ERROR,
PagerDutyResumeConfig,
pagerduty_source,
validate_credentials as validate_pagerduty_credentials,
@@ -62,7 +64,7 @@ class PagerDutySource(ResumableSource[PagerDutySourceConfig, PagerDutyResumeConf
label="PagerDuty",
caption="""Enter your PagerDuty REST API key to pull your PagerDuty data into the PostHog Data warehouse.
-You can create a read-only API key in your PagerDuty account under **Integrations → API Access Keys**. Select the **Read-only** option — that's all this source needs.""",
+You can create an account-level API key in your PagerDuty account under **Integrations → API Access Keys**. A **Read-only** key syncs every table except `incident_analytics`, because the PagerDuty Analytics API only accepts POST requests. To sync `incident_analytics`, create a full access key instead.""",
iconPath="/static/services/pagerduty.svg",
docsUrl="https://posthog.com/docs/cdp/sources/pagerduty",
fields=cast(
@@ -97,8 +99,11 @@ You can create a read-only API key in your PagerDuty account under **Integration
force_refresh: bool = False,
api_version: str | None = None,
) -> list[SourceSchema]:
- # incidents mutates after creation, so it merges (incremental) but is never append-only.
- return build_endpoint_schemas(ENDPOINTS, INCREMENTAL_FIELDS, names, merge_only={"incidents"})
+ # Incidents and their analytics rows mutate after creation, so they merge (incremental) but are
+ # never append-only.
+ return build_endpoint_schemas(
+ ENDPOINTS, INCREMENTAL_FIELDS, names, merge_only={"incidents", "incident_analytics"}
+ )
def validate_credentials(
self,
@@ -132,7 +137,10 @@ You can create a read-only API key in your PagerDuty account under **Integration
return False, error
def get_non_retryable_errors(self) -> dict[str, str | None]:
+ # The Analytics entries come first: the first matching entry supplies the message.
return {
+ "403 Client Error: Forbidden for url: https://api.pagerduty.com/analytics": ANALYTICS_READ_ONLY_KEY_ERROR,
+ "400 Client Error: Bad Request for url: https://api.pagerduty.com/analytics": ANALYTICS_PERSONAL_KEY_ERROR,
"401 Client Error: Unauthorized for url: https://api.pagerduty.com": "Your PagerDuty API key is invalid or expired. Please generate a new key and reconnect.",
"403 Client Error: Forbidden for url: https://api.pagerduty.com": "Your PagerDuty API key does not have the required permissions. Please check the key's access and try again.",
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/tests/test_pagerduty.py b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/tests/test_pagerduty.py
index aec6b956bb44..5758e1853662 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/tests/test_pagerduty.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/pagerduty/tests/test_pagerduty.py
@@ -17,6 +17,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.generated_
PagerDutySourceConfig,
)
from products.warehouse_sources.backend.temporal.data_imports.sources.pagerduty.pagerduty import (
+ ANALYTICS_PERSONAL_KEY_ERROR,
+ ANALYTICS_READ_ONLY_KEY_ERROR,
PAGE_SIZE,
PagerDutyResumeConfig,
_format_incremental_value,
@@ -102,6 +104,7 @@ class TestFanOut:
[
("incident_alerts", "/incidents", "incidents", "alerts", "incident_id", None),
("team_members", "/teams", "teams", "members", "team_id", "U1"),
+ ("incident_notes", "/incidents", "incidents", "notes", "incident_id", "U1"),
],
)
def test_reads_each_parents_children_and_tags_the_parent_id(
@@ -144,6 +147,54 @@ class TestFanOut:
assert [row.get("user_id") for row in result.rows] == [expected_user_id, expected_user_id]
+class TestIncidentAnalytics:
+ @pytest.mark.parametrize(
+ "should_use_incremental_field,last_value,expected_filters",
+ [
+ (False, None, None),
+ # The first incremental sync has no watermark yet, so it reads the full default window.
+ (True, None, None),
+ (True, datetime(2026, 1, 1, tzinfo=UTC), {"updated_after": "2026-01-01T00:00:00+00:00"}),
+ ],
+ )
+ def test_walks_body_cursor_pages_until_more_is_false(
+ self, should_use_incremental_field: bool, last_value: datetime | None, expected_filters: Any
+ ) -> None:
+ result = _driver().run(
+ "incident_analytics",
+ [
+ ScriptedResponse(json={"data": [{"id": "I1"}, {"id": "I2"}], "last": "c2", "more": True}),
+ # The final page still carries its `last` cursor.
+ ScriptedResponse(json={"data": [{"id": "I3"}], "last": "c3", "more": False}),
+ ],
+ should_use_incremental_field=should_use_incremental_field,
+ db_incremental_field_last_value=last_value,
+ )
+
+ assert result.raised is None
+ assert [request.method for request in result.requests] == ["POST", "POST"]
+ assert result.paths == ["/analytics/raw/incidents", "/analytics/raw/incidents"]
+ bodies = [request.json() for request in result.requests]
+ assert [body.get("starting_after") for body in bodies] == [None, "c2"]
+ assert all(body["order"] == "asc" and body["order_by"] == "created_at" for body in bodies)
+ assert [body.get("filters") for body in bodies] == [expected_filters, expected_filters]
+ assert [row["id"] for row in result.rows] == ["I1", "I2", "I3"]
+ assert result.saved_states == [PagerDutyResumeConfig(cursor="c2")]
+ assert result.response is not None
+ assert result.response.sort_mode is None
+
+ def test_resumes_from_saved_cursor(self) -> None:
+ result = _driver().run(
+ "incident_analytics",
+ [ScriptedResponse(json={"data": [{"id": "I3"}], "last": "c3", "more": False})],
+ resume_state=PagerDutyResumeConfig(cursor="c2"),
+ )
+
+ assert result.raised is None
+ assert [request.json().get("starting_after") for request in result.requests] == ["c2"]
+ assert [row["id"] for row in result.rows] == ["I3"]
+
+
class TestOncalls:
@pytest.mark.parametrize(
"oncall,expected_id,expected_schedule_id",
@@ -225,6 +276,7 @@ class TestValidateCredentials:
# A fan-out child path carries an `{id}` placeholder, so the probe reads the parent list.
("incident_alerts", "/incidents"),
("team_members", "/teams"),
+ ("incident_notes", "/incidents"),
],
)
def test_probe_path(self, endpoint: str, expected_path: str) -> None:
@@ -234,6 +286,26 @@ class TestValidateCredentials:
assert ok is True
assert [request.path for request in network.requests_log] == [expected_path]
+ @pytest.mark.parametrize(
+ "status_code,expected_ok,expected_error",
+ [
+ (200, True, None),
+ # PagerDuty restricts read-only keys to GET requests.
+ (403, False, ANALYTICS_READ_ONLY_KEY_ERROR),
+ # Personal keys must send a team_ids or service_ids filter.
+ (400, False, ANALYTICS_PERSONAL_KEY_ERROR),
+ ],
+ )
+ def test_analytics_probe_posts_to_the_analytics_endpoint(
+ self, status_code: int, expected_ok: bool, expected_error: str | None
+ ) -> None:
+ with scripted_network(always(ScriptedResponse(status=status_code, json={}))) as network:
+ ok, status, error = validate_credentials("tok", "incident_analytics")
+
+ assert (ok, status, error) == (expected_ok, status_code, expected_error)
+ [request] = network.requests_log
+ assert (request.method, request.path) == ("POST", "/analytics/raw/incidents")
+
def test_transport_failure_returns_zero_status(self) -> None:
with scripted_network(always(ConnectionError("no network"))) as network:
ok, status, error = validate_credentials("tok")