Installer Registration

Registration options

Registration can be customized by overriding defaults and/or providing custom data to be used in configuration templates. A custom registration options configuration file, in JSON format, can be pre-installed or placed on the system as part of configuration management and/or orchestration. The options are additive, more specific options will override generic options of the the same name.

The options are used when setting and interpolating specific fields within the configuration templates.

Replacement fields

1. Check - display_name, metric_limit, and target
2. Graph - title and description
3. Worksheet - title and description

Interpolation fields

1. Check - display_name and target
2. Graph - title and description
3. Worksheet - title and description

Tags

Tags are a special case, if specified, each custom options tag will be added to the default tags created by cosi.

Default configuration data

{
	"host_name": "",
	"host_target": "",
	"num_cpus": ""
}

• host_name default is what is returned from node's os.hostname() call.
• host_target default is first non-internal IP Address returned from node's os.networkInterfaces() call. The primary use for host_target is a multihomed system where a specific interface/address should be used by the Broker for a pull check. The target is arbitrary for a push (HTTPTRAP) check.
• num_cpus is the length of the array returned from a call to node's os.cpus().

Structure

The host_* items apply to everything. host_name, host_target and any variables defined in host_vars will be available in all interpolation fields. Any tags defined in host_tags will be added to everything (check, graphs, worksheet).

{
	//
	// settings applicable to *everything*
	//
    host_name: "string",      // default - what is returned from os.hostname()
    host_target: "string",    // default - first non-internal IP from os.networkInterfaces()
    host_tags: ["strings"],   // default - cosi tags are added to all checks, graphs, worksheets
    host_vars: {},            // default - { num_cpus: os.cpus().length }

    //
    // settings applicable to *all* checks
    //
    check: {
        display_name: "string",  // default - interpolation pattern from template
        target: "string",        // default - interpolation pattern from template
        metric_limit: "number",  // default - from template
        tags: ["strings"],       // default - none
        vars: {},                // default - none
        //
        // settings applicable to a specific check (e.g. check-system)
        //
        check-<id>: {
            display_name: ...,
            target: ...,
            tags: ..., 
            metric_limit: ...,
            vars: ...
        }
    }
    
    //
    // settings applicable to *all* graphs
    //
    graph: {
        title: "string",       // default - interpolation pattern from template
        description: "string", // default - interpolation pattern from template
        tags: ["strings"],     // default - none
        vars: {},              // default - none
        //
        // settings applicable to a specific graph ID (e.g. graph-vm)
        //
        graph-id: {
            title: ...,
            description: ...,
            tags: ...,
            vars: ...,
            //
            // settings applicable to a specific graph item (e.g. graph-disk-sda)
            //
            graph-item: {
                title: ...,
                description: ...,
                tags: ..., 
                vars: ...
            }
        }
    }
    
    //
    // settings applicable to *all* worksheets
    //
    worksheet: {
        title: "string",       // default - interpolation pattern from template
        description: "string", // default - interpolation pattern from template
        tags: ["strings"],     // default - none
        vars: {},              // default - none
        //
        // settings applicable to a specific worksheet ID (e.g. worksheet-system)
        //
        worksheet-id: {
            title: ...,
            description: ...,
            tags: ...,
            vars: ...
        }
    }
}

All of the settings are optional. As noted above, more specific settings will override the generic settings. For example, worksheet-system.title will override worksheet.title which overrides whatever is set in the template.

Field interpolation patterns

{{=cosi.<variable name>}} e.g. {{=cosi.host_name}} would be replaced by the host_name setting, {{=cosi.num_cpus}} would be replaced by the host_vars.num_cpus setting which, at the time of interpolation is simply num_cpus.

Examples

• Host name: web01.example.com
• Host IP: 10.28.36.100
• CPUs: 4

Default data used for configuration templates:

{
	host_name: "web01.example.com",
	host_target: "10.28.36.100",
	num_cpus: 4
}

We have some additional metadata we'd like to expose datacenter and cluster id. We want to specify some custom tags and make the metadata available for some custom field interpolation. So we will add a custom options configuration file in /opt/circonus/cosi/etc/registration-options.json. (and let the installer know about it by adding another command line option --regconf /opt/circonus/cosi/etc/registration-options.json.)

{
	"host_vars": {
		"datacenter": "sfo1",
		"cluster_id": "w3"
	},
	"host_tags": [
		"cluster:w3",
		"dc:sfo1"
	],
	"check": {
		"check-system": {
			"display_name": "{{=cosi.host_name}} system/{{=cosi.datacenter}}.{{=cosi.cluster_id}}"
		}
	}
}

When the system check is created for this host:

1. The check.display_name property will be replaced with the interpolation pattern specified.
2. The check.tags property will contain the default cosi tags, as well as, the two new tags specified in host_tags.
3. The data used for interpolation will be:

{
	host_name: "web01.example.com",
	host_target: "10.28.36.100",
	num_cpus: 4,
	datacenter: "sfo1",
	cluster_id: "w3"
}