Quickstart for using Monitoring Query Language

This Quickstart shows you how to use Monitoring Query Language (MQL) to explore metrics, create charts, and set up a query-based alert. In this Quickstart, you do the following:

  1. Create a Compute Engine instance.

  2. Navigate to the Query Editor.

  3. Perform a query and create a chart.

  4. Set up a query-based alert.

Before you begin

To use MQL, you need to create a Google Cloud project and enable billing.

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Cloud Console, on the project selector page, select or create a Cloud project.

    Go to the project selector page

  3. Make sure that billing is enabled for your Google Cloud project. Learn how to confirm billing is enabled for your project.

Create a Compute Engine instance

To have a Google Cloud resource to collect metrics from, create a Compute Engine instance by completing the following steps:

  1. From the Cloud Console menu, select Compute Engine.

    User interface for selecting a compute instance.

  2. Select Create instance, and then click Create.

Navigate to the Query Editor

To begin using MQL, do the following:

  1. From the Cloud Console menu, select Monitoring.

    The first time you access Monitoring in the Google Cloud Console, a Workspace must be created. If you've never used Monitoring, or if you've never created a multi-project Workspace, a Workspace is created automatically. Otherwise, a dialog appears and you can select between creating a Workspace and adding your project to an existing Workspace.

  2. From the Monitoring menu, select Metrics Explorer.

  3. Click Query Editor on the Build Your Query pane.

    User interface for selecting the Query Editor.

    The interface changes to the MQL Query Editor:

    User interface for Query Editor.

Use the Query Editor to construct, test, and run MQL queries.

Perform a simple query and create a chart

Create a simple query that charts the CPU utilization of your instance:

  1. Paste the following query into the Query Editor:

    fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
    | {
        top 1, max(val())
      ;
        bottom 1, min(val())
      }
    | union
    

    User interface for entering a query into the Query Editor.

    This query selects the time series with the maximum and minimum CPU utilization for charting. For more information on this query, see Combining selections with union.

  2. Click Run Query. The chart displays two lines, showing your instance's maximum and minimum CPU utilization:

    The chart shows the max and min CPU utilization.

  3. To save the chart, click Save Chart. Give the chart a name and add it to either an existing dashboard or a new one. Then click Save.

    User interface for saving a chart.

The chart can be accessed by going to the Monitoring overview page, or if you saved it to a dashboard, by going to that dashboard's page.

Set up a query-based alert

You can create an alerting policy that monitors the results of a query. To create such an alerting policy, complete the following steps:

  1. From the Cloud Console menu, select Monitoring and then select Alerting.

  2. From the Alerting page, click Edit Notification Channels. In this step, you configure an email address to receive alert notifications.

    1. On the Notification channels page, sroll down to Email and click Add.

    2. Enter the email address to which you want alert notifications sent in the Email Address field.

    3. Enter a brief description of this channel, like "Alert on-call", in the Display name field.

    4. Click Save.

    5. Go back to the Alerting page by clicking Back on the page header.

  3. From the Alerting page, click Create Policy.

    Interface for creating an alerting policy.

    This page leads you through the steps to create an alerting policy:

    1. Describing what you want to alert on.
    2. Specifying a notification channel for the alert.
    3. Providing information about how to address this issue.
  4. To describe what you want to alert on, click Add Condition. This action brings up the form-based condtion editor.

    1. Change to the Query Editor view of the condition editor by clicking Query Editor. This version of the condition editor includes the Query Editor and a Configuration pane:

      The condition editor for MQL-based alerting policies.

    2. Enter a name for your condition, like "MQL Quickstart condition".

    3. To be alerted when your instance's CPU usage time stays above 2 seconds, enter the following query:

      fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time
      | window 1m
      | condition val() > 2 's'
      

      The condition operation establishes the performance threshold you want to alert on. In the example, the alerting policy tracks CPU usage time above 2 seconds.

    4. Click Run Query to see the selected data and a threshold line:

      Chart for an alert-condition query.

    5. To be alerted when the your instance's CPU utilization exceeds the the threshold and stays there for 5 minutes, use the Condition pane as follows:

      1. Change the value of the For field to 5 minutes.
      2. Don't change the value of the Condition triggers if field.
    6. To save your condition in your alerting policy, click Add. You are notified that the condition is converted to a strict form when saved.

    7. Continue by clicking Save. This action returns you to the Create alerting policy page.

  5. Click Next to move to the next step, setting up notifications.

  6. Select the notification channel you created previously, and click OK.

  7. Click Next to move to the next step, providing steps to fix the issue.

    1. Enter a name for the alerting policy in the Alert name field. This value lets you distinguish among notifications from different alerting policies.

    2. Enter some text to be sent with any alert notification in the Documentation field. This text typically provides responders with information to help them address the problem. For this exercise, enter "Your CPU usage has exceeded 2 seconds."

  8. Save your policy by clicking Save.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, follow these steps.

  1. Go to the Identity and Access Management page in the Google Cloud Console:

    Go to project settings

  2. Click Shut down and follow the instructions.

What's next