Metadata-Version: 1.1
Name: python-monclient
Version: 1.0.1
Summary: Monitoring API Client Library
Home-page: https://git.hpcloud.net/mon/python-monclient
Author: Hewlett-Packard
Author-email: UNKNOWN
License: UNKNOWN
Description: Python bindings to the Monitoring API
        =======================================
        
        This is a client library for Monitoring built to interface with the Monitoring API. It
        provides a Python API (the ``monclient`` module) and a command-line tool
        (``mon``).
        
        The Monitoring Client was written using the OpenStack Heat Python client as a framework. 
        
        .. contents:: Contents:
           :local:
        
        Ubuntu Install
        --------------
        Requires:
          - pip - version >= 1.4.  python get-pip.py
          - git - sudo apt-get install git-core
          
        Install Steps:
          - git clone or copy the python-monclient distribution to the server
          - cd python-monclient
          - sudo pip install -r requirements.txt
          - sudo python setup.py install
        
        Command-line API
        ----------------
        Installing this distribution gets you a shell command, ``mon``, that you
        can use to interact with the Monitoring API server.
        
        Usage:
          mon
        
          mon help
        
          mon help <command>
          
          mon -j <command>
          
            This outputs the results in jason format.  Normally output is in table format.
          
        
        The monclient CLI needs the Monitoring API endpoint url and the OS_AUTH_TOKEN to pass to the 
        Monitoring API RESTful interface.  This is provided through environment or CLI 
        parameters.
        
        Environmental Variables
        ~~~~~~~~~~~~~~~~~~~~~~~  
        
        Environmental variables can be sourced, or optionally passed in as CLI arguments.
        It is easiest to source them first and then use the CLI.
        
        When token and endpoint are known::
          
          export OS_AUTH_TOKEN=12345678
          export MON_API_URL=http://192.168.10.4:8080/v2.0/
        
        When using Keystone to obtain the token and endpoint::
          
          export OS_USERNAME=
          export OS_PASSWORD=
          export OS_TENANT_NAME=
          export OS_AUTH_URL=
          export OS_REGION_NAME=
        
        When using Jahmon Vagrant Environment for test - no Keystone::
          
          export OS_AUTH_TOKEN=12345678  (this will be treated as your tenant id by the api)
          export OS_NO_CLIENT_AUTH=1
          export MON_API_URL=http://192.168.10.4:8080/v2.0/
        
        You'll find complete documentation on the shell by running
        ``mon help``::
          
          usage: mon [-j] [--version] [-d] [-v] [-k] [--cert-file CERT_FILE]
                     [--key-file KEY_FILE] [--ca-file CA_FILE] [--timeout TIMEOUT]
                     [--os-username OS_USERNAME] [--os-password OS_PASSWORD]
                     [--os-tenant-id OS_TENANT_ID] [--os-tenant-name OS_TENANT_NAME]
                     [--os-auth-url OS_AUTH_URL] [--os-region-name OS_REGION_NAME]
                     [--os-auth-token OS_AUTH_TOKEN] [--os-no-client-auth]
                     [--mon-api-url MON_API_URL] [--mon-api-version MON_API_VERSION]
                     [--os-service-type OS_SERVICE_TYPE]
                     [--os-endpoint-type OS_ENDPOINT_TYPE]
                     <subcommand> ...
        
          Command-line interface to the mon-client API.
          
          positional arguments:
            <subcommand>
              alarm-create         Create alarm.
              alarm-delete         Delete alarm.
              alarm-history        List alarm state history.
              alarm-list           List alarms for this tenant.
              alarm-patch          Patch the alarm.
              alarm-show           Describe the alarm.
              alarm-update         Update the alarm.
              measurement-list     List measurements for the specified metric.
              metric-create        Create metric.
              metric-list          List metrics for this tenant.
              notification-create  Create notification.
              notification-delete  Delete notification.
              notification-list    List notifications for this tenant.
              notification-show    Describe the notification.
              notification-update  Update notification.
              bash-completion      Prints all of the commands and options to stdout.
              help                 Display help about this program or one of its
                                   subcommands.
          
          optional arguments:
            -j, --json             output raw json response
            --version              Shows the client version and exits.
            -d, --debug            Defaults to env[MON_DEBUG].
            -v, --verbose          Print more verbose output.
            -k, --insecure         Explicitly allow the client to perform "insecure" SSL
                                   (https) requests. The server's certificate will not
                                   be verified against any certificate authorities. This
                                   option should be used with caution.
            --cert-file CERT_FILE  Path of certificate file to use in SSL connection.
                                   This file can optionally be prepended with the
                                   private key.
            --key-file KEY_FILE    Path of client key to use in SSL connection.This
                                   option is not necessary if your key is prepended to
                                   your cert file.
            --ca-file CA_FILE      Path of CA SSL certificate(s) used to verify the
                                   remote server's certificate. Without this option the
                                   client looks for the default system CA certificates.
            --timeout TIMEOUT      Number of seconds to wait for a response.
            --os-username OS_USERNAME
                                   Defaults to env[OS_USERNAME].
            --os-password OS_PASSWORD
                                   Defaults to env[OS_PASSWORD].
            --os-tenant-id OS_TENANT_ID
                                   Defaults to env[OS_TENANT_ID].
            --os-tenant-name OS_TENANT_NAME
                                   Defaults to env[OS_TENANT_NAME].
            --os-auth-url OS_AUTH_URL
                                   Defaults to env[OS_AUTH_URL].
            --os-region-name OS_REGION_NAME
                                   Defaults to env[OS_REGION_NAME].
            --os-auth-token OS_AUTH_TOKEN
                                   Defaults to env[OS_AUTH_TOKEN].
            --os-no-client-auth    Do not contact keystone for a token. Defaults to
                                   env[OS_NO_CLIENT_AUTH].
            --mon-api-url MON_API_URL
                                   Defaults to env[MON_API_URL].
            --mon-api-version MON_API_VERSION
                                   Defaults to env[MON_API_VERSION] or 2_0
            --os-service-type OS_SERVICE_TYPE
                                   Defaults to env[OS_SERVICE_TYPE].
            --os-endpoint-type OS_ENDPOINT_TYPE
                                   Defaults to env[OS_ENDPOINT_TYPE].
          
          See "mon help COMMAND" for help on a specific command.
        
        
        Metrics Examples
        ~~~~~~~~~~~~~~~~
        Note: this is not meant to be a complete list.
        
        metric-create::
          
          mon metric-create cpu1 123.40
          mon metric-create metric1 1234.56 --dimensions instance_id=123,service=ourservice
          mon metric-create metric1 2222.22 --dimensions instance_id=123,service=ourservice
          mon metric-create metric1 3333.33 --dimensions instance_id=222,service=ourservice
        
        metric-list::
          
          mon metric-list
          +---------+--------------------+
          | name    | dimensions         |
          +---------+--------------------+
          | cpu1    |                    |
          | metric1 | instance_id:123    |
          |         | service:ourservice |
          +---------+--------------------+
        
        measurement-list::
          
          mon measurement-list metric1 2014-01-01T00:00:00Z
          +---------+--------------------+----------------+----------------------+--------------+
          | name    | dimensions         | measurement_id | timestamp            | value        |
          +---------+--------------------+----------------+----------------------+--------------+
          | metric1 | instance_id:123    |     723885     | 2014-05-08T21:46:32Z |      1234.56 |
          |         | service:ourservice |     725951     | 2014-05-08T21:48:50Z |      2222.22 |
          | metric1 | instance_id:222    |     726837     | 2014-05-08T21:49:47Z |      3333.33 |
          |         | service:ourservice |                |                      |              |
          +---------+--------------------+----------------+----------------------+--------------+
          
          mon measurement-list metric1 2014-01-01T00:00:00Z --dimensions instance_id=123
          +---------+--------------------+----------------+----------------------+--------------+
          | name    | dimensions         | measurement_id | timestamp            | value        |
          +---------+--------------------+----------------+----------------------+--------------+
          | metric1 | instance_id:123    |     723885     | 2014-05-08T21:46:32Z |      1234.56 |
          |         | service:ourservice |     725951     | 2014-05-08T21:48:50Z |      2222.22 |
          +---------+--------------------+----------------+----------------------+--------------+
          
        
        Notifications Examples
        ~~~~~~~~~~~~~~~~~~~~~~
        Note: this is not meant to be a complete list.
        
        notification-create::
          
          mon notification-create cindyemail1 EMAIL cindy.employee@hp.com
        
        notification-list::
          
          mon notification-list
          +---------------+--------------------------------------+-------+----------------------+
          | name          | id                                   | type  | address              |
          +---------------+--------------------------------------+-------+----------------------+
          | cindyemail1   | 5651406c-447d-40bd-b868-b2b3e6b59e32 | EMAIL |cindy.employee@hp.com |
          +---------------+--------------------------------------+-------+----------------------+
        
        
        Alarms Examples
        ~~~~~~~~~~~~~~~
        Note: this is not meant to be a complete list.
        
        alarm-create::
          
          mon alarm-create cpu1alarm 'cpu1>10'
          mon alarm-create cpu2alarm
          mon alarm-create cindyalarm1 'avg(metric1{instance_id=123)>=10' --description 'avg greater than thresh' --alarm-actions 5651406c-447d-40bd-b868-b2b3e6b59e32
        
        alarm-list::
          
          mon alarm-list
          +-------------+--------------------------------------+------------------------------------+--------------+-----------------+
          | name        | id                                   | expression                         | state        | actions_enabled |
          +-------------+--------------------------------------+------------------------------------+--------------+-----------------+
          | cpu1alarm   | 67b9f4cc-3d57-4c6c-848c-555d0b3a8579 | cpu1>10                            | UNDETERMINED | True            |
          | cpu2alarm   | 9e6b9fad-ef1b-4030-beab-10678bcc758a | cpu1>10                            | UNDETERMINED | True            |
          | cindyalarm1 | c81e1d40-2115-4557-96f4-eda6b8823fd6 | avg(metric1{instance_id=123}) >= 10| UNDETERMINED | True            |
          +-------------+--------------------------------------+------------------------------------+--------------+-----------------+
        
        alarm-show::
          
          mon alarm-show c81e1d40-2115-4557-96f4-eda6b8823fd6
          (output not shown for now - changing schema)
        
        alarm-patch::
          
          mon alarm-patch c81e1d40-2115-4557-96f4-eda6b8823fd6 --state OK
        
        
        Python API
        ----------
        
        There's also a complete Python API.
        
        In order to use the python api directly, you must first obtain an auth token and 
        identify the monitoring api endpoint.
        
        The api_version matches the version of the Monitoring API.  Currently it is 'v2_0'.
        
        When calling the commands, refer to monclient.v2_0.shell.py 'do_<command>'
        to see the required and optional fields for each command.
        
        Refer to this example in python-monclient/client_api_example.py::
            
          from monclient import client
          import monclient.exc as exc
          import time
           
          api_version = '2_0'
          endpoint = 'http://192.168.10.4:8080/v2.0'
          kwargs = {
              'token': '12345678'
          }
           
          # construct the mon client
          mon_client = client.Client(api_version, endpoint, **kwargs)
           
          # call the metric-create command
          dimensions = {'instance_id': '12345', 'service': 'hello'}
          fields = {}
          fields['name'] = 'cindy1'
          fields['dimensions'] = dimensions
          fields['timestamp'] = time.time()
          fields['value'] = 222.333
          try:
              resp = mon_client.metrics.create(**fields)
          except exc.HTTPException as he:
              print(he.code)
              print(he.message)
          else:
              print(resp)
        
        
        
        License
        -------
        
        Copyright (c) 2014 Hewlett-Packard Development Company, L.P.
        
        Licensed under the Apache License, Version 2.0 (the "License");
        you may not use this file except in compliance with the License.
        You may obtain a copy of the License at
        
            http://www.apache.org/licenses/LICENSE-2.0
            
        Unless required by applicable law or agreed to in writing, software
        distributed under the License is distributed on an "AS IS" BASIS,
        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
        implied.
        See the License for the specific language governing permissions and
        limitations under the License.
        
        
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
