This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

This repository includes the necessary Python client libraries to access Hawkular remotely. Currently we only have a driver for the metrics component as it’s the most mature of the components.

Introduction

Python client to access Hawkular-Metrics, an abstraction to invoke REST-methods on the server endpoint using urllib2. No external dependencies, works with Python 2.7.x (tested on 2.7.5/2.7.6 and 2.7.10) and Python 3.4.x (tested with the Python 3.4.2, might work with newer versions also)

Installation

To install, run python setup.py install if you installed from source code, or pip install hawkular-client if using pip.

Usage

To use hawkular-client-python in your own program, after installation import from hawkular the class HawkularMetricsClient and instantiate it. After this, push dicts with keys id, timestamp and value with put or use assistant method create to send events. pydoc gives the list of allowed parameters for each function.

Timestamps should be in the milliseconds after epoch and numeric values should be float. The client provides a method to request current time in milliseconds, time_millis()

See metrics_test.py for more detailed examples and Hawkular-Metrics documentation for more detailed explanation of available features.

General

When a method wants a metric_type one can use the shortcuts of from MetricType class (Gauge, Availability and Counter). For availability values, one can use values Availability.Up and Availability.Down to simplify usage.

To instantiate the client, use HawkularMetricsClient() method. It requires something given as tenant_id, even if the tenant does not exists yet (it is not auto-created, you have to call create_tenant(tenant_id) to create it). To change the target tenant_id, use tenant(tenant_id)

>>> from hawkular.metrics import HawkularMetricsClient, MetricType
>>> client = HawkularMetricsClient(tenant_id='python_test')

Creating and modifying metric definitions

While creating a metric definition is not required, it is recommended to avoid duplicate metric_ids, which could cause silent data overwriting. It is possible to define a custom data retention times as well as tags for each metric. To create a metric, use method create_metric_definition(metric_id, metric_type, **tags) The only reserved keyword for tags is dataRetention, which will change the dataRetention time, other tag names are used for user’s metadata.

Example:

>>> client.create_metric_definition(MetricType.Gauge, 'example.doc.1', units='bytes', env='test')
True
>>> client.query_metric_definitions(MetricType.Gauge)
[{'type': 'gauge', 'id': 'example.doc.1', 'tags': {'units': 'bytes', 'env': 'test'}, 'tenantId': 'python_test', 'dataRetention': 7}]

Modifying metric definition tags

One powerful feature of Hawkular-Metrics is the tagging feature that allows one to define descriptive metadata for any metric. Tags can be added when creating a metric definition (see above), but also modified later. By tagging the definitions, you can search for matching definitions with the tag query language.

Example:

>>> client.create_metric_definition(MetricType.Gauge, 'example.doc.2', units='bytes', env='test', hostname='testenv01')
>>> client.query_metric_tags(MetricType.Gauge, 'example.doc.2')
{'units': 'bytes', 'hostname': 'testenv01', 'env': 'test'}

To search all the metric definitions with a given tags and tag values, use the query_definitions()

>>> client.query_metric_definitions(MetricType.Gauge, hostname='testenv.*')
[{'type': 'gauge', 'id': 'example.doc.2', 'tags': {'units': 'bytes', 'hostname': 'testenv01', 'env': 'test'}, 'tenantId': 'python_test', 'dataRetention': 7}]

It is also possible to query all the available tag values, in case you want to list for example the hostnames that have metrics information gathered.

>>> client.query_tag_values(hostname='*')
{'hostname': ['testenv01', 'prodenv01']}

Pushing new values

All the methods that allow pushing values can accept both availability status as well as float values. It is possible to push multiple metrics with multiple values per metric in one call to the Hawkular-Metrics. However for convenience, a method which will push just one value for one metric is also provided. To push availability values, use MetricType.Availability and values Availability.Up and Availability.Down, otherwise the syntax is equal.

create_datapoint(value) and create_metric(metric_type, metric_id, datapoints) return the necessary structures requested by the multi-functions.

Example pushing a multiple values:

>>> from hawkular.metrics import create_datapoint, create_metric, time_millis
>>> datapoint = create_datapoint(float(4.35), time_millis())
>>> datapoint2 = create_datapoint(float(4.42), time_millis() + 10)
>>> metric = create_metric(MetricType.Gauge, 'example.doc.1', [datapoint, datapoint2])
>>> client.put(metric)

And a shortcut method to push just a single value with automatically generated timestamp:

>>> client.push(MetricType.Gauge, 'example.doc.1', float(4.24))

To push multiple metrics with multiple values per metric, see metrics_test.py and method test_add_multi_metrics_and_datapoints().

Querying metric values

Querying metrics and its raw values happens through the method query_metric(metric_type, metric_id, **query_options). Available options are listed in the Hawkular-Metrics documentation. To query for aggregated values, use the method query_metric_stats(metric_type, metric_id, **query_options)

Example querying for raw values:

>>> client.query_metric(MetricType.Gauge, 'example.doc.1')
[{'value': 4.24, 'timestamp': 1462363124102}, {'value': 4.42, 'timestamp': 1462363032249}, {'value': 4.35, 'timestamp': 1462362981464}]
>>> client.query_metric(MetricType.Gauge, 'example.doc.1', start=1462363032249)
[{'value': 4.24, 'timestamp': 1462363124102}, {'value': 4.42, 'timestamp': 1462363032249}]

For aggregated metrics:

>>> client.query_metric_stats(MetricType.Gauge, 'example.doc.1', buckets=2, percentiles='90.0,95.0')
[{'empty': True, 'start': 1462334779765, 'end': 1462349179765}, {'empty': False, 'avg': 4.336666666666667, 'start': 1462349179765, 'min': 4.24, 'samples': 3, 'sum': 13.01, 'max': 4.42, 'end': 1462363579765, 'median': 4.35, 'percentiles': [{'value': 4.35, 'quantile': 0.9}, {'value': 4.35, 'quantile': 0.95}]}]
>>>

Method documentation

Method documentation is available with pydoc hawkular

Release History

Release History

0.4.5

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
hawkular-client-0.4.5.tar.gz (9.4 kB) Copy SHA256 Checksum SHA256 Source Sep 14, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting