Naming schema
collectd uses are very powerful naming schema to identify each statistics value. It has been proven very generic and flexible, but may be confusing at first, especially to new plugin authors. This page tries to explain the schema in more detail.
Unfortunately it's necessary to get some terminology sorted out first: The main data type collectd handles when passing performance data around is a value-list which we usually call “value” for short. The data type is called value-list-t and is defined in src/plugin.h. The name value list is no mistake: It may consist of more than one actual data points. So keep in mind that we talk about a value but usually mean a group of values.
A value is identified by a unique name, which we usually call “identifier”. The identifier consists of five parts, two of which are optional:
- host
- plugin
- plugin instance (optional)
- type
- type instance (optional)
Each field is basically a free-text field, though certain limitations apply:
- Each field has a fixed maximum length. Currently this limit is 63 characters, but may be extended in the future.
- The fields host, plugin instance, and type instance may use all ASCII characters except the null-byte and the slash character (‘/’).
- The fields plugin and type may use all ASCII characters except null-byte, the slash character (‘/’), and the dash character (‘-’).
The serialized form of the identifier is:
host "/" plugin ["-" plugin instance] "/" type ["-" type instance]
You can use the format_name function and the FORMAT_VL macro (both declared in src/common.h) to serialize an identifier.
Because no field may contain the slash character and the plugin and type fields may not contain the dash character, parsing the serialized form is easily possible. You can use the parse_identifier function (declared in src/common.h) to do this.
These are a few examples of valid identifiers.
leeloo/cpu-0/cpu-idlealyja/memory/memory-usedwanda/disk-hdc1/disk_octetsleeloo/load/load
The difference of the plugin instance field and the type instance field is not very intuitive.
The idea is to group values belonging together using the same plugin instance. Take the Disk plugin, for example: The plugin instance is set to the name of the device or partition, creating a sort of "namespace" for each device.
The type instance is used to separate values of identical type which nonetheless belong to one another. The Memory plugin is an example of this: All values are of type “memory” and the type instance is set to “used”, “free”, etc. to describe the data contained in the file further. Using the plugin instance here would not be correct, because all files belong to the same physical memory.
An example which combines both fields would be the CPU plugin: Values for each CPU are grouped using the plugin instance. Since all values are of type “cpu”, the type instance is used to specify which data is contained, “user”, “idle”, etc.
Unfortunately, not all plugins use this correctly. The Interface plugin sets the type instance to the name of the interface, when in fact it should use the plugin instance for this. Changing such mistakes is a backwards incompatible change, however, and is therefore on our ToDo-list for the next major version.