snap_plugin.v1 package

Module contents

This is a module for writing python plugins for the Snap telemetry framework.

This module provides provides everything you need to write a Collector, Processor or Publisher plugin for Snap. For more details checkoout the plugin authoring details at https://intelsdi-x.github.io/snap-plugin-lib-py/.

class snap_plugin.v1.Collector(name, version, **kwargs)

Bases: snap_plugin.v1.plugin.Plugin

Abstract base class for ‘collector’ plugins.

This class makes the creation of a snap ‘collector’ plugin as easy as possible. For instance, when a class inherits from py:class:snap_plugin.v1.collector.Collector plugins can be created by providing implementations for:

collect(metrics)

Collect requested metrics.

This method is abstract so the implementation must be provided by the plugin which extends snap_plugin.v1.Collector.

This method is called by the Snap deamon during the collection phase of the execution of a Snap workflow.

Parameters:metrics (list of snap_plugin.v1.Metric) – List of metrics to be collected.
Returns:List of collected metrics.
Return type:list of snap_plugin.v1.Metric
update_catalog(config)

Returns the metrics which the plugin provides.

This method is called by the Snap daemon when the plugin is loaded and returns a list of snap_plugin.v1.metric.Metric that will populate the snap metric catalog. The method is abstract so the implementation must be provided by the plugin which extends snap_plugin.v1.Collector.

Note: Requiring config to successfully return metric types should be avoided. Only in rare circumstances should a plugin require configuration data for it to load.

Parameters:config (snap_plugin.v1.ConfigMap) – Provides configuration data.
Returns:List of collectable metrics.
Return type:list of snap_plugin.v1.Metric
class snap_plugin.v1.Processor(name, version, **kwargs)

Bases: snap_plugin.v1.plugin.Plugin

Abstract base class for ‘processor’ plugins.

This class makes the creation of snap ‘processor’ plugins as easy as possible. For instance, when a class inherits from snap_plugin.v1.processor.Process plugins can be created by providing implementation for:

process(metrics, config)

Process metrics.

This method is abstract so the implementation must be provided by the plugin which extends snap_plugin.v1.Processor.

This method is called by the Snap deamon during the process phase of the execution of a Snap workflow. Examples of processing metrics include applying filtering, max, min, average functions as well as adding additional context to the metrics to name just a few.

Parameters:(obj (metrics) – list of snap_plugin.v1.Metric): List of metrics to be processed.
Returns:List of processed metrics.
Return type:list of snap_plugin.v1.Metric
class snap_plugin.v1.Publisher(name, version, **kwargs)

Bases: snap_plugin.v1.plugin.Plugin

Abstract base class for ‘publisher’ plugins.

This class makes the creation of snap ‘publisher’ plugins as easy as possible. For instance, when a class inherits from snap_plugin.v1.publisher.Publisher plugins can be created by providing implementation for:

publish(metrics, config)

Publishes metrics.

This method is abstract so the implementation must be provided by the plugin which extends snap_plugin.v1.Publisher.

This method is called by the Snap deamon during the publish phase of a Snap workflow.

Parameters:
Returns:

None
class snap_plugin.v1.Metric(namespace=[], version=None, tags={}, config={}, timestamp=1489110772.705474, unit='', description='', **kwargs)

Bases: object

The metric object is the core entity of snap representing metrics.

:param namespace (list of: NamespaceElement):
namespace elements
Parameters:
  • version (int) – metric version
  • tags (dict) – metric tags (key/value pairs)
  • config (ConfigMap) – config for metric (key/value pairs)
  • timestamp (float) – metric timestamp (see time.time())
  • unit (str) – metric unit
  • description (str) – metric description

Example

metric = Metric(namespace=(“acme”, “sk8”, “matix”, “rotations”),
description=”Rotation count”)
config

Metric config

Returns:ConfigMap
data

Metric data

:param value (bool or int or long or float: or basestring or bytes)

Returns:value
Raises:TypeError
description

Metric description

Parameters:value (str) –
Returns:str
namespace

Metric namespace elements.

Returns:
list of
NamespaceElement)
pb
tags

Metric tags.

Parameters:value (dict of strings) – {“tag-key”: “tag-value”}
Returns:Example: [(“tag-key”, “tag-value”)]
Return type:list of tuple
timestamp

Time in seconds since Epoch.

Parameters:value (float) – time in seconds since Epoch (see time.time())
Returns:time in seconds since Epoch (see time.time())
Return type:float
unit

Metric unit

Parameters:value (str) –
Returns:str
version

Metric version.

Parameters:value (int) – version
Returns:int
class snap_plugin.v1.Namespace(pb, *elements)

Bases: object

Namespace of a metric.

:param elements (list of: NamespaceElement
or list of strings): namespace elements
add(namespace_element)
add_dynamic_element(name, description)

Adds a dynamic namespace element to the end of the Namespace.

A dynamic namespace element is defined by an element that contains a non-static data relative to the metric being collected. For instance, when collecting metrics for a given virtual machine the namespace element that contains the virtual-machine-id would be dynamic. This is modeled by the a NamespaceElement when its name attribute contains the value ‘virtual-machine-id’. In this example the value attribute would be set to the ID of the virtual machine when the metric is collected.

Parameters:value (snap_plugin.v1.namespace_element.NamespaceElement) – namespace element
Returns:snap_plugin.v1.namespace.Namespace
add_static_element(value)

Adds a static namespace element to the end of the Namespace.

A static namespace element is defined by the value attribute being set and where the name attribute is not used (set to None). This is the case when the namespace does not change based on what is being collected.

Parameters:value (snap_plugin.v1.namespace_element.NamespaceElement) – namespace element
Returns:snap_plugin.v1.namespace.Namespace
pop(key=-1)

Removes and retuns the namespace element at a given index.

If the kwarg ‘key’ is provided the item at the given index is removed and returned. If the kwarg ‘key’’ is not provided the last Namespace element is removed and returned.

Parameters:**kwargs (optional) – key=-1
class snap_plugin.v1.NamespaceElement(name='', description='', value='', **kwargs)

Bases: object

Namespace element of a metric.

A namespace element is static when the value attribute is set and where the name attribute is not set. This is the case when the namespace does not change based on what is being collected.

A dynamic namespace element is defined by an element that contains non-static data relative to the metric being collected. For instance, when collecting metrics for a given virtual machine the namespace element that contains the virtual-machine-id would be dynamic. This is modeled by the NamespaceElement when its name attribute contains the value ‘virtual-machine-id’. In this example the value attribute would be set to the ID of the virtual machine when the metric is collected and ‘*’ when the metric catalog is updated.

Parameters:
  • value (str) – The value of an element.
  • name (str) – The name of an element.
  • description (str) – A short description of the element.
description
classmethod dynamic_namespace_element(name, description)

Returns a dynamic namespace_element.

A dynamic namespace element is one whose value attribute is set while the name attribute is not.

Parameters:
  • name (str) – Name of the namespace element
  • description (str) – Decription of the namespace element
Returns:

NamespaceElement
Return type:

NamespaceElement
name
classmethod static_namespace_element(value)

Returns a static namespace_element.

A static namespace element is one whose value attribute is set and the name attribute is not.

Parameters:value (str) – Value of the namespace element
Returns:NamespaceElement
Return type:NamespaceElement
value
class snap_plugin.v1.ConfigMap(*args, **kwargs)

Bases: collections.abc.MutableMapping

ConfigMap provides a map of config key value pairs.

Parameters:
  • *args – variable length argument list. A valid argument is a two item tuple/list. The first item is the key and the second is the value.
  • **kwargs – Arbitrary keyword arguments representing the config.

Example:

cfg0 = snap.ConfigMap(user="john", port=911)
cfg1 = snap.ConfigMap(("user","john"),("port", 911))
Also see:
clear()

Removes all entries from the config map

has_key(key)

Does the config map contain the key?

Returns:True if key exists, False otherwise.
Return type:bool
items()

Returns a list of (key, value) pairs as 2-tuples.

iteritems()

Returns an iterator over the items of ConfigMap.

iterkeys()

Returns an iterator over the keys of ConfigMap.

itervalues()

Returns an iterator over the values of ConfigMap.

keys()

Returns a list of ConfigMap keys.

pb
pop(key, default=None)

Remove specified key and return the corresponding value. If key is not found, default is returned if given, otherwise KeyError is raised.

popitem()

Remove and return some (key, value) pair as a 2-tuple

update(*args, **kwargs)

Update ConfigMap from mapping/iterable.

If the key exists the entry is updated else it is added.

Parameters:
  • *args – variable length argument list. A valid argument is a two item tuple/list. The first item is the key and the second is the value.
  • **kwargs – Arbitrary keyword arguments representing the config.
values()

Returns a list of ConfigMap values.

class snap_plugin.v1.StringRule(default='', required=False, **kwargs)

Bases: object

A configuration item with a string value type.

Parameters:
  • default (str) – The default value
  • required (bool) – Is the config item required
default

The default value

required

Is the config item required

class snap_plugin.v1.IntegerRule(default=None, maximum=None, minimum=None, required=False, **kwargs)

Bases: object

A configuration item with a integer value type.

Parameters:
  • default (int) – The default value
  • maximum (int) – The maximum allowed value
  • minimum (int) – The minimum allowed value
  • required (bool) – Is the config item required
default

The default value

maximum

The maximum allowed value

minimum

The minimum allowed value

required

Is the config item required

class snap_plugin.v1.BoolRule(default=False, required=False, **kwargs)

Bases: object

A configuration item with a integer value type.

Parameters:
  • default (bool) – The default value
  • required (bool) – Is the config item required?
default

The default value

required

Is the config item required

class snap_plugin.v1.FloatRule(default=0.0, required=False, **kwargs)

Bases: object

A configuration item with a float value type.

Parameters:
  • default (float) – The default value
  • maximum (float) – The maximum allowed value
  • minimum (float) – The minimum allowed value
  • required (bool) – Is the config item required
default

The default value

maximum

The maximum allowed value

minimum

The minimum allowed value

required

Is the config item required

class snap_plugin.v1.ConfigPolicy(*args)

Bases: object

ConfigPolicy describes the configuration items for a plugin.

A plugin exposes its configuration to the Snap framework through the object ConfigPolicy. The policy describes the configuration items value type (string, float, integer and bool), it’s default value (if any) as well as its contraints (min, max, etc).

Parameters:*args – A variable length list of tuples/lists where the first item of the list/tuple is a tuple/list representing the namespace. The second item is a tuple/list where the first item is the config’s key and the second is the specific configuration rule that should be applied.

Example:

snap.ConfigPolicy(
    [
        ("random"),
        [
            (
                "int_max",
                snap.IntegerRule(default=100, minimum=1, maximum=10000)
            ),
            (
                "int_min",
                snap.IntegerRule(default=0, minimum=0)
            )
        ]
    ]
)
Also see: