Quickstart: Using Cloud Datalab with Stackdriver

Beta

This is a Beta release of Stackdriver Monitoring support in Cloud Datalab. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.

This Quickstart shows you how to set up Cloud Datalab to use with your Stackdriver Monitoring projects. Cloud Datalab's dynamic notebooks let you perform ad hoc analyses and visualizations that go beyond the present features of Stackdriver Monitoring.

To preview the Stackdriver Monitoring tutorials in Cloud Datalab, see Stackdriver Monitoring tutorials. You cannot interact with the tutorials unless you are running Cloud Datalab.

Before you begin

For this Quickstart you need:

• Access to a Stackdriver account that is monitoring one or more VM instances. The account is used as something to look at in Cloud Datalab; it is not modified. If you do not have access to such an account, you can create one using the Quickstart for Compute Engine or the Quickstart for Amazon EC2.

• An instance of Cloud Datalab that is running locally:

  • Cloud Datalab must be accessible as http://127.0.0.1:8081/.

  • Cloud Datalab must have the Stackdriver Monitoring tutorials in datalab > docs > tutorials > Stackdriver Monitoring.

  If you do not have a running instance of Cloud Datalab, you can install one locally using instructions in this Quickstart.

Set up Cloud Datalab

If you have a running instance of Cloud Datalab as described in Before you begin, then skip ahead to The Cloud Datalab interface. Otherwise, the following instructions are excerpted from the Cloud Datalab Quickstart, Run Cloud Datalab locally. The installation involves installing Docker and then loading the Cloud Datalab Docker container.

Install Docker

If you have Docker installed on your local workstation, you can skip ahead to Run Cloud Datalab. Otherwise, the following instructions are taken from Install Docker Engine.

Ubuntu & Debian

Run the following commands on your workstation:

sudo apt-get update
sudo apt-get install docker-engine
sudo service docker start

To verify the installation, load a container test image using the following command:

sudo docker run hello-world

Red Hat & CentOS

Run the following commands on your workstation:

sudo yum install docker-engine
sudo systemctl enable docker.service
sudo systemctl start docker

To verify the installation, load a container test image using the following command:

sudo docker run hello-world

Mac OS

To install under MacOS, see Get started with Docker for Mac.

Run Cloud Datalab

For detailed instructions, see Run Cloud Datalab locally. Otherwise, the following command starts Cloud Datalab in a Docker container on Linux or MacOS. Execute the command in a separate terminal window, because the container will remain running in the terminal, preventing you from doing other work there:

sudo docker run -it -p "127.0.0.1:8081:8080" -v "${HOME}:/content"  \
    -e "PROJECT_ID=[YOUR_PROJECT_ID]"  gcr.io/cloud-datalab/datalab:local

When using Stackdriver Monitoring, [YOUR_PROJECT_ID] should be set to the Stackdriver account whose resources you will access. You can optionally set or change this ID from within Cloud Datalab.

The Cloud Datalab Interface

To see the Cloud Datalab interface, browse to the URL http://127.0.0.1:8081/ or click the following button. If this is the first time you've used Cloud Datalab, you are asked to agree to the terms of service.

Go to your running Cloud Datalab

In the Cloud Datalab docs/ folder you will find several Datalab getting started notebooks you can explore. To go right to Stackdriver Monitoring in Cloud Datalab, continue reading this document.

Log in to Cloud Datalab

To use Google Cloud Platform services such as Stackdriver Monitoring from Cloud Datalab, you must give it permission by logging in:

1. In the Cloud Datalab interface, click the top-right Account icon and select Sign In.

2. Agree to the GCP permissions needed.

Stackdriver Monitoring

Cloud Datalab is installed with several Stackdriver Monitoring interactive tutorials:

Getting started

Shows how to import the Python Stackdriver API into Cloud Datalab and set your default Stackdriver account project ID. There is sample code that calls the API and retrieves monitoring data from your project.

Group metrics

Shows how to look at the group structure in a project and how to use groups to filter and aggregate metric data. If your Stackdriver account does not have groups, change to another Stackdriver account that does.

Time-shifted data

Shows how to transform time series data in interesting ways. Since your project might not have enough VM instances to be a good example, the tutorial is set up to optionally use previously-extracted data from a demonstration project.

You can run the tutorials, and optionally modify them, as explained in the following section.

Running the tutorials

To run the tutorials, do the following:

1. Click on docs, tutorials, and Stackdriver Monitoring in the Cloud Datalab interface. You should see the following page:

   

2. Select the tutorial. Click on the name of the tutorial you want to run.

3. Set the project ID. When using Stackdriver Monitoring with Cloud Datalab, the "project ID" should always be the ID of a Stackdriver account. If you did not set your project ID when you ran the Cloud Datalab Docker container, or if you want to change the project ID, then un-comment and edit the set_datalab_project_id line near the beginning of the tutorial. For example, if your Stackdriver account is named wonderful-project, then here is what the edited line should look like:

   set_datalab_project_id('wonderful-project')
   

4. Run the tutorial code. From the menu bar at the top of the interface, select Run > Run all cells. This reruns all the code in the tutorial using your current project ID.

Feel free to modify the code in the tutorials and try out your changes. You can run the code in a single cell by clicking on the cell and choosing Run from the menu to the left of the cell. You can also create your own notebooks.

Clean up

To avoid incurring charges to your Google Cloud Platform account for the resources used in this quickstart:

1. Click on the Running Sessions icon at the top-right of the Cloud Datalab interface, and shut down any notebooks you are not using. You can restart them later if you need to. Close the associated browser tabs or windows.

2. If you don't want to keep the Cloud Datalab container running, type CTRL-C in the terminal window where you started Cloud Datalab.

3. If you installed Docker just for this Quickstart and don't want to keep it, stop and uninstall it.

4. If you created any Stackdriver accounts, projects, or VM instances that you do not want to keep, remove them.

What's next

See the following API reference material:

• The time series query from the Stackdriver Monitoring API v3 google-cloud-python library

• The datalab.stackdriver.monitoring library