Show events on a dashboard

This document describes how you can show events on the charts on a dashboard. An event is an activity, such as a deployment or a crash, that affects the operation of a system. Showing events can help you correlate data from different sources when you're troubleshooting an issue.

You can show events on most dashboards listed in the Dashboards page of the Google Cloud console. To configure the event types that are shown by a dashboard, you can use the Google Cloud console. For custom dashboards, you can also use the Cloud Monitoring API.

How events are identified

Dashboards query for events by analyzing the log entries that pass through the Cloud Logging sinks in your Google Cloud project. These log entries include those generated by your project and those routed to your project.

To get notified when one of these events occurs, you can create a log-based alerting policy. In the alerting policy, use the queries provided on the Event types page.

How events are shown

Note: For performance reasons, dashboards limit the number of events that they show. When these limits are reached, the dashboards show only the most recent events. To view older events, use a shorter time range or add filters.

For all events, as those events occur, the charts on your dashboard are annotated. Events identified by analyzing log entries are shown with a single time reference.

The following screenshot illustrates a chart that is showing one event that is was identified by analyzing log entries:

As shown in the previous screenshot, the tooltip for an event includes information like the following:

• Event name.
• The Google Cloud service or the resource that caused the event.
• Date and start time of the event.
• A View button, which when selected opens a page that shows more information about the event. For example, it might open the Logs Explorer, so that you can view log entries.

Dashboard filters, which limit the data shown by a dashboard, typically filter both time-series data and events.

Before you begin

To get the permissions that you need to view and show events on dashboards, and to create alerting policies, ask your administrator to grant you the following IAM roles on your project:

• View and create dashboards and alerting policies: Monitoring Editor (roles/monitoring.editor).
• View and show events identified from non-data access log entries that are created in your Google Cloud project: Logs Viewer (roles/logging.viewer).
• View and show events identified from any log entries that are created in your Google Cloud project: Private Logs Viewer (roles/logging.privateLogViewer).

For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Show events

For a list of event types, troubleshooting references, and queries that can be used with the Logs Explorer or with log-based alerting policies, see the Event types page.

Console

To show events on a dashboard, do the following:

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

   Go to Dashboards

   If you use the search bar to find this page, then select the result whose subheading is Monitoring.

2. Select the dashboard you want to view.

3. In the dashboard's toolbar, ensure the Events toggle is on.

   If the Events toggle isn't shown, then the dashboard can't show events.

4. Click Select event types, select the event types that you want the dashboard to show, and then do one of the following:

   • If you are viewing a custom dashboard and want to save your event type selections, then click Pin selected. If you have autosave disabled on your dashboard, then go to the dashboard's toolbar and click Save.

     When you pin your selections, you modify the JSON definition of the dashboard. Therefore, when the dashboard is reopened, your selections are loaded and the dashboard shows annotations for the corresponding event types.

   • Otherwise, click Ok.

   After you update the list of event types to show, Cloud Monitoring issues queries, which takes a few moments, and then adds the annotations to the charts on the dashboard.

5. To view a summary of an event or to access links to log entries, use your pointer to activate the tooltip.

API

To configure a custom dashboard to show events, include an annotations field in the Dashboard object. The annotations field contains an instance of a DashboardAnnotations object, which contains two fields:

• The defaultResourceName field lists the dashboard-level defaults for the Google Cloud projects to search for events. If you don't specify this field, then your selected project is searched.

• An array of EventAnnotation objects. Each object contains the following:

  • A displayName field, which lets you define the label on the event-specific toggle. When this field isn't specified or when the value of this field is an empty string, the default name for the event is shown.
  • An enabled field, which controls the value of the event's toggle. When true, the toggle is in the on position and events are shown on the dashboard. When false, the toggle is in the off position.
  • An eventType field, which contains a value from the EventType enumeration.
  • A filter field, which lets you specify a query to append to the event-specific query. When the value of this field is an empty string, then the event-specific query is used.
  • A resourceNames field, which lets you define a list of Google Cloud projects to search for events. When this field is an empty array, your selected project is searched.

The following shows an example annotations object for a cluster update event. The filter field in this example restricts the events to a specific cluster:

"annotations": {
  "defaultResourceNames": [],
  "eventAnnotations": [
    {
      "displayName": "",
      "enabled": true,
      "eventType": "GKE_CLUSTER_UPDATE",
      "filter": "resource.labels.cluster_name=my-cluster",
      "resourceNames": []
    }
  ]
}

For detailed information about how to use the Cloud Monitoring API to create dashboards, see Create and manage dashboards by API and Example: enable events on dashboards.

View event details

When you are viewing a chart that is showing event annotations, you can use links provided in the tooltip to access additional information.

To access details about a specific event, click View.

The Google Cloud console page opened by the View button is determined by the event type. For example, for an uptime check event, this button opens the dashboard for the uptime check. For a different event type, the Logs Explorer might open.

Create alerting policies

When events are identified by analyzing the log entries that pass through the Cloud Logging sinks in your Google Cloud project, you can get notified when these events occur by configuring a log-based alert. Log-based alerting policies query your log entries as they are received. When the query returns a non-empty result, an incident is created and notifications are sent.

Console

Note: To create an alerting policy for an event that you are viewing, activate the tooltip for the event, click View Logs, and then proceed to the create-alert step in the following procedure.

To create a logs-based alert, do the following:

1. If you haven't configured a notification channel, then do the following:

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

      Go to Alerting

      If you use the search bar to find this page, then select the result whose subheading is Monitoring.

   2. Click Edit notification channel.
   3. Go to the type of notification channel that you want to configure, click Add new, and then complete the dialog.

2. In the Google Cloud console, go to the Logs Explorer page:

   Go to Logs Explorer

   If you use the search bar to find this page, then select the result whose subheading is Logging.

3. In the toolbar, select Create Alert.

4. Enter a name for the alerting policy and then click Next.

5. In the Define log entries to alert on section, enter a query or update the query that was copied from the Query pane when you selected Create Alert.

   For each event type, the Event types page lists a query that is suitable for use in a log-based alerting policy.

6. Complete the dialog and click Save.

API

To create a logs-based alerting policy by using the Cloud Monitoring API, do the following:

1. Identify the query that is to be included in the condition of the alerting policy. For each event type, the Event types page lists a query that is suitable for use in a log-based alerting policy.

2. Create the JSON file that contains the representation of the alerting policy. For more information about this step and an example, see Design the alerting policy.

3. Invoke the alertPolicies.create API method. For example, you might issue the gcloud alpha monitoring policies create command.

Hide events

Console

To hide all events, in the dashboard toolbar, ensure the Events toggle is off.

To hide one type of event, set the toggle for that event type to the off position.

API

To hide one type of event on a custom dashboard, find the EventAnnotation object for the event type, and then set the enabled field to false.

For detailed information about how to use the Cloud Monitoring API, see Create and manage dashboards by API.

What's next

• Share a custom dashboard
• Explore charted data
• Access resource-specific dashboards
• Add temporary filters to custom dashboards
• Add permanent filters to custom dashboards