ceres

class ceres.CeresNode(tree, nodePath, fsPath)

A CeresNode represents a single time-series metric of a given timeStep (its seconds-per-point resolution) and containing arbitrary key-value metadata.

A CeresNode is associated with its most precise timeStep. This timeStep is the finest resolution that can be used for writing, though a CeresNode can contain and read data with other, less-precise timeStep values in its underlying CeresSlice data.

param tree:The CeresTree this node is associated with param nodePath:The name of the metric this node represents param fsPath:The filesystem path of this metric

Note

This class generally should be instantiated through use of CeresTree. See CeresTree.createNode() and CeresTree.getNode()

See also

setDefaultSliceCachingBehavior() to adjust caching behavior

aggregationMethod

clearSliceCache()

Clear slice cache, forcing a refresh from disk at the next access

compact(datapoints)

Compacts datapoints into a list of contiguous, sorted lists of points with duplicate timestamps and null values removed

param datapoints:  List of datapoint tuples [(timestamp, value), ...] returns:A list of lists of contiguous sorted datapoint tuples [[(timestamp, value), ...], ...]

classmethod create(tree, nodePath, **properties)

Create a new CeresNode on disk with the specified properties.

param tree:The CeresTree this node is associated with param nodePath:The name of the metric this node represents param **properties:  A set of key-value properties to be associated with this node

A CeresNode always has the timeStep property which is an integer value representing the precision of the node in seconds-per-datapoint. E.g. a value of 60 represents one datapoint per minute. If no timeStep is specified at creation, the value of ceres.DEFAULT_TIMESTEP is used

returns:CeresNode

classmethod fromFilesystemPath(fsPath)

Instantiate a CeresNode from the on-disk path of an existing node

Params fsPath:The filesystem path of an existing node Returns:CeresNode

fsPath

hasDataForInterval(fromTime, untilTime)

Test whether this node has any data in the given time interval. All slices are inspected which will trigger a read of slice information from disk if slice cache behavior is set to latest or none (See slices())

param fromTime:Beginning of interval in unix epoch seconds param untilTime:  End of interval in unix epoch seconds

:returns True or False

static isNodeDir(path)

Tests whether the given path is a CeresNode

Parameters:path – Path to test

:returns True or False

metadataFile

nodePath

read(fromTime, untilTime)

Read data from underlying slices and return as a single time-series

Parameters:

• fromTime – Beginning of interval in unix epoch seconds
• untilTime – End of interval in unix epoch seconds

Returns:

TimeSeriesData

readMetadata()

Update node metadata from disk

Raises:CorruptNode

readSlices()

Read slice information from disk

Returns:[(startTime, timeStep), ...]

setSliceCachingBehavior(behavior)

Set slice caching behavior.

Parameters:behavior – See slices() for valid behavior values

sliceCache

sliceCachingBehavior

slice_info

A property providing a list of current information about each slice

Returns:[(startTime, endTime, timeStep), ...]

slices

A property providing access to information about this node’s underlying slices. Because this information is accessed in every read and write, a caching mechanism is provided. Cache behavior is set using setSliceCachingBehavior() and defaults to the value set in DEFAULT_SLICE_CACHING_BEHAVIOR

The following behaviors are available:

• none (default) - Slice information is read from the filesystem at every access

• latest - The latest slice is served from cache, all others from disk. Reads and writes of recent data are most likely to be in the latest slice

• all - All slices are cached. The cache is only refreshed on new slice creation or deletion

  returns:[(startTime, timeStep), ...]

timeStep

tree

write(datapoints)

Writes datapoints to underlying slices. Datapoints that round to the same timestamp for the node’s timeStep will be treated as duplicates and dropped.

param datapoints:  List of datapoint tuples [(timestamp, value), ...]

writeMetadata(metadata)

Writes new metadata to disk

Parameters:metadata – a JSON-serializable dict of node metadata

class ceres.CeresSlice(node, startTime, timeStep)

classmethod create(node, startTime, timeStep)

deleteBefore(t)

endTime

fsPath

isEmpty

mtime

node

read(fromTime, untilTime)

startTime

timeStep

write(sequence)

class ceres.CeresTree(root)

Represents a tree of Ceres metrics contained within a single path on disk This is the primary Ceres API.

Parameters:root – The directory root of the Ceres tree

Note

Use createTree() to initialize and instantiate a new CeresTree

See also

setDefaultNodeCachingBehavior() to adjust caching behavior

createNode(nodePath, **properties)

Creates a new metric given a new metric name and optional per-node metadata :param nodePath: The new metric name. :param **properties: Arbitrary key-value properties to store as metric metadata.

Returns:CeresNode

classmethod createTree(root, **props)

Create and returns a new Ceres tree with the given properties

Parameters:

• root – The root directory of the new Ceres tree
• **props – Arbitrary key-value properties to store as tree metadata

Returns:

CeresTree

fetch(nodePath, fromTime, untilTime)

Fetch data within a given interval from the given metric

Parameters:

• nodePath – The metric name to fetch from
• fromTime – Requested interval start time in unix-epoch.
• untilTime – Requested interval end time in unix-epoch.

Returns:

TimeSeriesData

Raises:

NodeNotFound, InvalidRequest

find(nodePattern, fromTime=None, untilTime=None)

Find nodes which match a wildcard pattern, optionally filtering on a time range

param nodePattern:  A glob-style metric wildcard param fromTime:Optional interval start time in unix-epoch. param untilTime:  Optional interval end time in unix-epoch. returns:An iterator yielding CeresNode objects

getFilesystemPath(nodePath)

Get the on-disk path of a Ceres node given a metric name

Parameters:nodePath – A metric name e.g. carbon.agents.graphite-a.cpuUsage Returns:The Ceres node path on disk

getNode(nodePath)

Returns a Ceres node given a metric name. Because nodes are looked up in every read and write, a caching mechanism is provided. Cache behavior is set using setNodeCachingBehavior() and defaults to the value set in DEFAULT_NODE_CACHING_BEHAVIOR

The following behaviors are available:

• none - Node is read from the filesystem at every access.
• all (default) - All nodes are cached.
  param nodePath:A metric name returns:CeresNode or None

getNodePath(fsPath)

Get the metric name of a Ceres node given the on-disk path

Parameters:fsPath – The filesystem path of a Ceres node Returns:A metric name Raises:ValueError – When fsPath is not a path within the CeresTree

hasNode(nodePath)

Returns whether the Ceres tree contains the given metric

Parameters:nodePath – A metric name e.g. carbon.agents.graphite-a.cpuUsage Returns:True or False

setNodeCachingBehavior(behavior)

Set node caching behavior.

Parameters:behavior – See getNode() for valid behavior values

store(nodePath, datapoints)

Store a list of datapoints associated with a metric :param nodePath: The metric name to write to e.g. carbon.agents.graphite-a.cpuUsage :param datapoints: A list of datapoint tuples: [(timestamp, value), ...]

walk(**kwargs)

Iterate through the nodes contained in this CeresTree

Parameters:**kwargs – Options to pass to os.walk() Returns:An iterator yielding CeresNode objects

exception ceres.CorruptNode(node, problem)

exception ceres.InvalidAggregationMethod

exception ceres.InvalidRequest

exception ceres.NoData

exception ceres.NodeDeleted

exception ceres.NodeNotFound

exception ceres.SliceDeleted

exception ceres.SliceGapTooLarge

For internal use only

class ceres.TimeSeriesData(startTime, endTime, timeStep, values)

endTime

merge(other)

startTime

timeStep

timestamps

values

ceres.aggregate(aggregationMethod, values)

ceres.aggregateSeries(method, oldTimeStep, newTimeStep, values)

ceres.getTree(path)

ceres.setDefaultNodeCachingBehavior(behavior)

ceres.setDefaultSliceCachingBehavior(behavior)