Monasca API Client Library
Project description
This is a client library for Monasca built to interface with the Monasca API. It provides a Python API (the monascaclient module) and a command-line tool (monasca).
The Monasca Client was written using the OpenStack Heat Python client as a framework.
Ubuntu Install
- Requires:
pip - version >= 1.4. python get-pip.py
- Install It:
sudo pip install python-monascaclient
- Alternative Manual Install Steps:
cd to your python-monascaclient repo
sudo pip install -r requirements.txt
python setup.py install
Command-line API
Installing this distribution gets you a shell command, monasca, that you can use to interact with the Monitoring API server.
- Usage:
monasca
monasca help
monasca help <command>
monasca -j <command>
This outputs the results in jason format. Normally output is in table format.
The monascaclient CLI needs the Monasca API endpoint url and the OS_AUTH_TOKEN to pass to the Monasca 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=XXX export MONASCA_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 Vagrant Environment with middleware disabled:
export OS_AUTH_TOKEN=82510970543135 export OS_NO_CLIENT_AUTH=1 export MONASCA_API_URL=http://192.168.10.4:8080/v2.0/
The Monasca API will treat the auth token as the tenant ID when Keystone is not enabled.
You’ll find complete documentation on the shell by running monasca help:
usage: monasca [-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 MONASCA_API_URL] [--mon-api-version MONASCA_API_VERSION]
[--os-service-type OS_SERVICE_TYPE]
[--os-endpoint-type OS_ENDPOINT_TYPE]
<subcommand> ...
Command-line interface to the monasca-client API.
positional arguments:
<subcommand>
alarm-definition-create Create an alarm definition.
alarm-definition-delete Delete the alarm definition.
alarm-definition-list List alarm definitions for this tenant.
alarm-definition-patch Patch the alarm definition.
alarm-definition-show Describe the alarm definition.
alarm-definition-update Update the alarm definition.
alarm-delete Delete the alarm.
alarm-history Alarm state history.
alarm-history-list List alarms 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-create-raw Create metric from raw json body.
metric-list List metrics for this tenant.
metric-statistics List measurement statistics for the specified metric.
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[MONASCA_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 MONASCA_API_URL
Defaults to env[MONASCA_API_URL].
--mon-api-version MONASCA_API_VERSION
Defaults to env[MONASCA_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.
Bash Completion
Basic command tab completion can be enabled by sourcing the bash completion script.
source /usr/local/share/monasca.bash_completion
Metrics Examples
Note: To see complete usage: ‘monasca help’ and ‘monasca help <command>’
metric-create:
monasca metric-create cpu1 123.40 monasca metric-create metric1 1234.56 --dimensions instance_id=123,service=ourservice monasca metric-create metric1 2222.22 --dimensions instance_id=123,service=ourservice monasca metric-create metric1 3333.33 --dimensions instance_id=222,service=ourservice
metric-list:
monasca metric-list +---------+--------------------+ | name | dimensions | +---------+--------------------+ | cpu1 | | | metric1 | instance_id:123 | | | service:ourservice | +---------+--------------------+
measurement-list:
monasca 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 | | | | +---------+--------------------+----------------+----------------------+--------------+ monasca 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: To see complete usage: ‘monasca help’ and ‘monasca help <command>’
notification-create:
monasca notification-create cindyemail1 EMAIL cindy.employee@hp.com monasca notification-create myapplication WEBHOOK http://localhost:5000
notification-list:
monasca notification-list +---------------+--------------------------------------+-------+----------------------+ | name | id | type | address | +---------------+--------------------------------------+-------+----------------------+ | cindyemail1 | 5651406c-447d-40bd-b868-b2b3e6b59e32 | EMAIL |cindy.employee@hp.com | | myapplication | 55905ce2-91e3-41ce-b45a-de7032f8d718 | WEBHOOK |http://localhost:5000 +---------------+--------------------------------------+-------+----------------------+
Alarms Examples
Note: To see complete usage: ‘monasca help’ and ‘monasca help <command>’
alarm-definition-create:
monasca alarm-definition-create alarmPerHost "max(cpu.load_avg_1_min) > 0" --match-by hostname
alarm-definition-list:
+--------------+--------------------------------------+-----------------------------+----------+-----------------+ | name | id | expression | match_by | actions_enabled | +--------------+--------------------------------------+-----------------------------+----------+-----------------+ | alarmPerHost | 4bf6bfc2-c5ac-4d57-b7db-cf5313b05412 | max(cpu.load_avg_1_min) > 0 | hostname | True | +--------------+--------------------------------------+-----------------------------+----------+-----------------+
alarm-definition-show:
monasca alarm-definition-show 4bf6bfc2-c5ac-4d57-b7db-cf5313b05412 +----------------------+----------------------------------------------------------------------------------------------------+ | Property | Value | +----------------------+----------------------------------------------------------------------------------------------------+ | actions_enabled | true | | alarm_actions | [] | | description | "" | | expression | "max(cpu.load_avg_1_min) > 0" | | id | "4bf6bfc2-c5ac-4d57-b7db-cf5313b05412" | | links | href:http://192.168.10.4:8080/v2.0/alarm-definitions/4bf6bfc2-c5ac-4d57-b7db-cf5313b05412,rel:self | | match_by | [ | | | "hostname" | | | ] | | name | "alarmPerHost" | | ok_actions | [] | | severity | "LOW" | | undetermined_actions | [] | +----------------------+----------------------------------------------------------------------------------------------------+
alarm-definition-delete:
monasca alarm-definition-delete 4bf6bfc2-c5ac-4d57-b7db-cf5313b05412
alarm-list:
monasca alarm-list +--------------------------------------+--------------------------------------+--------------+--------------------+---------------------+----------+-------+ | id | alarm_definition_id | alarm_name | metric_name | metric_dimensions | severity | state | +--------------------------------------+--------------------------------------+--------------+--------------------+---------------------+----------+-------+ | 35122ab6-3007-41e7-9654-22e97b387f75 | 754276aa-a892-47c0-b74a-9c96ed84a712 | alarmPerHost | cpu.load_avg_1_min | hostname: mini-mon | LOW | ALARM | | | | | | service: monitoring | | | | 54ab81e3-b4d6-4fd0-9fec-707909f2d576 | 754276aa-a892-47c0-b74a-9c96ed84a712 | alarmPerHost | cpu.load_avg_1_min | hostname: devstack | LOW | ALARM | | | | | | service: monitoring | | | +--------------------------------------+--------------------------------------+--------------+--------------------+---------------------+----------+-------+
alarm-history:
monasca alarm-history 9d748b72-939b-45e7-a807-c0c5ad88d3e4
+--------------------------------------+-----------+--------------+------------------------------------------------------------------------------+-------------+--------------------+---------------------+--------------------------+
| alarm_id | new_state | old_state | reason | reason_data | metric_name | metric_dimensions | timestamp |
+--------------------------------------+-----------+--------------+------------------------------------------------------------------------------+-------------+--------------------+---------------------+--------------------------+
| 9d748b72-939b-45e7-a807-c0c5ad88d3e4 | ALARM | UNDETERMINED | Thresholds were exceeded for the sub-alarms: [max(cpu.load_avg_1_min) > 0.0] | {} | cpu.load_avg_1_min | hostname: mini-mon | 2014-10-14T21:14:11.000Z |
| | | | | | | service: monitoring | |
+--------------------------------------+-----------+--------------+------------------------------------------------------------------------------+-------------+--------------------+---------------------+--------------------------+
alarm-patch:
monasca alarm-patch fda5537b-1550-435f-9d6c-262b7e05065b --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 monasca api endpoint. The user can obtain the token and endpoint using the keystone client api: http://docs.openstack.org/developer/python-keystoneclient/. The service catalog name for our API endpoint is “monasca”.
Start using the monascaclient API by constructing the monascaclient client.Client class. The Client class takes these parameters: api_version, endpoint, and token. The Client class is used to call all monasca-api resource commands (i.e. client.Client.metrics.create(fields)).
Long running users of Client will recieve an indication that the keystone token has expired when they receive an HTTP response code of 401 Unauthorized from the monasca-API. In this case, it is up to the user to get a new token from keystone which can be passed into the client.Client.replace_token(token) method.
The api_version matches the version of the Monasca API. Currently it is ‘v2_0’.
When calling the commands, refer to monascaclient.v2_0.shell.py ‘do_<command>’ to see the required and optional fields for each command.
Refer to this example in python-monascaclient/client_api_example.py:
from monascaclient import client
from monascaclient import ksclient
import monascaclient.exc as exc
import time
api_version = '2_0'
# Authenticate to Keystone
keystone_url = 'http://keystone:5000/v3'
ks = ksclient.KSClient(auth_url=keystone_url, username='user', password='password')
# construct the mon client
monasca_client = client.Client(api_version, ks.monasca_url, token=ks.token)
# 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 = monasca_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
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.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for python-monascaclient-1.0.9.tar.gz
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 38594f852d3ac3f8524cc20dfb8cc3c2e683d9010f0c82cd8599a91cf22cc7a9 |
|
| MD5 | 8209e29e2bbdd1646f7701505a393fcd |
|
| BLAKE2b-256 | 93a2114683ff49d48564c2deb97555adf0d2fbcca318f41400733d9f8e1d69d7 |
Hashes for python_monascaclient-1.0.9-py2.py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 92e1cf11ed0732dae939f864e4b16eb63121094e6d5eae92f2115c6cd34a4ea4 |
|
| MD5 | b0989c81519142faff626dfc27c60447 |
|
| BLAKE2b-256 | 694ff7f4187b83d72d7b732cb188a166e1e2e1efc0e6327436c62ca63831cda7 |
