{"id":21630469,"url":"https://github.com/hawkular/hawkular-client-python","last_synced_at":"2026-02-14T13:02:37.115Z","repository":{"id":30768517,"uuid":"34325237","full_name":"hawkular/hawkular-client-python","owner":"hawkular","description":"Python client for Hawkular","archived":false,"fork":false,"pushed_at":"2018-03-14T11:34:34.000Z","size":139,"stargazers_count":8,"open_issues_count":3,"forks_count":17,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-11-12T20:25:05.231Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hawkular.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-21T12:21:39.000Z","updated_at":"2018-09-04T12:24:11.000Z","dependencies_parsed_at":"2022-09-09T23:24:56.161Z","dependency_job_id":null,"html_url":"https://github.com/hawkular/hawkular-client-python","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-client-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-client-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-client-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hawkular%2Fhawkular-client-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hawkular","download_url":"https://codeload.github.com/hawkular/hawkular-client-python/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226260538,"owners_count":17596495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-25T02:11:06.075Z","updated_at":"2026-02-14T13:02:37.108Z","avatar_url":"https://github.com/hawkular.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/hawkular/hawkular-client-python.svg?branch=master)](https://travis-ci.org/hawkular/hawkular-client-python)\n\nhawkular-client-python\n=========================\n\nThis repository includes the necessary Python client libraries to access Hawkular remotely. Currently we only have a driver for the metrics and alerts components.\n\n## Introduction\n\nPython 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.14) and Python 3.4.x / 3.5.x / 3.6.x (tested with the Python 3.4.2, Python 3.5.3 and Python 3.6.4, might work with newer versions also).\n\n## License and copyright\n\n```\n   Copyright 2015-2018 Red Hat, Inc. and/or its affiliates\n   and other contributors.\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n```\n\n## Installation\n\nTo install, run ``python setup.py install`` if you installed from source code, or ``pip install hawkular-client`` if using pip.\n\n## Metrics Usage\n\nTo 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.\n\nThe client provides a method to request current time in milliseconds, ``time_millis()`` that's accepted by the methods, but you can use ``datetime`` and ``timedelta`` to control the time also when sending requests to the Hawkular-Metrics. \n\nSee ``tests/test_metrics.py`` for more detailed examples and [Hawkular-Metrics documentation](http://www.hawkular.org/hawkular-metrics/docs/user-guide/) for more detailed explanation of available features.\n\n### General\n\nWhen 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.\n\nTo 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)``\n\n```python\n\u003e\u003e\u003e from hawkular.metrics import HawkularMetricsClient, MetricType\n\u003e\u003e\u003e client = HawkularMetricsClient(tenant_id='python_test')\n```\n\n### Creating and modifying metric definitions\n\nWhile 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.\n\nExample:\n\n```python\n\u003e\u003e\u003e client.create_metric_definition(MetricType.Gauge, 'example.doc.1', units='bytes', env='test')\nTrue\n\u003e\u003e\u003e client.query_metric_definitions(MetricType.Gauge)\n[{'type': 'gauge', 'id': 'example.doc.1', 'tags': {'units': 'bytes', 'env': 'test'}, 'tenantId': 'python_test', 'dataRetention': 7}]\n```\n\n### Modifying metric definition tags\n\nOne 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.\n\nExample:\n\n```python\n\u003e\u003e\u003e client.create_metric_definition(MetricType.Gauge, 'example.doc.2', units='bytes', env='test', hostname='testenv01')\n\u003e\u003e\u003e client.query_metric_tags(MetricType.Gauge, 'example.doc.2')\n{'units': 'bytes', 'hostname': 'testenv01', 'env': 'test'}\n```\n\nTo search all the metric definitions with a given tags and tag values, use the ``query_definitions()``\n\n```python\n\u003e\u003e\u003e client.query_metric_definitions(MetricType.Gauge, hostname='testenv.*')\n[{'type': 'gauge', 'id': 'example.doc.2', 'tags': {'units': 'bytes', 'hostname': 'testenv01', 'env': 'test'}, 'tenantId': 'python_test', 'dataRetention': 7}]\n```\n\nIt 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.\n\n```python\n\u003e\u003e\u003e client.query_tag_values(hostname='*')\n{'hostname': ['testenv01', 'prodenv01']}\n```\n\n### Pushing new values\n\nAll 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.\n\n``create_datapoint(value)`` and ``create_metric(metric_type, metric_id, datapoints)`` return the necessary structures requested by the multi-functions.\n\nExample pushing a multiple values:\n\n```python\n\u003e\u003e\u003e from hawkular.metrics import create_datapoint, create_metric, time_millis\n\u003e\u003e\u003e t = datetime.utcnow()\n\u003e\u003e\u003e datapoint = create_datapoint(float(4.35), t)\n\u003e\u003e\u003e datapoint2 = create_datapoint(float(4.42), t + timedelta(seconds=10))\n\u003e\u003e\u003e metric = create_metric(MetricType.Gauge, 'example.doc.1', [datapoint, datapoint2])\n\u003e\u003e\u003e client.put(metric)\n```\n\nAnd a shortcut method to push just a single value with automatically generated timestamp:\n\n```python\n\u003e\u003e\u003e client.push(MetricType.Gauge, 'example.doc.1', float(4.24))\n```\n\nTo push multiple metrics with multiple values per metric, see metrics_test.py and method ``test_add_multi_metrics_and_datapoints()``.\n\n### Querying metric values\n\nQuerying 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)``\n\nExample querying for raw values:\n\n```python\n\u003e\u003e\u003e client.query_metric(MetricType.Gauge, 'example.doc.1')\n[{'value': 4.24, 'timestamp': 1462363124102}, {'value': 4.42, 'timestamp': 1462363032249}, {'value': 4.35, 'timestamp': 1462362981464}]\n\u003e\u003e\u003e client.query_metric(MetricType.Gauge, 'example.doc.1', start=1462363032249)\n[{'value': 4.24, 'timestamp': 1462363124102}, {'value': 4.42, 'timestamp': 1462363032249}]\n```\n\nFor aggregated metrics:\n\n```python\n\u003e\u003e\u003e client.query_metric_stats(MetricType.Gauge, 'example.doc.1', buckets=2, percentiles='90.0,95.0')\n[{'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}]}]\n\u003e\u003e\u003e\n```\n\n## Method documentation\n\nMethod documentation is available with ``pydoc hawkular``\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhawkular%2Fhawkular-client-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhawkular%2Fhawkular-client-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhawkular%2Fhawkular-client-python/lists"}