circonus Documentation

circonus Documentation
Release 0.0.22
Monetate Inc.
February 14, 2015
Contents
1
Features
2
User Guide
2.1 Installation
2.2 Core . . .
2.3 Annotation
2.4 Tag . . . .
3
.
.
.
.
5
5
5
8
9
3
API Documentation
3.1 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
11
4
Changelog
4.1 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
23
.
.
.
.
Python Module Index
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
27
i
ii
circonus Documentation, Release 0.0.22
Release v0.0.22. (Installation)
circonus is a Python module for interacting with the Circonus REST API.
from circonus import CirconusClient
CIRCONUS_API_APP_NAME = "my-app"
CIRCONUS_APP_TOKEN = "generated-by-circonus-ui"
circonus = CirconusClient(CIRCONUS_API_APP_NAME, CIRCONUS_APP_TOKEN)
A configured CirconusClient will authenticate via custom Circonus HTTP request headers for all subsequent
requests:
response = circonus.get("user/current")
print 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’}
Contents
1
circonus Documentation, Release 0.0.22
2
Contents
CHAPTER 1
Features
circonus is built on the excellent requests library. It extends or improves the standard Circonus REST API by
providing several conveniences and features:
• Application name and token handling
• Resource tagging
• An annotation decorator and context manager
• Error logging
• Opinionated collectd system metric graphing
3
circonus Documentation, Release 0.0.22
4
Chapter 1. Features
CHAPTER 2
User Guide
2.1 Installation
circonus is available on the Python Package Index and can be installed with pip:
pip install circonus
2.2 Core
Setup the CirconusClient:
from circonus import CirconusClient
CIRCONUS_API_APP_NAME = "my-circonus-app"
CIRCONUS_APP_TOKEN = "generated-by-circonus-ui"
circonus = CirconusClient(CIRCONUS_API_APP_NAME, CIRCONUS_APP_TOKEN)
Authentication is performed via custom Circonus HTTP request headers. The headers are set for all subsequent
requests made via the circonus object:
print circonus.api_headers
{’Accept’: ’application/json’,
’X-Circonus-App-Name’: ’my-circonus-app’,
’X-Circonus-Auth-Token’: ’generated-in-circonus-ui’}
2.2.1 Get
The current user:
response = circonus.get("user/current")
print 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’}
5
circonus Documentation, Release 0.0.22
All users:
response = circonus.get("user")
print response.json()
[{u’_cid’: u’/user/1234’,
u’contact_info’: {u’sms’: u’’, u’xmpp’: u’’},
u’email’: u’user0@example.com’,
u’firstname’: u’Ewe’,
u’lastname’: u’Sure’},
{u’_cid’: u’/user/1235’,
u’contact_info’: {u’sms’: u’’, u’xmpp’: u’’},
u’email’: u’user1@example.com’,
u’firstname’: u’Ewe’,
u’lastname’: u’Sure Jr.’},
...]
A specific graph:
response = circonus.get("graph/6c53484e-b0ad-4652-8b4b-6645fae0db7b")
print response.json()
{u’_cid’: u’/graph/6c53484e-b0ad-4652-8b4b-6645fae0db7b’,
u’access_keys’: [],
u’composites’: [],
u’datapoints’: [...],
u’description’: u’’,
u’guides’: [],
u’line_style’: u’stepped’,
u’logarithmic_left_y’: None,
u’logarithmic_right_y’: None,
u’max_left_y’: None,
u’max_right_y’: None,
u’metric_clusters’: [],
u’min_left_y’: u’0’,
u’min_right_y’: u’0’,
u’notes’: None,
u’style’: u’area’,
u’tags’: [],
u’title’: u’cpu usage’}
Graphs filtered by title:
response = circonus.get("graph", {"f_title_wildcard": "*cpu*"})
print response.json()
[{u’_cid’: u’/graph/6c53484e-b0ad-4652-8b4b-6645fae0db7b’,
u’access_keys’: [],
u’composites’: [],
u’datapoints’: [...],
u’description’: u’’,
u’guides’: [],
u’line_style’: u’stepped’,
u’logarithmic_left_y’: None,
u’logarithmic_right_y’: None,
u’max_left_y’: None,
u’max_right_y’: None,
u’metric_clusters’: [],
u’min_left_y’: u’0’,
6
Chapter 2. User Guide
circonus Documentation, Release 0.0.22
u’min_right_y’: u’0’,
u’notes’: None,
u’style’: u’area’,
u’tags’: [],
u’title’: u’cpu usage’}]
2.2.2 Create
A check bundle:
data = {
"brokers": ["/broker/123"],
"metrics": [{"type": "text", "name": "dummy"}],
"target": "10.0.0.1",
"type": "collectd"
}
response = circonus.create("check_bundle", data)
print response.json()
{u’_checks’: [u’/check/123456’],
u’_cid’: u’/check_bundle/12345’,
u’_created’: 1418331830,
u’_last_modified’: 1418331830,
u’_last_modified_by’: u’/user/1234’,
u’brokers’: [u’/broker/123’],
u’config’: {u’asynch_metrics’: u’false’},
u’display_name’: u’10.0.0.1 - collectd’,
u’metrics’: [{u’name’: u’dummy’, u’status’: u’active’, u’type’: u’text’}],
u’notes’: None,
u’period’: 60,
u’status’: u’active’,
u’tags’: [u’telemetry:collectd’],
u’target’: u’10.0.0.1’,
u’timeout’: 10,
u’type’: u’collectd’}
2.2.3 Update
A check bundle to remove all of the tags associated with it:
response = circonus.update("/check_bundle/12345", {"tags": []})
print response.json()
{u’_checks’: [u’/check/123456’],
u’_cid’: u’/check_bundle/12345’,
u’_created’: 1418331830,
u’_last_modified’: 1418331830,
u’_last_modified_by’: u’/user/1234’,
u’brokers’: [u’/broker/123’],
u’config’: {u’asynch_metrics’: u’false’},
u’display_name’: u’10.0.0.1 - collectd’,
u’metrics’: [{u’name’: u’dummy’, u’status’: u’active’, u’type’: u’text’}],
u’notes’: None,
u’period’: 60,
u’status’: u’active’,
2.2. Core
7
circonus Documentation, Release 0.0.22
u’tags’: [],
u’target’: u’10.0.0.1’,
u’timeout’: 10,
u’type’: u’collectd’}
2.2.4 Delete
A tag:
response = circonus.delete("tag/category:tag")
print response.status_code
204
A HTTP status code 204 No Content indicates that the resource was deleted successfully.
2.3 Annotation
A Circonus annotation can be created in several ways.
2.3.1 Explicit
annotation = circonus.create_annotation("title", "category")
Note:
The create_annotation() method returns an Annotation instance rather than a
requests.Response instance. The requests.Response object is available at the response attribute on
the returned object.
2.3.2 Decorator
@circonus.annotation("title", "category")
def nap_time():
sleep(10)
This will create an annotation with the given parameters and start and stop times that are automatically set to the
UTC values of the object.__enter__() and object.__exit__() for the decorated function.
2.3.3 Context Manager
with circonus.annotation("title", "category"):
sleep(10)
This will create an annotation with the given parameters and start and stop times that are automatically set to the
UTC values of the object.__enter__() and object.__exit__() for the block.
8
Chapter 2. User Guide
circonus Documentation, Release 0.0.22
2.4 Tag
The CirconusClient can be setup with a list of common tags. These tags will be applied to all resources that are
created via the create() method or updated via the update() method.
COMMON_TAGS = ["category:tag", "global"]
circonus = CirconusClient(CIRCONUS_API_APP_NAME, CIRCONUS_APP_TOKEN, COMMON_TAGS)
Now when a resource is created:
response = circonus.create("check_bundle", {
"brokers": ["/broker/123"],
"metrics": [{"type": "text", "name":"dummy"}],
"target": "10.0.0.1",
"type": "collectd"
})
It will automatically be tagged with those common tags:
print response.json()["tags"]
["category:tag", "global"]
A few examples for which common tags can be helpful for automatically tagging resources are:
• The environment, e.g., development, staging, production
• The application layer which created the CirconusClient, e.g., application, database, web
• Platform information, e.g., data center, image name, subnet
• Provisioning information from a configuration management tool
2.4. Tag
9
circonus Documentation, Release 0.0.22
10
Chapter 2. User Guide
CHAPTER 3
API Documentation
3.1 API
The goal of the circonus package is to combine the ease of use of the requests.Response API with the robust
Circonus REST API.
3.1.1 Client Interface
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.
class circonus.CirconusClient(api_app_name, api_token, common_tags=None)
Construct a CirconusClient.
Parameters
• api_app_name (str) – The Circonus API application name.
• api_token (str) – The Circonus API token.
• common_tags (list) – (optional) The str tags to apply to all resources.
Return type CirconusClient
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(resource_type_or_cid, params=None)
Get the resource at resource type or cid via requests.get().
Parameters
11
circonus Documentation, Release 0.0.22
• resource_type_or_cid (str) – The resource type or cid representing a specific resource.
• params (dict) – (optional) The parameters to pass to requests.get().
Return type requests.Response
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(resource_type, data)
Create the resource type with data via requests.post().
Parameters
• resource_type (str) – The resource type to create.
• data (dict) – The data used to create the resource.
Return type requests.Response
update(cid, data)
Update the resource at cid with data via requests.put().
Parameters
• cid (str) – The resource to update.
• data (dict) – The data used to update the resource.
Return type requests.Response
delete(cid, params=None)
Delete the resource at cid via requests.delete().
Parameters
• cid (str) – The resource to delete.
• params (dict) – (optional) The parameters to pass to requests.delete().
Return type requests.Response
annotation(title, category, description=’‘, rel_metrics=None)
Context manager and decorator for creating Annotation instances.
Parameters
• title (str) – The title.
• category (str) – The category.
• description (str) – (optional) The description.
• rel_metrics (list) – (optional) The str names of metrics related to this annotation.
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_annotation(title, category, start=None, stop=None, description=’‘, rel_metrics=None)
Create an Annotation instance immediately.
Parameters
• title (str) – The title.
• category (str) – The category.
12
Chapter 3. API Documentation
circonus Documentation, Release 0.0.22
• start (datetime.datetime) – (optional) The start time.
• stop (datetime.datetime) – (optional) The stop time.
• description (str) – (optional) The description.
• rel_metrics (list) – (optional) The str names of metrics related to this annotation.
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_collectd_cpu_graph(check_bundle, title=None)
Create a CPU graph from the collectd check_bundle.
Parameters
• check_bundle (dict) – The check bundle to create a graph for.
• title (str) – (optional) The title to use for the graph.
Return type requests.Response or None
None is returned if no data to create the graph could be found in check_bundle.
create_collectd_df_graph(check_bundle, mount_dir, title=None)
Create a disk free graph from the collectd check_bundle for mount_dir on target.
Parameters
• check_bundle (dict) – The check bundle to create a graph for.
• mount_dir (str) – The mount directory to create the graph for.
• title (str) – (optional) The title to use for the graph.
Return type requests.Response or None
None is returned if no data to create the graph could be found in check_bundle.
create_collectd_graphs(check_bundle,
interface_names=None,
tles=None)
Create several graphs from the collectd check_bundle.
mount_dirs=None,
ti-
Parameters
• check_bundle (dict) – The check bundle to create graphs for.
• interface_name (list) – (optional) The interface names to create interface graphs for,
e.g., ["eth0"].
• mount_dirs (list) – (optional) The mount directories to create df graphs for, e.g.,
["/root", "/mnt"].
• titles (dict) – (optional) The titles to use for each graph.
Return type (bool, list)
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.
3.1. API
13
circonus Documentation, Release 0.0.22
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_collectd_interface_graph(check_bundle, interface_name=’eth0’, title=None)
Create an interface graph from the collectd check_bundle.
Parameters
• check_bundle (dict) – The check bundle to create a graph for.
• interface_name (str) – (optional) The interface name, e.g., “eth0”.
• title (str) – (optional) The title to use for the graph.
Return type requests.Response or None
None is returned if no data to create the graph could be found in check_bundle.
create_collectd_memory_graph(check_bundle, title=None)
Create a memory graph from the collectd check_bundle.
Parameters
• check_bundle (dict) – The check bundle to create a graph for.
• title (str) – (optional) The title to use for the graph.
Return type requests.Response or None
None is returned if no data to create the graph could be found in check_bundle.
update_with_tags(cid, new_tags)
Update the resource at cid to have new_tags added to it via update().
Parameters
• cid (str) – The resource to update.
• new_tags (list) – The str tags to add to the resource.
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.
Client Functions
Several functions exist that CirconusClient depends on and may be useful elsewhere:
circonus.client.get_api_url(resource_type_or_cid)
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
14
Chapter 3. API Documentation
circonus Documentation, Release 0.0.22
circonus.client.with_common_tags(f )
Decorator to ensure that common tags exist on resources.
Only resources which support tagging via the Circonus API will be affected.
circonus.client.log_http_error(f )
Decorator for logging any HTTPError raised by a request.
Raises requests.exceptions.HTTPError
3.1.2 Classes
class circonus.client.Annotation(client, title, category, description=’‘, rel_metrics=None)
Construct an Annotation.
Parameters
• client (CirconusClient) – The client to create the annotation with.
• title (str) – The title.
• category (str) – The category.
• description (str) – (optional) The description.
• rel_metrics (list) – (optional) The str names of metrics related to this 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()
Create an annotation from the current state.
3.1.3 Modules
circonus.collectd
Turn collectd check bundles into graphs and worksheets.
circonus.collectd.cpu
Create graph data from a collectd check bundle containing cpu metrics.
circonus.collectd.cpu.CPU_METRIC_RE = <_sre.SRE_Pattern object at 0x7f414578cbb0>
A compiled regular expression which matches collectd metrics.
circonus.collectd.cpu.CPU_METRIC_SUFFIXES = [’steal’, ‘interrupt’, ‘softirq’, ‘system’, ‘wait’, ‘user’, ‘nice’, ‘idle’]
Ordered list of metric suffixes.
This list is used to filter and sort metrics in preparation for creating a graph.
circonus.collectd.cpu.CPU_NUMBER_RE = <_sre.SRE_Pattern object at 0x7f414576a978>
A compiled regular expression which captures CPU number from the CPU metric.
circonus.collectd.cpu.get_cpu_datapoints(check_bundle, metrics)
Get a list of datapoints from sorted metrics.
Parameters
• check_bundle (dict) – The check bundle.
3.1. API
15
circonus Documentation, Release 0.0.22
• metrics (list) – Sorted CPU metrics.
Return type :py:class‘list‘
circonus.collectd.cpu.get_cpu_graph_data(check_bundle, title=None)
Get graph data for check_bundle.
Parameters
• check_bundle (dict) – The check bundle to create graph data with.
• title (str) – (optional) The title to use for the graph.
Return type dict
title defaults to using check_bundle["target"].
The returned data dict can be used to create() a graph.
circonus.collectd.cpu.get_cpu_metrics(metrics)
Get a sorted list of metrics from metrics.
Parameters metrics (list) – The metrics to sort.
The CPU metrics are sorted by:
1.Name, ascending
2.Explicit suffix, i.e., CPU_METRIC_SUFFIXES
circonus.collectd.cpu.get_stacked_cpu_metrics(metrics, hide_idle=True)
Get metrics with the stack attribute added.
Parameters
• metrics (list) – The metrics to stack.
• hide_idle (bool) – (optional) Hide CPU idle.
Return type list
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.
circonus.collectd.df
Create graph data from a collectd check bundle containing df metrics.
circonus.collectd.df.DF_METRIC_RE = <_sre.SRE_Pattern object at 0x7f41450e0b10>
A compiled regular expression which matches collectd metrics.
circonus.collectd.df.DF_METRIC_SUFFIXES = [’reserved’, ‘used’, ‘free’]
Ordered list of metric suffixes.
This list is used to filter and sort metrics in preparation for creating a graph.
circonus.collectd.df.get_df_datapoints(check_bundle, metrics)
Get a list of datapoints from sorted metrics.
Parameters
• check_bundle (dict) – The check bundle.
• metrics (list) – The sorted metrics to cerate datapoints with.
Return type list
16
Chapter 3. API Documentation
circonus Documentation, Release 0.0.22
circonus.collectd.df.get_df_graph_data(check_bundle, mount_dir, title=None)
Get graph data for check_bundle.
Parameters
• check_bundle (dict) – The check bundle to create graph data with.
• title (str) – (optional) The title to use for the graph.
• mount_dir (str) – The mount directory to create graph data for.
Return type dict
title defaults to using check_bundle["target"]. df and mount_dir will be appended to title.
The returned data dict can be used to create() a graph.
circonus.collectd.df.get_df_metrics(metrics, mount_dir)
Get disk free metrics from metrics for mount_dir.
Parameters
• metrics (list) – The metrics.
• mount_dir (str) – The mount directory to get metrics for.
Return type list
circonus.collectd.df.get_sorted_df_metrics(metrics)
Get sorted disk free metrics from metrics.
Parameters metrics (list) – The metrics to sort.
Return type list
circonus.collectd.df.is_mount_dir(metric_name, mount_dir)
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.
circonus.collectd.graph
Create graph data for several collectd graphs.
circonus.collectd.graph.get_collectd_graph_data(check_bundle,
interface_names,
mount_dirs, titles=None)
Get collectd graph data for check_bundle.
Parameters
• check_bundle (dict) – The check bundle to get graph data from.
• interface_names (list) – The interface names to get data for.
• mount_dirs (list) – The mount directories to get data for.
• titles (dict) – (optional) The titles to use for each graph.
3.1. API
17
circonus Documentation, Release 0.0.22
Return type list
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.
circonus.collectd.memory
Create graph data from a collectd check bundle.
circonus.collectd.memory.MEMORY_METRIC_RE = <_sre.SRE_Pattern object at 0x7f41450e0ce0>
A compiled regular expression which matches collectd metrics.
circonus.collectd.memory.MEMORY_METRIC_SUFFIXES = [’used’, ‘buffered’, ‘cached’, ‘free’]
Ordered list of metric suffixes.
This list is used to filter and sort metrics in preparation for creating a graph.
circonus.collectd.memory.get_memory_datapoints(check_bundle, metrics)
Get a list of datapoints from sorted metrics.
Parameters
• check_bundle (dict) – The check bundle.
• metrics (list) – The sorted metrics to cerate datapoints with.
Return type list
circonus.collectd.memory.get_memory_graph_data(check_bundle, title=None)
Get graph data for check_bundle.
Parameters
• check_bundle (dict) – The check bundle to create graph data with.
• title (str) – (optional) The title to use for the graph.
Return type dict
title defaults to using check_bundle["target"].
The returned data dict can be used to create() a graph.
circonus.collectd.memory.get_sorted_memory_metrics(metrics)
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.
circonus.collectd.interface
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.
circonus.collectd.interface.DATA_FORMULA_RECEIVER = ‘=-8*VAL’
The data formula to apply to received interface metrics.
18
Chapter 3. API Documentation
circonus Documentation, Release 0.0.22
circonus.collectd.interface.DATA_FORMULA_TRANSMITTER = ‘=8*VAL’
The data formula to apply to transmitted interface metrics.
circonus.collectd.interface.get_interface_datapoints(check_bundle,
face_name=’eth0’)
Get a list of datapoints for check_bundle and interface_name.
inter-
Parameters
• check_bundle (list) – The check bundle.
• interface_name (str) – (optional) The interface name, e.g., “eth0”.
Return type list
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.
circonus.collectd.interface.get_interface_graph_data(check_bundle,
face_name=’eth0’,
tle=None)
Get graph data for check_bundle.
interti-
Parameters
• check_bundle (dict) – The check bundle to create graph data with.
• title (str) – (optional) The title to use for the graph.
• interface_name (str) – (optional) The interface name, e.g., “eth0”.
Return type dict
title defaults to using check_bundle["target"]. interface_name and bit/s will be appended
to title.
The returned data dict can be used to create() a graph.
circonus.collectd.interface.get_interface_metrics(metrics,
interface_name=’eth0’,
kind=None)
Get metrics for interface interface_name and kind.
Parameters
• metrics (list) – The metrics.
• interface_name (str) – (optional) The interface name, e.g., “eth0”.
• kind (str) – (optional) The kind of interface metrics to get, e.g., “octets”.
Return type list
circonus.collectd.interface.is_receiver(metric)
Is interface metric a receiver?
Parameters metric (dict) – The metric.
Return type bool
circonus.collectd.interface.is_transmitter(metric)
Is interface metric a transmitter?
Parameters metric (dict) – The metric.
Return type bool
3.1. API
19
circonus Documentation, Release 0.0.22
circonus.graph
Create graph data from a check bundle.
circonus.graph.get_graph_data(check_bundle, datapoints, custom_data=None)
Get graph data for check_bundle and datapoints.
Parameters
• check_bundle (dict) – The check bundle to create graph data for.
• datapoints (list) – The datapoints to include in the graph data.
• custom_data (dict) – (optional) The custom data to include in the graph data.
Return type dict
Merge common graph data with custom_data. Add the telemetry tag based on the type attribute of
check_bundle.
circonus.metric
Manipulate check metrics.
circonus.metric.get_datapoints(check_id, metrics, custom=None)
Get a list of datapoints for check_id from metrics.
Parameters
• check_id (str) – The check id.
• metrics (list) – The metrics.
• custom (dict) – (optional) The custom datapoint attributes used to update each datapoint.
Return type list
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.
circonus.metric.get_metrics(check_bundle, metric_re)
Get a list of metrics from check_bundle.
Parameters
• check_bundle (dict) – A check bundle with metrics.
• metric_re (re) – Regular expression matching metrics to return.
Return type list
circonus.metric.get_metrics_sorted_by_suffix(metrics, suffixes)
Get a list of metrics sorted by suffix from the list of metrics.
Parameters
• metrics (list) – Metrics to sort.
• suffixes (list) – Sorted list of suffixes used to sort the return metrics list.
Return type list
20
Chapter 3. API Documentation
circonus Documentation, Release 0.0.22
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.
circonus.metric.get_metrics_with_status(metrics, status, metric_re=None)
Get a copy of metrics with each status attribute value set to status.
Parameters
• metrics (list) – The metrics to set statuses for.
• status (str) – The status to set on each metric.
• metric_re (re) – (optional) The compiled regular expression used to match metrics to update.
Return type list
metrics is not modified by this function.
circonus.tag
Manipulate tags on resources that support them.
circonus.tag.TAGGABLE_RESOURCES = [’check_bundle’, ‘contact_group’, ‘graph’, ‘maintenance’, ‘metric_cluster’, ‘temp
Circonus API resources for which tags can be modified.
circonus.tag.get_tag_string(tag, category=None)
Get a string representing tag.
Parameters
• tag (str) – The tag.
• category (str) – (optional) The category.
Return type str
Circonus requires categorized tags to be a string of the form, “category:tag”. Uncategorized tags are simply,
“tag”.
circonus.tag.get_tags_with(resource, tags)
Get the list of tags for resource with tags added to it.
Parameters
• resource (dict) – The resource with a tags key.
• tags (list) – The tags to add to resource.
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.
circonus.tag.get_tags_without(resource, tags)
Get the list of tags for resource with tags removed from it.
Parameters
• resource (dict) – The resource with a tags key.
3.1. API
21
circonus Documentation, Release 0.0.22
• tags (list) – The tags to remove from resource.
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.
circonus.tag.get_telemetry_tag(check_bundle)
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.
circonus.tag.is_taggable(cid)
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.
circonus.util
Utility functions that other modules depend upon.
circonus.util.colors(items)
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)
circonus.util.datetime_to_int(dt)
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,
datetime.datetime.utcnow().
It is converted to seconds since the
calendar.timegm() to respect UTC.
e.g.,
epoch
with
with
circonus.util.get_check_id_from_cid(cid)
Get a check id integer from cid.
Parameters cid (str) – The check id.
Return type int
circonus.util.get_resource_from_cid(cid)
Get the resource name from cid.
Parameters cid (str) – The check id.
Return type str
22
Chapter 3. API Documentation
CHAPTER 4
Changelog
4.1 Changelog
4.1.1 Release History
0.0.22 (2015-02-14)
Bug fixes
• Avoid selecting df metrics other than df_complex when creating disk free graphs.
0.0.21 (2015-01-29)
Improvements
• Change the collectd client interface to take an explicit check bundle to create graphs from rather than naïvely
using the first collectd check bundle found for target.
• Refactor the datetime_to_int method from Annotation to be a function in util.
0.0.20 (2015-01-28)
Bug fixes
• Remove errant df from custom graph title.
0.0.19 (2015-01-28)
Bug fixes
• Fix optional custom titles for all collectd graphs.
0.0.18 (2015-01-26)
Improvements
• Add optional custom titles for all collectd graphs.
23
circonus Documentation, Release 0.0.22
0.0.17 (2015-01-26)
Improvements
• Add function for updating the status of each metric in a list of metrics.
0.0.16 (2015-01-24)
Improvements
• Make the get_tag_string function public.
0.0.15 (2015-01-24)
Bug fixes
• Add MANIFEST.in to include required distribution files.
0.0.14 (2015-01-22)
Bug fixes
• Hard code version in setup to avoid setup dependency
0.0.13 (2015-01-22)
Bug fixes
• Require the colour package at setup time
0.0.12 (2015-01-22)
Improvements
• Add client method to create all supported collectd plugin graphs for a specific target at once.
• Update circonus.collectd.cpu API to act like the other plugin modules.
• Change exception handling to raise HTTPError in log decorator.
• Add API documentation
0.0.11 (2015-01-21)
Improvements
• Add collectd df graph
• Add API documentation
24
Chapter 4. Changelog
circonus Documentation, Release 0.0.22
0.0.10 (2015-01-20)
Improvements
• Rename circonus.collectd.network to circonus.collectd.interface to reflect what the
name of the collectd module is.
0.0.9 (2015-01-20)
Improvements
• Add collectd network graph
• Add API documentation
0.0.8 (2015-01-20)
Improvements
• Add collectd memory graph
• Add API documentation
Bug fixes
• Fix key error when looking for metrics in a check bundle that has none.
• Handle error state when sorting metrics. If there were less metrics than suffixes to sort by the returned list would
contain None values. Now an empty list is returned.
0.0.7 (2015-01-19)
Improvements
• Add initial support for collectd
• Add graph module
• Add metric module
• Add API documentation
0.0.6 (2015-01-16)
Improvements
• Add optional common tags parameter to CirconusClient class for a cleaner way to specify common tags on a
given instance of the client.
• Update all docstrings to reStructuredText format with parameter and return types.
• Add API documentation.
0.0.5 (2015-01-13)
Bug fixes
• Fix documentation link
4.1. Changelog
25
circonus Documentation, Release 0.0.22
0.0.4 (2015-01-13)
Improvements
• Documentation
0.0.3 (2015-01-13)
Bug fixes
• Make the with_common_tags decorator copy the COMMON_TAGS list rather than modify it.
0.0.2 (2015-01-13)
Improvements
• Annotation decorator, context manager & ad hoc methods
• HISTORY.rst
Bug fixes
• Properly unpack args in with_common_tags decorator
0.0.1 (2015-01-08)
• Wrap REST API with requests
• Custom HTTP request headers for app. name and token
• Resource tagging
• Error logging
26
Chapter 4. Changelog
Python Module Index
c
circonus, 11
circonus.collectd, 15
circonus.collectd.cpu, 15
circonus.collectd.df, 16
circonus.collectd.graph, 17
circonus.collectd.interface, 18
circonus.collectd.memory, 18
circonus.graph, 19
circonus.metric, 20
circonus.tag, 21
circonus.util, 22
27
circonus Documentation, Release 0.0.22
28
Python Module Index
Index
A
Annotation (class in circonus.client), 15
annotation() (circonus.CirconusClient method), 12
C
circonus (module), 11
circonus.collectd (module), 15
circonus.collectd.cpu (module), 15
circonus.collectd.df (module), 16
circonus.collectd.graph (module), 17
circonus.collectd.interface (module), 18
circonus.collectd.memory (module), 18
circonus.graph (module), 19
circonus.metric (module), 20
circonus.tag (module), 21
circonus.util (module), 22
CirconusClient (class in circonus), 11
colors() (in module circonus.util), 22
CPU_METRIC_RE (in module circonus.collectd.cpu), 15
CPU_METRIC_SUFFIXES
(in
module
circonus.collectd.cpu), 15
CPU_NUMBER_RE (in module circonus.collectd.cpu),
15
create() (circonus.CirconusClient method), 12
create() (circonus.client.Annotation method), 15
create_annotation() (circonus.CirconusClient method), 12
create_collectd_cpu_graph()
(circonus.CirconusClient
method), 13
create_collectd_df_graph()
(circonus.CirconusClient
method), 13
create_collectd_graphs()
(circonus.CirconusClient
method), 13
create_collectd_interface_graph()
(circonus.CirconusClient method), 14
create_collectd_memory_graph()
(circonus.CirconusClient method), 14
D
DATA_FORMULA_RECEIVER (in
conus.collectd.interface), 18
module
DATA_FORMULA_TRANSMITTER (in module circonus.collectd.interface), 18
datetime_to_int() (in module circonus.util), 22
delete() (circonus.CirconusClient method), 12
DF_METRIC_RE (in module circonus.collectd.df), 16
DF_METRIC_SUFFIXES
(in
module
circonus.collectd.df), 16
G
get() (circonus.CirconusClient method), 11
get_api_url() (in module circonus.client), 14
get_check_id_from_cid() (in module circonus.util), 22
get_collectd_graph_data()
(in
module
circonus.collectd.graph), 17
get_cpu_datapoints() (in module circonus.collectd.cpu),
15
get_cpu_graph_data() (in module circonus.collectd.cpu),
16
get_cpu_metrics() (in module circonus.collectd.cpu), 16
get_datapoints() (in module circonus.metric), 20
get_df_datapoints() (in module circonus.collectd.df), 16
get_df_graph_data() (in module circonus.collectd.df), 16
get_df_metrics() (in module circonus.collectd.df), 17
get_graph_data() (in module circonus.graph), 20
get_interface_datapoints()
(in
module
circonus.collectd.interface), 19
get_interface_graph_data()
(in
module
circonus.collectd.interface), 19
get_interface_metrics()
(in
module
circonus.collectd.interface), 19
get_memory_datapoints()
(in
module
circonus.collectd.memory), 18
get_memory_graph_data()
(in
module
circonus.collectd.memory), 18
get_metrics() (in module circonus.metric), 20
get_metrics_sorted_by_suffix()
(in
module
circonus.metric), 20
get_metrics_with_status() (in module circonus.metric),
21
cirget_resource_from_cid() (in module circonus.util), 22
29
circonus Documentation, Release 0.0.22
get_sorted_df_metrics() (in module circonus.collectd.df),
17
get_sorted_memory_metrics()
(in
module
circonus.collectd.memory), 18
get_stacked_cpu_metrics()
(in
module
circonus.collectd.cpu), 16
get_tag_string() (in module circonus.tag), 21
get_tags_with() (in module circonus.tag), 21
get_tags_without() (in module circonus.tag), 21
get_telemetry_tag() (in module circonus.tag), 22
I
is_mount_dir() (in module circonus.collectd.df), 17
is_receiver() (in module circonus.collectd.interface), 19
is_taggable() (in module circonus.tag), 22
is_transmitter() (in module circonus.collectd.interface),
19
L
log_http_error() (in module circonus.client), 15
M
MEMORY_METRIC_RE
(in
module
conus.collectd.memory), 18
MEMORY_METRIC_SUFFIXES (in module
conus.collectd.memory), 18
circir-
T
TAGGABLE_RESOURCES (in module circonus.tag), 21
U
update() (circonus.CirconusClient method), 12
update_with_tags() (circonus.CirconusClient method), 14
W
with_common_tags() (in module circonus.client), 14
30
Index