servicehealth-incident-correlation
Checks Personalized Service Health (PSH) events and resource-level impacts to determine whether a Google Cloud incident affects a project or its resources, returning an impact verdict with affected resources, published symptoms, and workarounds. Use when asked whether Google Cloud is having an outage or affecting a project or its resources, when looking up a PSH event, or when triaging live Google Cloud workload issues or alerts whose symptoms suggest a possible Google Cloud service disruption—even if the user does not suspect an outage. Don't use for local code or build errors, routine alerts
Try your first task
A source-grounded starter task has not been verified for this skill yet.
SKILL.md
name: servicehealth-incident-correlationmetadata: version: "1.0.0" category: CloudObservabilityAndMonitoringdescription: >- Checks Personalized Service Health (PSH) events and resource-level impacts to determine whether a Google Cloud incident affects a project or its resources, returning an impact verdict with affected resources, published symptoms, and workarounds. Use when asked whether Google Cloud is having an outage or affecting a project or its resources, when looking up a PSH event, or when triaging live Google Cloud workload issues or alerts whose symptoms suggest a possible Google Cloud service disruption—even if the user does not suspect an outage. Don't use for local code or build errors, routine alerts or automations that neither ask for a service health check nor suggest a platform disruption, configuring PSH alerts, or checking non-project-specific public status.Personalized Service Health incident correlation
Correlates
Personalized Service Health (PSH)
events (v1) and resource-level impacts (v1beta, Preview) with observed
workload symptoms (product, location, resource, time) to return a per-project
impact verdict. Read-only: relay published PSH symptoms and workarounds without
modifying resources or inventing incident data.
[!IMPORTANT] The costliest mistake is a false all-clear. Telling a responder "not Google" during an active Google Cloud incident misdirects incident response. When a PSH events call fails or the customer's product is not covered by PSH, the verdict is
INCONCLUSIVE, neverNO_IMPACT_IDENTIFIED.
Usage Attribution
MUST READ: Before executing any gcloud, REST API, or MCP command, you
MUST read and follow the instructions in
Usage Attribution.
Prerequisites
- Target project: Pass
{project_id}explicitly on every call; never rungcloud config set project. - Billing: The project must have an active billing account attached.
- API enablement: Requires
servicehealth.googleapis.comon{project_id}(gcloud services enable servicehealth.googleapis.com --project={project_id}; ask before enabling). Resource-level impacts (Preview) require enablement at least 24 hours before an incident starts. - Authentication & IAM: Authenticate via
gcloud auth login,gcloud auth application-default login, orGOOGLE_APPLICATION_CREDENTIALS(install the Google Cloud CLI ifgcloudis missing). Requiresroles/servicehealth.vieweron{project_id}(servicehealth.events.*andservicehealth.impacts.*; custom roles may omitimpacts), plusroles/mcp.toolUserfor remote MCP. - Transports: Use the
PSH remote MCP server
(
https://servicehealth.googleapis.com/mcp, scopehttps://www.googleapis.com/auth/servicehealth.readonly). Read REST API and gcloud fallback only if the MCP server is unavailable.
Workflow
Step 1: Determine scope
- Project ID. Query only a project named in the prompt/conversation, an
alert payload (
incident.resource.labels.project_id, elseincident.scoping_project_id), a resource pathprojects/{project_id}/..., or caller context. Never fall back to the host's defaultgcloudproject orGOOGLE_CLOUD_PROJECT: querying the agent's own host project produces false signals for unrelated stacks. - Observed context. Extract any product, location, named resource, and
reference time (alert
incident.started_atin Unix seconds, a user-given time with relative times such as "20 minutes ago" converted to UTC, or now). - Missing scope.
- Interactive: Ask only when an essential identifier is missing (an
unnamed workload project ID, or a question about a specific event
without its event ID). When no workload project was named, ask solely
for the Google Cloud project ID without issuing an impact verdict
(
Status: ...) or listing events from any environment, host, or quota project. Broad checks ("Are there any outages?") for a named project need no narrowing by service or region. - Headless (alert, notification, or automated caller): Never wait for
human input; when no workload project ID is present, return
INCONCLUSIVEright away, naming the missing project ID, without substituting any environment or quota project.
- Interactive: Ask only when an essential identifier is missing (an
unnamed workload project ID, or a question about a specific event
without its event ID). When no workload project was named, ask solely
for the Google Cloud project ID without issuing an impact verdict
(
- PSH coverage. Whenever web access is available, fetch the live
Supported products and locations
page first; otherwise use the PSH coverage
snapshot. Both list onboarded products and mark emerging incident (
*),IMPACTEDrelevance (†), and resource-level impact (‡, Preview) support.
Step 2: Retrieve incidents (bounded)
All PSH resources use parent projects/{project_id}/locations/global. Pass
pageSize: 100 and follow all nextPageToken pages (list_project_events
defaults to pageSize=10 and orders results alphabetically by event_id, not
newest-first). Take event resource names verbatim from retrieved events or the
prompt.
MCP tools:
list_project_events(parent,filter,pageSize,pageToken): lists events withoutupdates. EacheventImpactsentry carries the granular status of one product/location pair:state(AFFECTEDorRESOLVED),startTime, andendTime. Filterable fields (space-joined AND):category,state,update_time, andevent_impacts.product.product_name(repeated field: requires:for exact, case-sensitive element match;=fails withinvalid filter).relevance, location,startTime, andendTimeare not filterable.get_project_event(name): fetches one event withupdates(symptoms and workarounds).list_project_impacts(parent,filter,pageSize,pageToken): lists resource-level impacts (PreviewImpactresources); scope it per event as in Step 3.get_project_impact(name): fetches one resource-level impact by ID.
Always pass a bounded filter on list_project_events (and ?filter= or
--filter= on REST/gcloud) unless the user explicitly asks for the full
event history, since an unfiltered call returns the full historical archive:
| Situation | Event filter |
|---|---|
| Live/ongoing check with no symptom start time ("Is anything down right now?") | state=ACTIVE |
Correlating a symptom or alert start time (YYYY-MM-DD..., Unix started_at, or a relative time such as "20 minutes ago" converted to UTC) | state=ACTIVE OR update_time>="{reference_time_minus_24h}" |
Product known (exact, case-sensitive name from coverage.md; combine variants with OR, or omit only the product clause while keeping state or update_time and match productName client-side) | add event_impacts.product.product_name:"{product_name}" |
| Recently resolved check (only when asked) | update_time>="{now_minus_n_hours}" |
For example, correlating symptoms that started at 2026-10-16T14:05:00Z on Compute Engine (attribution prefix from Usage Attribution omitted):
# MCP
list_project_events {"parent": "projects/{project_id}/locations/global",
"filter": "state=ACTIVE OR update_time>=\"2026-10-15T14:05:00Z\"",
"pageSize": 100}
# gcloud fallback: --filter is required here too
gcloud service-health events list --project={project_id} --location=global \
--page-size=100 --format=json \
--filter='state=ACTIVE OR update_time>="2026-10-15T14:05:00Z"'
Quote RFC 3339 timestamps (update_time>="2026-09-01T00:00:00Z"). Save large
responses to a temp file outside the repository rather than reading raw JSON
into context, and summarize large multi-event listings by product and location.
Step 3: Correlate with what was observed
-
Product and location. Keep incidents matching the observed product and location (or all active incidents on a general project check). Regions, zones, multi-regions (such as
us,europe,asia), andglobalare distinct PSH locations, and any hierarchy between them is product-specific:- Exact location named (e.g.,
europe-west1orus-west1-a): stay within that exact location for the impact verdict. If no incident matches that exact location, still mention active or recently closed incidents in proximate locations (e.g., other zones inus-west1, its containing region, or aeuropemulti-region incident) as helpful context without marking the projectIMPACTED. - Vague location named (e.g., "Europe" or "US"): match broadly across every location that fits the description.
If an
eventImpactsentry omitslocation(e.g., emerging or informational events), checktitleanddescriptionbefore ruling out a location match. - Exact location named (e.g.,
-
Event state. Before checking the timeline:
detailedStateMERGED: consolidated intoparentEvent, not resolved. Because closed (MERGED) events receive no further updates, followparentEventviaget_project_eventuntil reaching a root event that is notMERGED, and replace the merged events with it. Treat the root event as the single source of truth for active/closed state,relevance, impact verdict, linkedimpacts, and published symptoms/workarounds (never carry forward superseded child symptoms, and assess the root event even when itseventImpactsnames an underlying service).detailedStateEMERGING(Google is still investigating): an active incident, reported with the emerging-incident wording in Step 5.detailedStateFALSE_POSITIVEorAUTO_CLOSED: does not match.
-
Timeline. Pick the window, then compare the reference time with it.
- Window: when a location was named, use the
eventImpactsentries matching the observed product and location. The window opens at their earlieststartTime, stays open while any of them isAFFECTED, and closes at their latestendTimeonce all areRESOLVED, even if the event staysACTIVEelsewhere. Otherwise, or when the matching entries carry no granular status, use the event'sstartTimetoendTime(open while the event isACTIVE). - Comparison (
startTimeoften lags symptom onset):- Reference time inside the window: matches.
- Up to 4 hours before the window opens: matches (note that
symptoms preceded
startTime). - More than 4 hours before the window opens: does not match
(mention only as a possible aggravating factor since
startTime). - Window closed within 1 hour before the reference time: recent
close (
INCONCLUSIVE); state how long before the reference time it closed. - Window closed more than 1 hour before the reference time: does not match.
- Window: when a location was named, use the
-
Event details. Call
get_project_eventfor surviving matches and read the latest update's symptom and workaround (unless full history was requested). -
Resource-level impacts (informational only). Query
list_project_impacts(or its REST/gcloud betaequivalent) withfilterevents:"{event.name}"for every surviving incident (the root event, never aMERGEDone) and report what it returns, but never derive the verdict from it. Even for products with resource-level impact coverage, product teams can detect resource-level impact only for some incidents and PSH does not say which, so an empty list never means "not impacted".asset.assetNameuses numeric{project_number}, not{project_id}— match customer-named resources byassetType, location, and resource name. If a named resource is absent while other project resources appear, report both facts.
-
Fresh state. Re-fetch incident data from earlier turns or alert payloads before issuing a verdict.
Step 4: Issue the verdict
PSH Event.relevance and the skill verdict are distinct, and the verdict comes
from events only: resource-level impact results (listed impacts, an empty list,
or a failed call) never change it.
-
IMPACTEDif any matching incident'sEvent.relevanceisIMPACTEDorRELATED. The verdict makes no distinction between the two; Step 5 reports each event'srelevance. Never treatRELATEDas "not impacted" or skip it when asked for "only impacting" incidents: it is PSH's strongest signal for products without project-level or resource-level impact support. -
INCONCLUSIVEif theeventscall failed, the observed product is not onboarded to PSH, the project ID is missing in a headless flow, or a matching incident's window (Step 3) closed within 1 hour before the reference time. State why. A failedimpactscall alone never makes the verdictINCONCLUSIVE. -
NO_IMPACT_IDENTIFIEDwheneventssucceeded for a PSH-covered product and:- No incident matches, or
- Every match has a
relevanceother thanIMPACTEDorRELATED(NOT_IMPACTED,PARTIALLY_RELATED, orUNKNOWN).
Never present this as an all-clear: incident declaration can lag symptoms. State this caveat and suggest checking the workload or re-checking PSH if symptoms persist.
Step 5: Report
Report in concise prose for interactive and headless callers alike, with the granular status table below (see Report examples). For multi-project checks, give each project its own verdict and describe shared incidents once. Include in order:
-
Impact verdict (one per project; use these exact tokens, the second
IMPACTEDform forEMERGINGincidents, and list every matching event ID):Status: IMPACTED -- Project {project_id} is affected by incident {event_id} (PSH relevance {relevance}).Status: IMPACTED -- Project {project_id} matches emerging incident {event_id}, which Google is still investigating (PSH relevance {relevance}).Status: NO_IMPACT_IDENTIFIED -- No PSH incident impacting project {project_id} was identified at this time.Status: INCONCLUSIVE -- Impact on project {project_id} could not be determined: {reason}.
-
Project ID source (prompt, alert payload, resource name, request context).
-
Event summary (one per matching event; every active event on a general project check): title, event ID,
relevance, state, window, and how it correlates with observed symptoms. List incidents in proximate locations separately as context. -
Granular status (per event, right after its summary): a table with one row per
eventImpactsentry, so the status of each product and location stands out (omit it when no entry carries granular status):Product Location Status Start End {productName} {locationName} {AFFECTED or RESOLVED} {startTime} {endTime, or "ongoing"} -
Resource-level impacts (per event): each returned impact's
assetName,assetType, anddescription/timestamps, or when none were returned:- Empty
impactson a product with resource-level impact coverage:"PSH has not listed any resource-level impacts for this incident. Resource-level impacts are not available for every {product} incident yet, so this project can still be impacted." - Empty
impactson a product/resource type without coverage:"Resource-level impacts are not supported for {product_or_resource_type} yet." - Failed
impactscall:"Resource-level impacts could not be retrieved: {reason}", with the same failure detail as for a failedeventscall (never claim none were listed, and never invent resource names)
- Empty
-
Symptoms and workarounds (per event): quote the latest update ("No workaround published" if empty).
-
PSH links: per event,
https://console.cloud.google.com/servicehealth/incidentDetails/{event_name}?project={project_id}(/inevent.nameencoded as%2F); and in every report whose project ID is known, whatever the verdict, the events dashboardhttps://console.cloud.google.com/servicehealth/incidents?project={project_id}.
References
Read each reference only when its condition applies, to keep context small:
- Usage Attribution: before the first command.
- PSH coverage: supported products and resource-level impacts: only when the live Supported products and locations page cannot be fetched.
- Errors and resolutions: only after a call fails.
- REST API and gcloud fallback: only when MCP is unavailable.
- Report examples: when writing the report.
- PSH concepts and PSH MCP reference