This document describes the key concepts and terms used within Personalized Service Health
(PSH). Understanding these concepts helps you effectively interpret events and
configure alerts.

### Personalized Service Health event

A Service Health **event**
([v1](https://docs.cloud.google.com/service-health/docs/reference/rest/v1/projects.locations.events.md.txt#resource:-event),[v1beta](https://docs.cloud.google.com/service-health/docs/reference/rest/v1beta/projects.locations.events.md.txt#resource:-event))
is any disruptive event impacting a Google Cloud product that is relevant to
your projects or resources. Examples include network outages, configuration
errors, and performance issues.

Each event contains details about the overall impact of the event, updates from
Google, and information specific to your Google Cloud project.

### Incident

**Incidents** are emerging and active Google Cloud service outages or
degradations relevant to your projects. An incident is also a category of a
Service Health event.

An incident includes the following:

- **Incident impact**: Details of the scope of the event, such as impacted Google Cloud products and locations.
- **Updates from Google Cloud**: Periodic updates from Google Cloud support.
- **Personalized relevance**: Incident's relevance to your Google Cloud project.
- **Symptoms, workarounds, and ETAs**: Information to help assess impact, apply a workaround, or learn more about the root cause.

Incidents may have an **incident report**, which includes the factors that
contributed to the incident, and the steps Google Cloud plans to take to prevent
similar incidents from recurring. Incident reports are available for incidents
that meet the following conditions:

- The incident has global impact or is affecting a significant percentage of customer projects across one or more regions.
- One or more products are unavailable or severely degraded.

### Event states and detailed states

An event has two fields indicating its state. The values for these fields
change as the event evolves.

- **Event state**: Indicates the overall state of the event. It can be one of
  the following:

  - **Active**: Event is actively affecting Google Cloud and will continue to receive updates.
  - **Closed**: Event is no longer affecting any Google Cloud product, or has been merged with another event.
- **Detailed state**: Provides more information on the state of the event. It
  applies to incidents only, and can be one of the following values depending
  on the event state:

  - **Emerging**: Google engineers are actively investigating the incident
    to determine the impact. An emerging incident will become either a
    confirmed or resolved incident once the impact assessment is complete.
    An active incident can be an emerging incident.

    Support for emerging incidents is available for Google Cloud
    networking products only.
  - **Confirmed**: The incident is confirmed by Google engineers and
    impacting at least one Google Cloud product. Ongoing status
    updates will be provided until it is resolved.

    An active incident can be a confirmed incident.
  - **Merged**: The incident was merged into a parent incident. All further
    updates will be published to the parent only.

  - **Resolved**: The incident is no longer affecting any Google Cloud
    product after action was taken. There will be no further updates.

    A closed incident is usually a resolved incident.
  - **False positive**: Upon investigation, Google engineers concluded that
    the incident is not affecting a Google Cloud product. This state can
    change if the incident is reviewed again.

  - **Auto-closed**: The incident was automatically closed because of the
    following reasons:

    - The impact of the incident couldn't be confirmed.
    - The incident was intermittent or resolved itself.

    The incident does not have a resolution because no action or
    investigation happened. If it is intermittent, the incident may reopen.

### Granular disruption status

During a multi-product or multi-location incident, individual products or
locations might recover before the overall incident is resolved.
Personalized Service Health provides **granular disruption status** at the per-product and
per-location level to reflect partial recovery while an incident is active.
Granular disruption status is available for both project-level events and
organization-level events.

A product or location can have one of the following granular disruption
statuses:

- **Affected**: The product or location is experiencing disruption due to the incident.
- **Resolved**: The specific product or location is no longer experiencing disruption and has recovered.

#### Distinction between event states and granular status

It's important to distinguish between the overall event state, the detailed
state, and the granular disruption status of individual products or locations:

- **Overall event state and detailed state** : Apply to the incident as a whole. An incident remains **Active** (with a detailed state such as **Confirmed** ) as long as at least one product or location remains **Affected** . An incident transitions to **Closed** (with a detailed state of **Resolved** ) only after all associated products and locations have reached **Resolved** status.
- **Granular disruption status** : Applies independently to each affected product or location. An individual product or location can transition to **Resolved** while the overall event state remains **Active**.

When an incident is **Merged** into a parent incident, the granular disruption
statuses of the child incident are cleared, and the child incident delegates
granular status to the parent incident as the single source of truth.

> [!NOTE]
> **Note:** Alerting policies configured in Cloud Logging apply to overall event revisions and state changes, not to isolated granular status transitions for individual products or locations.

### Relevance

Personalized Service Health assesses the impact of all incidents to your project. If the
incident's impact to your project is possible or confirmed, it becomes available
in the Service Health dashboard and API.

**Relevance** indicates whether your project is impacted, related, or partially
related to an event. For supported products in Preview, relevance also
identifies the specific resources in your project that are impacted.

Relevance can have the following values:

- **Impacted** : The incident is confirmed to be affecting your project. For [Supported products
  (Preview)](https://docs.cloud.google.com/service-health/docs/supported-products-locations#resource-level-impact), you can also view which specific resources in your project are impacted.
- **Related**: The incident has a direct connection with your project and impacts a Google Cloud product in a location your project uses.
- **Partially Related**: The incident is associated with a Google Cloud product your project uses, but the incident may not be impacting your project. For example, the incident may be impacting a Google Cloud product that your project uses, but in a location that your project does not use.
- **Not Impacted**: The incident is not impacting your project.
- **Unknown**: The impact to your project is not known at this point.

## Impacted resources

> [!WARNING]
>
> **Preview**
>
>
> This product or feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section
> of the [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA products and features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

When an event has a relevance of `IMPACTED` for your project,
Personalized Service Health can identify the specific Google Cloud resources
in your project that are affected by the disruption (for example, a specific
Cloud SQL instance or Google Kubernetes Engine cluster).

> [!NOTE]
> **Note:** For a list of products that support `IMPACTED` relevance with resource-level impact, see [Products supporting resource-level impact (Preview)](https://docs.cloud.google.com/service-health/docs/supported-products-locations.md.txt#resource-level-impact).

In the Service Health `v1beta` API, each affected resource is
represented by an
[`Impact`](https://docs.cloud.google.com/service-health/docs/reference/rest/v1beta/projects.locations.impacts.md.txt#Impact)
resource (`projects/{PROJECT_ID}/locations/global/impacts/{IMPACT_ID}`). An
`Impact` resource contains:

- **Linked events (`events`)** : One or more project-level Service Health `Event` resource names (`projects/{PROJECT_ID}/locations/global/events/{EVENT_ID}`) associated with the resource impact.
- **Impacted asset (`asset`)** :
  - `assetName`: The [full resource
    name](https://docs.cloud.google.com/apis/design/resource_names#full_resource_name) of the affected Google Cloud resource (for example, `//cloudsql.googleapis.com/projects/123456789/instances/my-db-instance`).
  - `assetType`: The [Cloud Asset Inventory resource
    type](https://docs.cloud.google.com/asset-inventory/docs/supported-asset-types) of the affected resource (for example, `sqladmin.googleapis.com/Instance` or `container.googleapis.com/Cluster`).
- **Description (`description`)**: Additional context about the impact on the resource, when available.
- **Timestamps (`createTime`, `updateTime`)**: When the resource impact record was first created and last updated.

Remember the following behaviors when using impacted resources in Preview:

- **Project impacts versus organization impacts** :
  - *Impact* (`projects.locations.impacts`) is scoped to a single project and only returns non-container resources when the event has confirmed `IMPACTED` relevance for that project, and when product support is available.
  - *Organization impact* (`organizations.locations.organizationImpacts`) aggregates across the organization to return container assets (projects) with any non-zero relevance (`PARTIALLY_RELATED`, `RELATED`, or `IMPACTED`), where *non-zero relevance* means any project that may be affected by an `OrganizationEvent`.
- **API enablement prerequisite** : To receive `Impact` records, the Service Health API (`servicehealth.googleapis.com`) must be enabled on the project at least 24 hours before the event starts. Enabling the API after an event starts backfills project-level events from the past 90 days, but does not backfill resource-level impacts.
- **Event-duration lifecycle** : Once a resource is identified as impacted by an event, its `Impact` record remains associated with the event for the lifecycle of the incident. Use the linked `Event` resource to track the overall incident state (`ACTIVE` or `COMPLETED`) and communications updates.
- **Supported products and incident scope** : Resource-level impact is available for [supported Google Cloud products and resource
  types](https://docs.cloud.google.com/service-health/docs/supported-products-locations#resource-level-impact). If an event affects a product that doesn't support resource-level impact, or if the disruption is at a control-plane or regional level not tied to individual resource instances, the project `Event` still appears with `relevance: IMPACTED`, while `impacts.list` returns an empty list.

To query impacted resources, see
[Manage events affecting a project](https://docs.cloud.google.com/service-health/docs/project-events.md.txt#list-impacted-resources).

## Product Identity Names and Display Names (Alpha and Beta only)

To let administrators quickly pinpoint operations without requiring local
mappings of product identifiers, event entries in `v1alpha` and `v1beta`
releases provide display strings inside referenced resources.

Specifically within the `Product` objects specified on standard payloads
(located inside the `impact` collections on both `Event` and
`OrganizationEvent`), two new properties assist in identification:

- **`display_name` (string)** : An `OUTPUT_ONLY` tag exposing human-readable product titles suited for customer readouts (such as `"Google Cloud SQL"`).
- **`previous_display_names` (repeated string)** : An `OUTPUT_ONLY` array detailing all titles this specific resource supported formerly. This maintains continuity in tracing events back through active rebrandings.

> [!NOTE]
> **Note:** The `display_name` and `previous_display_name` fields are for display purposes and may change as a result of product rebranding. For programmatic logic (API calls and alerting policies), use stable product IDs.

Product display fields are deferred on the `vGA (v1)` surface for maximum system
stability.

To determine correct immutable identifiers for usage in filters and alerts:

1. Open the [Supported products and locations](https://docs.cloud.google.com/service-health/docs/supported-products-locations.md.txt) guide.
2. Find the target Google Cloud product in the table.
3. Copy the value listed under **Product ID**.

Alternatively, determine correct immutable identifiers directly from API
payloads:

1. Make an API call returning event resources (such as `projects.locations.events.list`).
2. Inspect the `impact` block mappings in the resulting JSON array.
3. Extract the string present in the `product` property. This value indicates the stable product ID, independent of varying display names.