State and Topology
Getting Node State
This API call is for viewing the system state of the current node.
Data will be returned as a JSON document. The fields in this document are described below.
Description
URI
/state
Method
GET
Output
identity: The UUID that identifies this node.current: The current topology in which this node resides.next: The next topology for this node.base_rollup: The smallest period that is used for rolling up numeric data.rollups: An array containing a list of all data periods stored on this node.nnt: A container with information about NNT (Numeric) data storage.rollups: An array containing a list of all NNT (numeric) data periods stored on this node.rollup_<period>: Data for each configured rollup. There will be one of these entries per rollup period.fs: Information about file system storage for this rollup.id: The ID for this file system.totalMB: Megabytes of data used for this file system.freeMB: Megabytes of data available for this file system.
put.calls: The number of put calls for this numeric period.put.elapsed_us: The number of microseconds spent putting data for this numeric period.get.calls: The number of get calls for this numeric period.get.proxy_calls: The number of proxy get calls for this numeric period.get.count: The number of metrics retrieved for this numeric period.get.elapsed_us: The number of microseconds spent getting data for this numeric period.extend.calls: The number of extend calls for this numeric period. (The number of times the system needed to extend an NNT storage file from the beginning.)
aggregate: Aggregated data from all NNT (numeric) calls. Fields are the same as for each individual rollup.
nnt_cache_size: The current size of the NNT file handle cache. When IRONdb opens an NNT file for reading or writing, it will maintain an open file descriptor for it and store it in an LRU cache.text: A container with information about text data storage.fs: Information about file system storage for text data.id: The ID for this file system.totalMB: Megabytes of data used for this file system.freeMB: Megabytes of data available for this file system.
get: A container with information about text get calls.proxy_calls: The number of text get proxy calls.err: The number of text get errors.calls: The number of text get calls.tuples: The number of text get tuples.elapsed_us: The number of microseconds spent getting text data.
put: A container with information about text put calls.err: The number of text put errors.calls: The number of text put calls.tuples: The number of text put tuples.elapsed_us: The number of microseconds spent putting text data.
histogram: A container with information about histogram data storage.rollups: An array containing a list of all histogram data periods stored on this node.rollup_<period>: This describes data for each particular rollup. There will be one of these entries per rollup period.fs: Information about file system storage for this rollup.id: The ID for this file system.totalMB: Megabytes of data used for this file system.freeMB: Megabytes of data available for this file system.
put.calls: The number of put calls for this histogram period.put.elapsed_us: The number of microseconds spent putting data for this histogram period.get.calls: The number of get calls for this histogram period.get.proxy_calls: The number of proxy get calls for this histogram period.get.count: The number of metrics retrieved for this histogram period.get.elapsed_us: The number of microseconds spent getting data for this histogram period.
aggregate: The aggregated data from all histogram calls. The fields displayed are the same as those listed for each individual rollup.
rusage.utime: Resource Usage: User CPU time usedrusage.stime: Resource Usage: System CPU time usedrusage.maxrss: Resource Usage: Maximum resident set sizerusage.idrss: Resource Usage: Integral shared memory sizerusage.minflt: Resource Usage: Page reclaims (soft page faults)rusage.majflt: Resource Usage: Page faults (hard page faults)rusage.nswap: Resource Usage: Swapsrusage.inblock: Resource Usage: Block input operationsrusage.oublock: Resource Usage: Block output operationsrusage.msgsnd: Resource Usage: IPC messages sentrusage.msgrcv: Resource Usage: IPC messages receivedrusage.nsignals: Resource Usage: Signals receivedrusage.nvcsw: Resource Usage: Voluntary context switchesrusage.nivcsw: Resource Usage: Involuntary context switchesmax_peer_lag: The maximum amount, in seconds, by which the data on this node is behind any of the other IRONdb nodes.avg_peer_lag: The average amount, in seconds, by which the data on this node is behind any of the other IRONdb nodes.features: The features that are enabled on this node.text:store: Appears if text data storage is enabled on this node.histogram:store: Appears if histogram data storage is enabled on this node.nnt:second_order: Appears if second order derivatives for numeric data is enabled on this node.histogram:dynamic_rollups: Appears if dynamic histogram rollups are enabled on this node.nnt:store: Appears if numeric data storage is enabled on this node.features: Appears if feature flagging is enabled on this node.
version: The version of the IRONdb software running on this node.application: The name of this application.
Example 1 Output
Retrieving Gossip JSON Data
This API call retrieves gossip information from a IRONdb node. Gossip data is information on how the nodes are communicating with each other and if any nodes are behind other nodes with regards to data replication.
Data will be returned as an array of JSON objects. The format of these objects is described below.
Description
URI
/gossip/json
Method
GET
Inputs
none
Output
id: The UUID of the node whose gossip information follows.gossip_time: The last time, in seconds, that this node received a gossip message.gossip_age: The difference, in seconds, between the last time this node received a gossip message and the current time.topo_current: The topology that is currently in use.topo_next: The "next" topology to use.topo_state: The state of the current topology.latency: A JSON object that contains information on how far this node is lagging behind the other nodes. The entries will include the following:<uuid>: The UUID of the node to which the current node is being compared.<latency_seconds>: The number of seconds that the current node is behind the specified node.
Examples
Example 1 Output
Retrieving Gossip XML Data
This API call retrieves gossip information from a Snowth node. Gossip data is information on how the nodes are communicating with each other and if any nodes are behind other nodes with regards to data replication.
Data will be returned an XML object. The format of this object is described below.
Description
URI
/gossip/xml
Method
GET
Output
<nodes>: The top-level element for the topology.<node>: The container for all the information for a single node in the cluster. There will x of these elements, where "x" is the number of nodes in the cluster.Attributes:
id: The UUID of the node whose gossip information follows.gossip_time: The last time, in seconds, that this node received a gossip message.gossip_age: The difference, in seconds, between the last time this node received a gossip message and the current time.topo_current: The topology that is currently in use.topo_next: The "next" topology to use.topo_state: The state of the current topology.
<latency>: The element containing latency information for all non-local nodes.<node>: The element containing latency information for a non-local node.Attributes:
id: The UUID of the node to which the current node is being compared.diff: The number of seconds that the current node is behind the specified node.
Examples
Example 1 Output
Loading a New Topology
This API call will load a new topology onto an IRONdb node. It will not activate the topology; it will simply store and load it.
Description
URI
/topology/<hash>
Method
POST
Inputs
hash: The hash for the new topology to load.
XML Format
<nodes>: Top-Level element for the topology.Attributes:
n: The number of nodes on which the data will be stored.
<node>: The container for all the information on a single node in the cluster. There will be up to x of these, where "x" is the number of nodes in the cluster.Attributes:
id: The UUID of the node.address: The IP Address of the node.port: The port on which the node is listening.apiport: The port on which the API is listening for the node.weight: A value representing the relative preference weight of this node for metric ownership, compared to its peers.
Examples
The following example uses a file, data.xml, containing the XML document below and posts it to an IRONdb node.
In this example:
topology: The command to handle topology data.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef: This is the topology hash
data.xml contents:
Activating A New Topology
Switches a node to a new topology.
Caution
THIS IS A DANGEROUS CALL. DO NOT USE IT UNLESS YOU ARE SURE YOU KNOW WHAT YOU ARE DOING.
Description
URI
/activate/<hash>
Method
GET
Inputs
hash: The hash of the new topology after the transition.
Examples
In this example:
activate: This is the command to activate a new topology.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef: The new topology's hash
Retrieving Topology JSON Data
This API call retrieves data for a given topology in JSON format.
Data will be returned as an array of JSON objects. The format of these objects is described below.
Description
URI
/topology/json/<hash>
Method
GET
Inputs
hash: The hash of the topology for which to retrieve information.
Output
id: The UUID of the node.address: The IP Address of the node.port: The port on which the node is listening.apiport: The port on which the API is listening for the node.weight: A value representing how heavily the data to be stored on this node is weighted.n: The number of nodes on this ring on which data is stored.
Examples
In this example:
read: This is the command to read topology data from the server.json: This is the command to read data in JSON format.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef: This is the Topology Hash.
Example 1 Output
Retrieving Topology XML Data
This API call retrieves data for a given topology in XML format.
Data will be returned as an XML document. The format of this document is described below.
Description
URI
/topology/xml/<hash>
Method
GET
Inputs
hash: The hash of the topology for which to retrieve information.
Output
<nodes>: The Top-Level element for the topology.Attributes:
n: The number of nodes on which the data will be stored.
<node>: The container for all the information on a single node in the cluster. There will be up to x of these, where "x" is the number of nodes in the cluster.Attributes:
id: The UUID of the node.address: The IP Address of the node.port: The port on which the node is listening.apiport: The port on which the API is listening for the node.weight: A value representing how heavily the data to be stored on this node is weighted.
Examples
In this example:
topology: This is the command to read topology data from the server.xml: This is the command to read data in XML format.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef: This is the Topology Hash.
Example 1 Output
Retrieving Toporing JSON Data
This API call retrieves topology ring data for a given topology in JSON format.
Data will be returned as an array of JSON objects. The format of these objects is given below.
Description
URI
/toporing/json/<hash>
Method
GET
Inputs
hash: The hash of the topology to retrieve information for.
Output
id: The UUID of the node.idx: The index of an entry in the toporing. This is a number between 1 and n, where "n" is the weight of the node.location: The given location of the node.
Examples
This example retrieves a simplified topology for a 3-node cluster, assuming a weight of 3.
In this example:
toporing: This is the command to read toporing data from the server.json: This is the command to read data in JSON format.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef: This is the Topology Hash.
Example 1 Output
Retrieving Toporing XML Data
This API call retrieves toporing data for a given topology in XML format.
Data will be returned as a XML object. The format of this object is given below.
Description
URI
/toporing/xml/<hash>
Method
GET
Inputs
hash: The hash of the topology for which to retrieve information.
Output
<vnodes>: The Top-Level element for the topology.Attributes:
n: The number of nodes on which the data will be stored.
<vnode>: The container for all the information for a single virtual node in the cluster.Attributes:
id: The UUID of the node.idx: The index of an entry in the toporing. This is a number between 1 and n, where "n" is the weight of the node.location: The given location of the node.
Examples
This example retrieves a simplified topology for a 3-node cluster, assuming a weight of 3.
In this example:
toporing: This is the command to read toporing data from the server.xml: This is the command to read data in XML format.0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef: This is the Topology Hash.
Example 1 Output
Retrieving Data Location in JSON Format
This API call retrieves a list of all of the nodes on which a metric resides.
Data will be returned as a JSON object. The format of this object is described below.
Description
URI
/locate/json/<uuid>/<metric>
Method
GET
Inputs
uuid: The UUID of the check to which the metric belongs.metric: The name of the metric to locate.
Output
key: The key used to locate the metric. It is in the form<UUID>-<metric>.location: An array of JSON objects representing the nodes on which the data resides. The format of each object in the array is as follows:id: The UUID of the node.address: The IP Address of the node.port: The port on which the node is listening.apiport: The port on which the API is listening for the node.weight: A value representing the relative preference weight of this node for metric ownership, compared to its peers.n: The number of nodes in the topology on which data is stored.
Examples
In this example:
locate: This is the command to locate a check/metric.json: This is the command to read data in JSON format.6f6bdc73-2352-4bdc-ab0e-72f66d0dee12: This is the Check UUID.example: This is the Metric.
Example 1 Output
Retrieving Data Location in XML Format
This API call retrieves a list of all of the nodes on which a metric resides.
Data will be returned as an XML document. The format of this document is described below.
Description
URI
/locate/xml/<uuid>/<metric>
Method
GET
Inputs
uuid: The UUID of the check to which the metric belongs.metric: The name of the metric to locate.
Output
<nodes>: The Top-Level XML for the topology.Attributes:
n: The number of nodes on which the data will be stored.
<node>: The container for all the information on a single node in the cluster. There will be up to x of these, where "x" is the number of nodes in the cluster.Attributes:
id: The UUID of the node.address: The IP Address of the node.port: The port on which the node is listening.apiport: The port on which the API is listening for the node.weight: A value representing the relative preference weight of this node for metric ownership, compared to its peers.
Examples
In this example:
locate: This is the command to locate a check/metric.xml: This is the command to read data in XML format.6f6bdc73-2352-4bdc-ab0e-72f66d0dee12: This is the Check UUID.example: This is the Metric.
Example 1 Output
Last updated
Was this helpful?