.. This file is automatically generated. Do not edit this file directly.

Stackdriver Monitoring Python Samples
===============================================================================

This directory contains samples for Stackdriver Monitoring. `Stackdriver Monitoring `_ collects metrics, events, and metadata from Google Cloud Platform, Amazon Web Services (AWS), hosted uptime probes, application instrumentation, and a variety of common application components including Cassandra, Nginx, Apache Web Server, Elasticsearch and many others. Stackdriver ingests that data and generates insights via dashboards, charts, and alerts.




.. _Stackdriver Monitoring: https://cloud.google.com/monitoring/docs 

Setup
-------------------------------------------------------------------------------


Authentication
++++++++++++++

Authentication is typically done through `Application Default Credentials`_,
which means you do not have to change the code to authenticate as long as
your environment has credentials. You have a few options for setting up
authentication:

#. When running locally, use the `Google Cloud SDK`_

    .. code-block:: bash

        gcloud beta auth application-default login


#. When running on App Engine or Compute Engine, credentials are already
   set-up. However, you may need to configure your Compute Engine instance
   with `additional scopes`_.

#. You can create a `Service Account key file`_. This file can be used to
   authenticate to Google Cloud Platform services from any environment. To use
   the file, set the ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable to
   the path to the key file, for example:

    .. code-block:: bash

        export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service_account.json

.. _Application Default Credentials: https://cloud.google.com/docs/authentication#getting_credentials_for_server-centric_flow
.. _additional scopes: https://cloud.google.com/compute/docs/authentication#using
.. _Service Account key file: https://developers.google.com/identity/protocols/OAuth2ServiceAccount#creatinganaccount

Install Dependencies
++++++++++++++++++++

#. Install `pip`_ and `virtualenv`_ if you do not already have them.

#. Create a virtualenv. Samples are compatible with Python 2.7 and 3.4+.

    .. code-block:: bash

        $ virtualenv env
        $ source env/bin/activate

#. Install the dependencies needed to run the samples.

    .. code-block:: bash

        $ pip install -r requirements.txt

.. _pip: https://pip.pypa.io/
.. _virtualenv: https://virtualenv.pypa.io/

Samples
-------------------------------------------------------------------------------

Authenticating & basic operations
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++



To run this sample:

.. code-block:: bash

    $ python auth.py

    usage: auth.py [-h] project_id
    
    Sample command-line program for retrieving Stackdriver Monitoring API data.
    
    Prerequisites: To run locally, download a Service Account JSON file from
    your project and point GOOGLE_APPLICATION_CREDENTIALS to the file.
    
    This sample is used on this page:
    
        https://cloud.google.com/monitoring/api/authentication
    
    For more information, see the README.md under /monitoring.
    
    positional arguments:
      project_id  Your Google Cloud project ID.
    
    optional arguments:
      -h, --help  show this help message and exit


Labeled custom metrics
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++



To run this sample:

.. code-block:: bash

    $ python labeled_custom_metric.py

    usage: labeled_custom_metric.py [-h] --project_id PROJECT_ID --color COLOR
                                    --size SIZE --count COUNT
    
    Creates, writes, and reads a labeled custom metric.
    
    This is an example of how to use the Stackdriver Monitoring API to create,
    write, and read a labeled custom metric.
    The metric has two labels: color and size, and the data points represent
    the number of shirts of the given color and size in inventory.
    
    Prerequisites: To run locally, download a Service Account JSON file from
    your project and point GOOGLE_APPLICATION_CREDENTIALS to the file.
    
    From App Engine or a GCE instance with the correct scope, the Service
    Account step is not required.
    
    Typical usage: Run the following shell commands on the instance:
        python labeled_custom_metric.py --project_id <project_id> /
        --color yellow  --size large  --count 10
    
    optional arguments:
      -h, --help            show this help message and exit
      --project_id PROJECT_ID
                            Project ID you want to access.
      --color COLOR
      --size SIZE
      --count COUNT


Lightweight custom metrics
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++



To run this sample:

.. code-block:: bash

    $ python labeled_custom_metric.py

    usage: labeled_custom_metric.py [-h] --project_id PROJECT_ID --color COLOR
                                    --size SIZE --count COUNT
    
    Creates, writes, and reads a labeled custom metric.
    
    This is an example of how to use the Stackdriver Monitoring API to create,
    write, and read a labeled custom metric.
    The metric has two labels: color and size, and the data points represent
    the number of shirts of the given color and size in inventory.
    
    Prerequisites: To run locally, download a Service Account JSON file from
    your project and point GOOGLE_APPLICATION_CREDENTIALS to the file.
    
    From App Engine or a GCE instance with the correct scope, the Service
    Account step is not required.
    
    Typical usage: Run the following shell commands on the instance:
        python labeled_custom_metric.py --project_id <project_id> /
        --color yellow  --size large  --count 10
    
    optional arguments:
      -h, --help            show this help message and exit
      --project_id PROJECT_ID
                            Project ID you want to access.
      --color COLOR
      --size SIZE
      --count COUNT




.. _Google Cloud SDK: https://cloud.google.com/sdk/