Installer Templates

Configuration templates

Default templates are maintained in this repository. At the time of this writing the default templates available are:

• check-system
• worksheet-system
• graph-cpu
• graph-df
• graph-disk
• graph-fs
• graph-if
• graph-load
• graph-systemd
• graph-vm

The core of the naming convention is type-id. Type (check|graph|worksheet) and ID representing the entity for which the template exits (e.g. the system, cpu, memory vm, filesystem fs, network interfaces if, etc.) This naming schema is reflected in all files persisted in /opt/circonus/cosi/registration.

When the files are placed into the registration directory, they will be prepended with their category (template|config|registration). Specifics will be postfixed to the file names, separated by the dash '-' character. For variable graphs, the specific item being graphed: a network interface, filesystem, or disk. Additionally, a graph configuration template may contain more than one graph so, each graph will have an index identifier in its file name.

For example: (in /opt/circonus/cosi/registration)

File	Description
template-graph-vm.json	the configuration template for memory (VM) graphs
config-graph-vm-0.json	the configuration for vm graph 1 (what is sent to the Circonus API to create the graph)
config-graph-vm-1.json	the configuration for vm graph 2
registration-graph-vm-0.json	the registration for vm graph 1 (what was received from the Circonus API, when the graph is created)
registration-graph-vm-1.json	the registration for vm graph 2

The artifacts from each step of the process are retained, as well as logged, to ensure that troubleshooting is as efficient as possible, complete traceability. Enabling desktop debugging rather than needing to fully reproduce the exact environment and circumstances.

When issues occur send a description of the issue with a file made with: cd /opt/circonus/cosi && tar -zcf cosi-issue.tgz log/ registration/

Format

Configuration templates follow a formatting standard:

• JSON
• A meta data section containing ancillary data about the template
• A config section containing the skeleton of what would be sent to the Circonus API

Meta

{
	"type": "(check|graph|worksheet)",
	"id": "what is this template for... e.g. (system|cpu|fs|vm|etc)",
	"description": "an english language description of the template and its purpose",
	"version": "semver",
	"notes": [
		"array of strings containing notes for using the template"
	]
}

note: type-id must also be derivable from the file name e.g. file name=check-system.json, type must equal "check" and id must equal "system".

Check

{
	...meta, 
	"check": {
			"...check bundle definition"
	}
}

• Circonus API Check Bundle documentation for check bundle definition

Graph

{
	...meta, 
	"variable_metrics": "boolean",
	"filter": {
		"include": [],
		"exclude": []
	},
	"graphs": [
		{
			"...graph definition"
		}
	]
}

• Circonus API Graph documentation for graph definition
• variable_metrics - boolean (default: false), does this graph contain variable items such as fs, if, etc.
• filter - array of strings (for each, include and exclude) the graph_item string will be compared literally (javascript ===) to each metric available from NAD for that type (e.g. vm, fs, if, etc.)

For graphs where variable_metrics: true, the metric_name property of each item in datapoints is a regular expression not a literal string. These regular expressions will be evaluated against the literal metric names available from the NAD endpoint. The regular expression should include an extraction grouping () which will manifest itself as the graph_item variable in field interpolation.

For example: (template is graph-fs.json)

• template.graphs[0].datapoints[0].metric_name is "fs`([^`]+)`df_used_percent"
• NAD literal metric name is fs`/`df_used_percent
• resulting variable metric datum used to build configuration:
  • graph_item = /
  • variable metric name is fs`/`df_used_percent (used as value for metric_name in graph 0)

Worksheet

...meta, 
	"config": {
			"...worksheet definition"
	}
}

• Circonus API Worksheet documentation for worksheet definition