Torrus Architecture

Configuration processing

The XML configuration is compiled into the database representation by operator's manual request.

A compiled version of configuration is not a one-to-one representation of the XML version. All templates are expanded. Backward restoration of XML from the database is available with the snapshot utility.

A template defines a piece of configuration which can be used in multiple places. Templates can be nested.

The configuration consists of multiple XML files. They are processed in the order as specified in the tree configuration. Each new file is treated as an additive information to the existing tree.

The XML configuration compiler validates all the mandatory parameters.

Data storage

Three types of data stores are used in Torrus:

Tree configuration

The configuration consists of multiple trees. A tree consists of nodes, and each node can be of type "leaf" or "subtree". Subtrees contain child subtrees or leaves, and a leaf does not contain any child elements. Each node has an arbitrary number of parameters. Some parameters can prohibit recursion, but most of parameters are calculated by traversing the tree upwards, until a value is found.

Each node has a path within a tree. A subtree path ends always with a slash, and a leaf path ends with a word character. The top of the tree is identified by a single slash symbol. The node names in the path allow alphanumeric characters, dash and underscore.

Each node is identified by a token. A node token a 40-character SHA-1 checksum calculated from the tree name, followed by a colon, and the path.

ConfigTree objects

ConfigTree Perl module provides an API for accessing the configuration trees, as well as other types of data. Each data element is referred to by a token, as follows:

Tree node token is a 40-character SHA-1 checksum of a node as described above.

Tokenset name starts with letter S. The rest is an arbitrary sequence of word characters.

The special token SS is reserved for tokensets list. Also tokenset parameters are inherited from this token's parameters.

View and monitor names must be unique, and must start with a lower case letter.

Git storage

A Torrus instance uses a number of Git branches for each tree configuration. The XML compiler is the only writer, and consumers are only reading from the Git repositories. Both writing and reading is done directly on local Git repositories, so working directories are not needed. If the writer and reader are on the same host, they use the same Git repository. Otherwise, the writer pushes its commits to a remote repository, and the reader pulls from it. The reader sets an exclusive lock on the repository for the time of fetching and merging, so that other readers don't try to pull at the same time.

Each tree has its own set of branches. The TREE_configtree branch contains a full hierarchy of objects, so all parameters that are defined in the input XML are retrievable. Typically the Web UI renderer is consuming this data.

The TREE_srcfiles branch contains XML files that are used by the XML compiler. While processing the XML files, it adds them into this branch in order to track the changes in XML sources.

Also there's a number of agent branches, one per agent instance (collectors and monitors are typical agents): TREE_DAEMON_INSTANCE. Each such branch contains only the information and parameters needed by the agent, so that the agent process can start and update its data as fast as possible.

A Git reference refs/heads/TREE_agents_ref is used to indicate the commit in TREE_configtree branch that corresponds to the current heads in agent branches. This reference is moved when the agent branches are updated.

The TREE_agent_tokens branch is used to store the information which agent branches have which tokens. It is needed for deleting tokens from agent branches when they are deleted from configtree branch. The branch contains two-level 256-way directory hierarchy, for every token, and the JSON files contain arrays with agent branch names where a particular token is used.

The TREE_configtree branch has subdirectories as follows. The directories nodes and children contain JSON files named after the node tokens, arranged into two-level 256-way tree structure. For example, the file for token b7ba0d88a0b14a4e6c3c61f5446aa619a537098f is stored as b7/ba/0d88a0b14a4e6c3c61f5446aa619a537098f.

The srcdef structure is mainly required for recursive deletion of nodes if a corresponding XML file is changed or deleted.

Each Git commit refers to a complete and consistent tree structure. If the compiler finds an error, it does not create a new commit, and rolls back to the latest HEAD.

The JSON files within nodes hierarchy are hashes with the following keys and values:

The JSON files within other are hashes with the following keys and values:

The agent branches contain JSON files named after the node tokens, arranged into two-level 256-way tree structure. Each daemon that needs a quick access to a subset of leaf nodes (primarily, collector, and also monitor) retrieve the node configurations from this structure. The instance number is a 4-digit lower-case hexademical number. The JSON files are hashes defining all parameter values needed by the daemon. These files are populated by the XML compiler after the tree is processed.

An optional searchdb branch is used for indexing the node parameters in order to provide the search in GUI. It consists of the following directories:

Redis database

Redis is an in-memory database, supporting key/value hashes and linear arrays, with periodic saving to disk storage. Torrus keeps all run-time and dynamic information in Redis.

All Redis keys that are used within a single Torrus installation are prefixed with a configurable prefix ("torrus:" by default), thus allowing multiple Torrus installations to use the same Redis instance. Further in this document, the prefix is omitted for easier reading.

PubSub channels:

users contents

acl contents

monitor_alarms contents

serviceid_params contents

snmp_failures contents

Search and indexing service

Searching within trees is implemented in a standalone service, consisting of two parts:

1. the daemon that subscribes to treecommits:* channels and updates its database after every commit;
2. a RESTful API service for retrieving the search results


Copyright (c) 2016-2017 Stanislav Sinyagin