Personalized Service Health concepts

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,v1beta) 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.

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), 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

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).

In the Service Health v1beta API, each affected resource is represented by an 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 of the affected Google Cloud resource (for example, //cloudsql.googleapis.com/projects/123456789/instances/my-db-instance).
    • assetType: The Cloud Asset Inventory resource type 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. 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.

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.

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 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.