The goal of the circonus package is to combine the ease of use of the requests.Response API with the robust Circonus REST API.
The majority of functionality is provided by methods belonging to the CirconusClient. Most methods return a requests.Response object directly. This gives access to most of the information that requests.request() had when the API call was made, along with the response details.
The Circonus REST API returns a JSON encoded response that is available via the requests.Response.json() method on the returned object. In the event of an error the details will available there as well.
Construct a CirconusClient.
| Parameters: | |
|---|---|
| Return type: |
Usage:
>>> from circonus import CirconusClient
>>> circonus = CirconusClient("my-circonus-app", "generated-by-circonus-ui")
>>> response = circonus.get("/user/current")
>>> response.json()
{u'_cid': u'/user/1234',
u'contact_info': {u'sms': u'', u'xmpp': u''},
u'email': u'user@example.com',
u'firstname': u'Ewe',
u'lastname': u'Sure'}
Get the resource at resource type or cid via requests.get().
| Parameters: |
|
|---|---|
| Return type: |
If a resource type is given, e.g., /user, a list of resources will exist in the Response JSON.
If a cid is given, e.g., /check_bundle/123456, a single resource will exist in the Response JSON.
Create the resource type with data via requests.post().
| Parameters: | |
|---|---|
| Return type: |
Update the resource at cid with data via requests.put().
| Parameters: | |
|---|---|
| Return type: |
Delete the resource at cid via requests.delete().
| Parameters: |
|
|---|---|
| Return type: |
Context manager and decorator for creating Annotation instances.
| Parameters: | |
|---|---|
| Return type: | Annotation |
If rel_metrics is given, the metric names should be specified in the fully qualified format <digits>_<string> as required by the Circonus API documentation for annotation.
Create an Annotation instance immediately.
| Parameters: |
|
|---|---|
| Return type: | Annotation |
Note: sub-second annotation time resolution is not supported by Circonus.
stop defaults to the value of start if it is not given.
If rel_metrics is given, the metric names should be specified in the fully qualified format <digits>_<string> as required by the Circonus API documentation for annotation.
Create a CPU graph from the collectd check_bundle.
| Parameters: | |
|---|---|
| Return type: | requests.Response or None |
None is returned if no data to create the graph could be found in check_bundle.
Create a disk free graph from the collectd check_bundle for mount_dir on target.
| Parameters: | |
|---|---|
| Return type: | requests.Response or None |
None is returned if no data to create the graph could be found in check_bundle.
Create several graphs from the collectd check_bundle.
| Parameters: |
|
|---|---|
| Return type: |
mount_dirs should be a list of directories where devices are mounted. df graphs will be created for each.
interface_names should be a list of network interface device names. interface graphs will be created for each.
titles should be a dict instance mapping a key representing the collectd plugin name to a title for the graph representing it. For example:
>>> {"cpu": "test.example.com CPU", "df": "test.example.com Disk"}
Return True if all collectd graphs were created successfully, False otherwise, along with a list of requests.Response instances for requests made.
Create an interface graph from the collectd check_bundle.
| Parameters: | |
|---|---|
| Return type: | requests.Response or None |
None is returned if no data to create the graph could be found in check_bundle.
Create a memory graph from the collectd check_bundle.
| Parameters: | |
|---|---|
| Return type: | requests.Response or None |
None is returned if no data to create the graph could be found in check_bundle.
Update the resource at cid to have new_tags added to it via update().
| Parameters: | |
|---|---|
| Return type: | requests.Response or False |
False is returned in instances where a request to update the resource was not necessary because the resource is already tagged with new_tags.
Several functions exist that CirconusClient depends on and may be useful elsewhere:
Get a valid fully qualified Circonus API URL for the given resource type or cid.
| Parameters: | resource_type_or_cid (str) – The resource type or cid representing a specific resource. |
|---|---|
| Returns: | The API URL. |
| Return type: | str |
Decorator to ensure that common tags exist on resources.
Only resources which support tagging via the Circonus API will be affected.
Decorator for logging any HTTPError raised by a request.
| Raises: | requests.exceptions.HTTPError |
|---|
Construct an Annotation.
| Parameters: |
|---|
If rel_metrics is given, the metric names should be specified in the fully qualified format <digits>_<string> as required by the Circonus API documentation for annotation.
Create an annotation from the current state.
Create graph data from a collectd check bundle containing cpu metrics.
A compiled regular expression which matches collectd metrics.
Ordered list of metric suffixes.
This list is used to filter and sort metrics in preparation for creating a graph.
A compiled regular expression which captures CPU number from the CPU metric.
Get a list of datapoints from sorted metrics.
| Parameters: | |
|---|---|
| Return type: | :py:class`list` |
Get graph data for check_bundle.
| Parameters: | |
|---|---|
| Return type: |
title defaults to using check_bundle["target"].
Get a sorted list of metrics from metrics.
| Parameters: | metrics (list) – The metrics to sort. |
|---|
The CPU metrics are sorted by:
Get metrics with the stack attribute added.
| Parameters: | |
|---|---|
| Return type: |
Each CPU will be added to a stack group equal to that CPU’s number. CPU idle metrics are hidden by default. metrics is not modified by this function.
Create graph data from a collectd check bundle containing df metrics.
A compiled regular expression which matches collectd metrics.
Ordered list of metric suffixes.
This list is used to filter and sort metrics in preparation for creating a graph.
Get a list of datapoints from sorted metrics.
| Parameters: | |
|---|---|
| Return type: |
Get graph data for check_bundle.
| Parameters: | |
|---|---|
| Return type: |
title defaults to using check_bundle["target"]. df and mount_dir will be appended to title.
Get disk free metrics from metrics for mount_dir.
| Parameters: | |
|---|---|
| Return type: |
Get sorted disk free metrics from metrics.
| Parameters: | metrics (list) – The metrics to sort. |
|---|---|
| Return type: | list |
Is metric_name the collectd representation of mount_dir?
collectd represents mount directories with / as -. This makes it impossible to know if a - in a collectd mount directory was a / or a - on the host, e.g., a mount directory may be /mnt/solr-home and the metric name representing it may be df`mnt-solr-home`df_complex`free.
This function takes a naïve approach and removes all punctuation from both directory names before comparing them.
Both directory names are coerced with unicode() before translation because requests encodes responses in UTF-8 by default and Python has different signatures for the function string.translate() and the method str.translate() method.
Create graph data for several collectd graphs.
Get collectd graph data for check_bundle.
| Parameters: | |
|---|---|
| Return type: |
titles should be a dict instance mapping a key representing the collectd plugin name to a title for the graph representing it. For example:
>>> {"cpu": "test.example.com CPU", "df": "test.example.com Disk"}
The returned list will only contain valid graph data.
Create graph data from a collectd check bundle.
A compiled regular expression which matches collectd metrics.
Ordered list of metric suffixes.
This list is used to filter and sort metrics in preparation for creating a graph.
Get a list of datapoints from sorted metrics.
| Parameters: | |
|---|---|
| Return type: |
Get graph data for check_bundle.
| Parameters: | |
|---|---|
| Return type: |
title defaults to using check_bundle["target"].
Get a sorted list of metrics from metrics.
| Parameters: | metrics (list) – The metrics to sort. |
|---|
The metrics are sorted by explicit suffix, i.e., MEMORY_METRIC_SUFFIXES.
Create graph data from a collectd check bundle containing interface metrics.
Transmitted metrics will be on the top of the graph and received metrics will be on the bottom.
The data formula to apply to received interface metrics.
The data formula to apply to transmitted interface metrics.
Get a list of datapoints for check_bundle and interface_name.
| Parameters: | |
|---|---|
| Return type: |
octets and errors will be returned. octets datapoints have data formulas added to them which makes them render as bits per second. Transmitted octets will be on the top and received octets will be on the bottom of the graph due to the data formulas.
Get graph data for check_bundle.
| Parameters: | |
|---|---|
| Return type: |
title defaults to using check_bundle["target"]. interface_name and bit/s will be appended to title.
Get metrics for interface interface_name and kind.
| Parameters: | |
|---|---|
| Return type: |
Create graph data from a check bundle.
Get graph data for check_bundle and datapoints.
| Parameters: | |
|---|---|
| Return type: |
Merge common graph data with custom_data. Add the telemetry tag based on the type attribute of check_bundle.
Manipulate check metrics.
Get a list of datapoints for check_id from metrics.
| Parameters: | |
|---|---|
| Return type: |
Datapoints determine how metrics are rendered on a graph. This function merges values from metrics with a few default values of required datapoint attributes. Datapoint attributes can be overridden with the custom parameter. The custom dict is used to update() each datapoint as it is created.
Get a list of metrics from check_bundle.
| Parameters: | |
|---|---|
| Return type: |
Get a list of metrics sorted by suffix from the list of metrics.
| Parameters: | |
|---|---|
| Return type: |
Sort the metrics list by metric names ending with values in the suffixes list. When creating graphs with stacked metrics the order in which metrics are stacked affects the manner in which they are displayed, e.g., perhaps “free” memory makes the most sense when it is at the top of a memory graph.
If there are not enough metrics to sort for suffixes an empty list is returned.
Get a copy of metrics with each status attribute value set to status.
| Parameters: | |
|---|---|
| Return type: |
metrics is not modified by this function.
Manipulate tags on resources that support them.
Circonus API resources for which tags can be modified.
Get a string representing tag.
| Parameters: | |
|---|---|
| Return type: |
Circonus requires categorized tags to be a string of the form, “category:tag”. Uncategorized tags are simply, “tag”.
Get the list of tags for resource with tags added to it.
| Parameters: | |
|---|---|
| Return type: | list or None |
If tags changes the existing tags on the resource by adding new tags then that new list of tags is returned.
If tags does not change the existing tags on the resource then None is returned.
All other failure states resulting from trying to add the list of tags to resource will return None.
Get the list of tags for resource with tags removed from it.
| Parameters: | |
|---|---|
| Return type: | list or None |
If tags changes the existing tags on the resource by removing new tags then that new list of tags is returned.
If tags does not change the existing tags on the resource then None is returned.
All other failure states resulting from trying to remove the list of tags to resource will return None.
Get a telemetry tag string for check_bundle.
| Parameters: | check_bundle (dict) – The check bundle to get a telemetry tag from. |
|---|---|
| Return type: | str |
If check_bundle has a type attribute, a tag of the form “telemetry:type” will be returned. This makes filtering check bundles by the source of telemetry data easier in the Circonus UI.
Is the resource represented by the given cid taggable?
| Parameters: | cid (str) – The cid of a resource that may support tags. |
|---|---|
| Return type: | bool |
Only resources which support tagging via the Circonus API are considered taggable. Resources which have a _tags attribute are not considered taggable since the _tags list cannot be updated via the API – it is read-only.
Utility functions that other modules depend upon.
Create a generator which returns colors for each item in items.
| Parameters: | items (list) – The list to generate colors for. |
|---|---|
| Return type: | generator(colour.Color) |
Convert date and time to seconds since the epoch.
| Parameters: | dt (datetime.datetime) – The date and time to convert. |
|---|---|
| Return type: | int |
dt is expected to have been created for the UTC date and time, e.g., with datetime.datetime.utcnow(). It is converted to seconds since the epoch with calendar.timegm() to respect UTC.