Cloud Monitoring *alerts* let you track and investigate issues when
individual log entries in Cloud Logging match the condition of a log-based
alerting policy. For each alert, Monitoring sends a
notification and creates an **Alert details** page to help you
troubleshoot the failure and manage the alert lifecycle.

On the **Alert details** page, you can view matching log entries
and links to related alerts. Monitoring doesn't create a
new alert if the policy is snoozed or disabled, or if the number of
alerting policies or alerts exceeds the
[limits for alerting](https://docs.cloud.google.com/monitoring/quotas.md.txt#alerting_uptime_limits). If another log entry matches
the condition of an already open alert, Monitoring sends
an additional notification instead of opening a new alert.

This feature is supported only for Google Cloud projects.
For [App Hub](https://docs.cloud.google.com/app-hub/docs/overview.md.txt)
configurations, select the App Hub host project or management project.

## Before you begin


To get the permissions that
you need to view and manage alerts,

ask your administrator to grant you the
following IAM roles on your project:

- View alerts by using the Google Cloud CLI or the Cloud Monitoring API: [Monitoring Alert Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/monitoring.md.txt#monitoring.alertViewer) (`roles/monitoring.alertViewer`)
- View alerts by using the Google Cloud console:
  - [Monitoring Cloud Console Incident Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/monitoring.md.txt#monitoring.cloudConsoleIncidentViewer) (`roles/monitoring.cloudConsoleIncidentViewer`)
  - [Stackdriver Accounts Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/monitoring.md.txt#stackdriver.accounts.viewer) (`roles/stackdriver.accounts.viewer`)
- Manage alerts by using the Google Cloud console:
  - [Monitoring Cloud Console Incident Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/monitoring.md.txt#monitoring.cloudConsoleIncidentEditor) (`roles/monitoring.cloudConsoleIncidentEditor`)
  - [Stackdriver Accounts Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/monitoring.md.txt#stackdriver.accounts.viewer) (`roles/stackdriver.accounts.viewer`)


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

For more information about Cloud Monitoring roles,
see [Control access with Identity and Access Management](https://docs.cloud.google.com/monitoring/access-control.md.txt).

## View alerts

To view alerts in your project, use the Google Cloud console,
the gcloud CLI, or the Monitoring API.

### Google Cloud console

To list the alerts in your Google Cloud project, do the following:

1. In the Google Cloud console, go to the
   **Alerting** page:

   [Go to **Alerting**](https://console.cloud.google.com/monitoring/alerting)

   <br />

   If you use the search bar to find this page, then select the result whose subheading is
   **Monitoring**.
2. In the toolbar of the Google Cloud console,
   select your Google Cloud project. For [App Hub](https://docs.cloud.google.com/app-hub/docs/overview.md.txt)
   configurations, select the App Hub host project or management project.

   The **Alerting** page displays information about your alerting policies,
   snoozes, and alerts:
   - The **Summary** pane lists the number of open alerts.
   - The **Alerts** table displays the most recent open alerts. To list the most recent alerts in the table, including those that are closed, click **Show closed alerts**.
3. To view the details of a specific alert, select the
   alert in the list.

   The **Alert details** page opens. For more information about
   the **Alert details** page, see the
   [Investigate an alert](https://docs.cloud.google.com/monitoring/alerts/log-based-incidents.md.txt#details-page) section of this document.

### Find older alerts

The **Alerts** table on the **Alerting** page shows the most
recent open alerts. To view older alerts, do one of the
following:

- To page through the entries in the **Alerts** table, click
  **Newer** or **Older**.

- To open a page that lets you list and filter your alerts, click
  **See all alerts** . The **Alerts** page opens. From
  that page, do the following:

  - Show all alerts, including closed alerts. To show all alerts, click **Show closed alerts**.
  - Filter alerts. For information about adding filters, see [Filter alerts](https://docs.cloud.google.com/monitoring/alerts/log-based-incidents.md.txt#filtering).
  - Acknowledge or close an alert, or snooze its alerting policy. To access these options, click **More options** in the alert's row, and make a selection from the menu. For more information, see [Manage alerts](https://docs.cloud.google.com/monitoring/alerts/log-based-incidents.md.txt#incident).

### Filter alerts

To restrict the alerts that the table shows, add filters. If you
add multiple filters, the table displays only alerts that satisfy
all the filters.

To filter the table of alerts, do the following:

1. On the **Alerts** page, click
   **Filter table** and then select a filter
   property. Filter properties include the following:

   - State of the alert
   - Name of the alerting policy
   - When the alert was opened or closed
2. Select a value from the secondary menu or enter a value in the filter
   bar.


   The **Alerts** table then lists the filter.

### gcloud

You can use the gcloud to get alerts and list
alerts.

### Get alert


Before using any of the command data below,
make the following replacements:

- <var translate="no">ALERT_NAME</var>: The resource name of the alert. For example, `projects/my-project/alerts/my-alert-id`.


Execute the

[`gcloud alpha monitoring alerts describe`](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/monitoring/alerts/describe.md.txt)

command:

#### Linux, macOS, or Cloud Shell

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud alpha monitoring alerts describe ALERT_NAME
```

#### Windows (PowerShell)

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud alpha monitoring alerts describe ALERT_NAME
```

#### Windows (cmd.exe)

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud alpha monitoring alerts describe ALERT_NAME
```
The command returns a response with alert details such as alert state, attached labels, and the source alerting policy. The response looks similar to the following:

```
{
  "name": "projects/my-project/alerts/my-alert-id",
  "state": "OPEN",
  "open_time": "2025-06-11T09:53:46Z",
  "resource": {
    "type": "k8s_cluster",
    "labels": {
      "location": "us-central1",
      "cluster_name": "example_cluster",
      "project_id": "my-project"
    }
  },
  "log": {
    "extracted_labels": {
      "title": "my title"
    }
  },
  "policy": {
    "name": "projects/my-project/alertPolicies/POLICY_1",
    "displayName": "test-policy"
  },
  "summaryText": "[ALERT] test-policy for Kubernetes Cluster with {cluster_name=example_cluster, location=us-central1, project_id=my-project}"
}
```

<br />

### List alerts

You can list alerts in your project and filter the results using
the gcloud CLI.


Before using any of the command data below,
make the following replacements:

- <var translate="no">PROJECT_ID</var>: The identifier of the project.


Execute the

[`gcloud alpha monitoring alerts list`](https://docs.cloud.google.com/sdk/gcloud/reference/alpha/monitoring/alerts/list.md.txt)

command:

#### Linux, macOS, or Cloud Shell

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud alpha monitoring alerts list
```

#### Windows (PowerShell)

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud alpha monitoring alerts list
```

#### Windows (cmd.exe)

> [!NOTE]
> **Note:** Ensure you have initialized the Google Cloud CLI with authentication and a project by running either [gcloud init](https://docs.cloud.google.com/sdk/gcloud/reference/init); or [gcloud auth login](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) and [gcloud config set project](https://docs.cloud.google.com/sdk/gcloud/reference/config/set.md.txt).

```bash
gcloud alpha monitoring alerts list
```
The command returns a response with alert details such as alert state, attached labels, and the source alerting policy. The response looks similar to the following:

```
{
  "alerts": [
    {
      "name": "projects/my-project/alerts/my-alert-id",
      "state": "OPEN",
      "open_time": "2025-06-11T09:53:46Z",
      "resource": {
        "type": "k8s_cluster",
        "labels": {
          "location": "us-central1",
          "cluster_name": "example_cluster",
          "project_id": "my-project"
        }
      },
      "log": {
        "extracted_labels": {
          "title": "my title"
        }
      },
      "policy": {
        "name": "projects/my-project/alertPolicies/POLICY_1",
        "displayName": "test-policy"
      },
      "summaryText": "[ALERT] test-policy for Kubernetes Cluster with {cluster_name=example_cluster, location=us-central1, project_id=my-project}"
    }
  ]
}
```
You can also use the following optional flags to filter, sort, or modify the output:

- `--filter`: Provide a filter expression to filter alerts by time or by label. For
  example, filter by time with `--filter='close_time>="2025-09-10T00:00:00Z"'`, or
  filter by label with `--filter='resource.labels.key="value"'`.

- `--sort-by`: A comma-separated list of fields to sort the output by. For
  example, `--sort-by=open_time`.

- `--uri`: The command outputs a list of resource URIs instead of the default output.

- `--limit`: Set this flag to `2` or greater to limit the number of alerts
  returned. Don't use this flag in conjunction with the `--filter` flag.

<br />

### Monitoring API

You can use the Monitoring API to get alerts and list
alerts.

### Get alert

To get details on a single alert with the Monitoring API,
use the [`alerts.get`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alerts/get.md.txt) method.


Before using any of the request data,
make the following replacements:

- <var translate="no">PROJECT_ID</var>: The identifier of the project.
- <var translate="no">ALERT_ID</var>: The ID of the alert.


HTTP method and URL:

```
GET https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts/ALERT_ID
```

To send your request, expand one of these options:

#### curl (Linux, macOS, or Cloud Shell)


Execute the following command:

```
curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts/ALERT_ID"
```

#### PowerShell (Windows)


Execute the following command:

```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts/ALERT_ID" | Select-Object -Expand Content
```
The command returns a response with alert details such as alert state, attached labels, and the source alerting policy. The response looks similar to the following:

```
{
  "name": "projects/my-project/alerts/my-alert-id",
  "state": "OPEN",
  "open_time": "2025-06-11T09:53:46Z",
  "resource": {
    "type": "k8s_cluster",
    "labels": {
      "location": "us-central1",
      "cluster_name": "example_cluster",
      "project_id": "my-project"
    }
  },
  "log": {
    "extracted_labels": {
      "title": "my title"
    }
  },
  "policy": {
    "name": "projects/my-project/alertPolicies/POLICY_1",
    "displayName": "test-policy"
  },
  "summaryText": "[ALERT] test-policy for Kubernetes Cluster with {cluster_name=example_cluster, location=us-central1, project_id=my-project}"
}
```

<br />

### List alerts

To list alerts in your project and filter the results with
the Monitoring API, use the [`alerts.list`](https://docs.cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.alerts/list.md.txt)
method.


Before using any of the request data,
make the following replacements:

- <var translate="no">PROJECT_ID</var>: The identifier of the project.


HTTP method and URL:

```
GET https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts
```

To send your request, expand one of these options:

#### curl (Linux, macOS, or Cloud Shell)


Execute the following command:

```
curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts"
```

#### PowerShell (Windows)


Execute the following command:

```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://monitoring.googleapis.com/v3/projects/PROJECT_ID/alerts" | Select-Object -Expand Content
```
The command returns a response with alert details such as alert state, attached labels, and the source alerting policy. The response looks similar to the following:

```
{
  "alerts": [
    {
      "name": "projects/my-project/alerts/my-alert-id",
      "state": "OPEN",
      "open_time": "2025-06-11T09:53:46Z",
      "resource": {
        "type": "k8s_cluster",
        "labels": {
          "location": "us-central1",
          "cluster_name": "example_cluster",
          "project_id": "my-project"
        }
      },
      "log": {
        "extracted_labels": {
          "title": "my title"
        }
      },
      "policy": {
        "name": "projects/my-project/alertPolicies/POLICY_1",
        "displayName": "test-policy"
      },
      "summaryText": "[ALERT] test-policy for Kubernetes Cluster with {cluster_name=example_cluster, location=us-central1, project_id=my-project}"
    }
  ]
}
```
Curl users can add the `--data-urlencode` flag followed by a filter expression to filter alerts by time or label. See the following examples:

List alerts that were opened in the last hour:

```
--data-urlencode "filter=(open_time>=\"`date -u -d "1 hour ago" +"%Y-%m-%dT%H:%M:%SZ"`\")"
```

List \& filter alerts that are open from the last day:

```
--data-urlencode "filter=(open_time>=\"`date -u -d "1 DAY ago" +"%Y-%m-%dT%H:%M:%SZ"`\" AND state=open)"
```

List \& filter alerts that were opened between two periods:

```
--data-urlencode "filter=(open_time>=\"`date -u -d "2 DAY ago" +"%Y-%m-%dT%H:%M:%SZ"`\" AND open_time<=\"`date -u -d "1 DAY ago" +"%Y-%m-%dT%H:%M:%SZ"`\")"
```

List \& filter alerts by user label. In this example, filter by a user label with the name
`app` and the value `my-gke-app`:

```
--data-urlencode "filter=(policy.user_labels.app=\"my-gke-app\")"
```
Powershell users can use the following example to add a time-based filter to their request url:

```
$baseUrl = "https://monitoring.googleapis.com/v3/projects/my-project/alerts"
$filterValue = (Get-Date).AddHours(-1).ToString("yyyy-MM-ddTHH:mm:ssZ")
$filter = 'open_time >= "' + $filterValue + '"'
$encodedFilter = [System.Uri]::EscapeDataString($filter)
$url = $baseUrl + "?filter=" + $encodedFilter
```

<br />

> [!NOTE]
> **Note:** Alerts aren't always created when a condition is met. For more information, see [Alert isn't created when condition is met](https://docs.cloud.google.com/monitoring/alerts/troubleshooting-alerts.md.txt#no-incidents).

## Investigate an alert

The **Alert details** page contains information that may help you
identify the cause of an alert.

> [!CAUTION]
> **Caution:** If you're working with Google Cloud support to investigate the cause of an alert, then don't modify the associated alerting policy. Modifying an alerting policy causes Cloud Monitoring to discard the precomputed data that the system uses to determine when to create an alert. Discarding this data results in the loss of the historical record of the alert.

### Explore log entries

Explore log entries to find patterns and recurring issues related to your
investigation. The **Logs** pane shows log entries that match the query of your
log-based alerting policy.

- To view the log entries in the [Logs Explorer](https://docs.cloud.google.com/logging/docs/view/logs-explorer-interface.md.txt), click **View in Logs Explorer**, and then select a scoping project.
- To view the Logs Panel in the [Metrics Explorer](https://docs.cloud.google.com/monitoring/charts/metrics-explorer.md.txt), click **Explore Data**.

### View supplementary information

The **Labels** section shows the labels and values for the monitored resource
included in the log entry that caused the alert.
This information can help you identify the specific monitored
resource that caused the alert. For more information, see
[Annotate alerts with labels](https://docs.cloud.google.com/monitoring/alerts/labels.md.txt).

The **Documentation** section shows the documentation template for
notifications that you provided when creating the alerting policy.
This information might include a description of what the alerting
policy monitors as well as tips for mitigation. For more information, see
[Annotate notifications with user-defined documentation](https://docs.cloud.google.com/monitoring/alerts/doc-variables.md.txt).

If you didn't configure documentation for your alerting policy,
then the **Documentation** pane shows "No documentation is configured."

## Explore related alerts

To help you discover underlying issues across your application, you can
explore alerts related to other alerting policy conditions.
The **Related alerts** section shows a list of alerts that match one of the following:

<br />

- The alert was created when a condition of the same alerting policy was met.
- The alert shares a label with the alert shown on the **Alert details** page.

## Manage alerts

Alerts are in one of the following states:

- Open:

  The condition of the log-based alerting policy was met, and the
  alert is still open. If the same condition is met again and
  there is already an alert open, then a new alert isn't
  opened.

- Acknowledged:
  The alert is open and has manually been marked as acknowledged.
  Typically, this status indicates that the alert is being
  investigated.

- Closed:

  You have manually closed the alert, or it was automatically closed
  after the auto-close period expired.

### Acknowledge alerts

We recommend that you mark an alert as acknowledged when you begin
investigating the cause of the alert.

To mark an alert as acknowledged, do the following:

1. In the **Alerts** table of the **Alerting** page, click **See all alerts**.
2. On the **Alerts** page, find the alert that you want to
   acknowledge, and then do one of the following:

   - Click **More options** and then select **Acknowledge**.
   - Open the details page for the alert and then click **Acknowledge alert**.

### Snooze an alerting policy

To prevent Monitoring from creating alerts and sending
notifications during a specific time period, snooze the related alerting policy.

When you snooze an alerting policy, alerts related to the alerting
policy remain open but don't cause further notifications. The alerts
close based on the alerting policy auto-close duration.


To create a snooze for an alert that you are viewing, do the following:

1. On the **Alert details** page, click **Snooze Policy**.

2. Select the snooze duration. After you select the snooze duration, the snooze
   begins immediately.

You can also snooze an alerting policy from the **Alerts** page by
finding the alert that you want to snooze, clicking
**More options** , and then selecting **Snooze**.
You can snooze alerting policies during outages to prevent further
notifications during the troubleshooting process.

### Close alerts

You can let Monitoring close an alert for you, or
you can close the alert.

Monitoring automatically closes an alert when the
auto-close duration for the alerting policy expires. By default, the auto-close
duration is 7 days. The minimum auto-close duration
is 30 minutes.

The auto-close duration specifies the time that must elapse, without a repeat
of the cause of the alert, before the alert closes. For this
reason, when an alert is open and its cause reoccurs, the
alert can stay open longer than the auto-close duration.

To close an alert, do the following:

1. In the **Alerts** table of the **Alerting** page, click **See all alerts**.
2. On the **Alerts** page, find the alert that you want to
   close, and then do one of the following:

   - Click **View more** and then select **Close alert**
   - Open the **Alert details** page for that alert and then click **Close alert**.

If you see the message `Unable to close alert`, try again in a few
minutes. You can't close a new alert immediately because the conditions
that caused the alert are still considered active by the alerting
system.

## Data retention and limits

For information about limits and about the retention period of alerts,
see [Limits for alerting](https://docs.cloud.google.com/monitoring/quotas.md.txt#alerting_uptime_limits).

## What's next

- To create and manage alerting policies with the Monitoring API or from the command line, see [Manage alerting policies by API](https://docs.cloud.google.com/monitoring/alerts/using-alerting-api.md.txt).