In indeni.hawk, a series of functions are defined. They are simply helper functions that can be used in .ind scripts.
...
Collector output functions
See Metrics for more information about the metric types. This will help you when choosing type for new metrics.
writeTag(name, value)
write a tag to be associated with a device. Tags can only be written in an interrogation script. These tags are used by monitoring scripts (as well as some interrogation scripts) in the "requires" section at the top of the script (see /wiki/spaces/IKP/pages/54198315).
writeDoubleMetric(imName, tags, dsType, value, isLiveConfig, [displayName], [displayType], [identityTags])
writes a DOUBLE metric (see metrics) with the following information:
imName - the name of the metric
tags - tags to add to the metric. You can just write "null" (without quotes) to keep this empty. If you want to include tags (and read the "Tags" session in metrics VERY carefully), you need to initialize a tag array prior to making the call to writeDoubleMetric, like so:
Code Block linenumbers true For this input: Water level tank #1: 1.7 L Water level tank #2: 2.8 L This script: /Water level/ { id = $4 gsub(/#/,"", id) waterLevelTags["id"] = id writeDoubleMetric("water-level", waterLevelTags, "gauge", 60, $(NF-1)) }TIP: All variables in awk are global. DO NOT reuse the same variable names for tags for different metrics. In the example above, if we were to use waterLevelTags with another metric it would copy the "id" element with it. Only re-use the tag variables if indeed the tags must be the same.
dsType - Either "counter" or "gauge". Most often, it's gauge. A gauge metric just has a value: it can be any double value. Often it's a boolean, either 0.0 or 1.0. But, it could be, e.g., current CPU or memory usage: any sort of 'point-in-time' value that can go 'up or down'. "counter" is for a value that only increases: use it for for metrics which count how many times something has happened (for example, RX packets on a network interface). counter can never go down in value (unless it reaches its maximum value and wraps back to 0).
- value - a number (like 17.1 or 155513532423.1015) for the metric
- isLiveConfig – a string that should be either "true" or "false", denoting whether or not you want the metric to go to liveConfig. The "live config" (AKA "actual config") represents the most current data Indeni has pulled from a device (e.g., current memory usage, currently configured DNS servers). This data gets displayed in the Indeni GUI. Note that displayName is a mandatory argument when isLiveConfig is "true"
displayName - A string to categorize the metric. Shown to the user in the live config. Optional when isLiveConfig is "false" and mandatory when isLiveConfig is "true"
displayType - A string identifying the units of the to display, as documented in Reserved Metric/Tag Names. E.g., "percentage", "kilobytes", or "duration". May add units symbols to the live config display (e.g., "%")
identityTags - A string which corresponds to a key in the metric tag(s) array (see example below). If you pass no metric tags (i.e., the "tags" parameter is "null"), this string should be empty (""). You can pass multiple identityTags in the same string parameter, each separated by "|" (see notes below).
Example
Code Block memoryTag["name"] = "Free Memory" writeDoubleMetric("memory-free-kbytes", memoryTag, "gauge", free, "true", "Memory Usage", "kilobytes", "name") memoryTag["name"] = "Total Memory" writeDoubleMetric("memory-total-kbytes", memoryTag, "gauge", total, "true", "Memory Usage", "kilobytes", "name") memoryTag["name"] = "Used Memory" writeDoubleMetric("memory-used-kbytes", memoryTag, "gauge", used, "true", "Memory Usage", "kilobytes", "name") memoryTag["name"] = "Percent Memory Usage" writeDoubleMetric("memory-usage", memoryTag, "gauge", percentMemoryUsage, "true", "Memory Usage", "percentage", "name")The above code results in this live config:
In this way, you can create a "category" ("Memory Usage" above) and group related metrics. A few notes:- If you don't use any metricTag or identityTag, the live config data will display under the "Overview" category.
- Some rules require a metricTag/identityTag pair. They essentially require that you add live config for display. E.g., in the rule "/templatebased/crossvendor/cross_vendor_high_memory_usage.scala", there is an applicableMetricTag = "name" passed to the constructor. This gives you a clue that you need to include a name metricTag/identityTag (exactly as per the example above); if you don't, you won't get an alert!
- You can add any data to the live config – you don't need a rule or any existing, known metric. E.g.,Code Block metricTag["mylabel"] = "First Label" writeDoubleMetric("foo-metric", metricTag, "gauge", "77", "true", "Special Category", "percentage", "mylabel")This will display just fine and only in the live config.
- You can also pass multiple identityTags in the identityTags string parameter, each separated by "|": E.g.,Code Block pstags["name"] = pid pstags["process-name"] = processname writeDoubleMetric("process-cpu", pstags, "gauge", cpuUsage, "true", "Processes (CPU)", "percentage", "name|process-name")This will display like: "name-<PID> process-name-<some process name> <cpuUsage>"
writeComplexMetricString(imName, tags, value, isLiveConfig, [displayName])
similar to writeDoubleMetric, except that the value is a string. For example, for the "vendor" metric described in the list of reserved metrics, you would use this function:
isLiveConfig – A string that should be either "true" or "false"
writeComplexMetricString("vendor", null, "acme", "false")
displayName – Optional if isLiveConfig is "false" and mandatory if isLiveConfig is "true". See displayName in example for doubleMetric live config above.writeComplexMetricObjectArray(imName, tags, arrayValue, isLiveConfig, [displayName])
similar to writeComplexMetricString, except that the value is a json array of objects.isLiveConfig – A string that should be either "true" or "false"
displayName – Optional if isLiveConfig is "false" and mandatory if isLiveConfig is "true". See displayName in example for doubleMetric live config above.leverages AWK's capabilities of building a key-value map to make it easier to describe a complex object array. Here is an example of how to use it:
Code Block linenumbers true For this input: User Uid Gid Home Dir. Shell Real Name admin 0 0 /home/admin /etc/cli.sh n/a indeni 0 100 /home/indeni /bin/bash Indeni monitor 102 100 /home/monitor /etc/cli.sh Monitor We can use this ind script: /home/ { iuser++ users[iuser, "username"] = $1 users[iuser, "uid"] = $2 users[iuser, "gid"] = $3 } END { # We normally dump the metric itself at the end of the script, because we spend the script collecting the items # and then we write it once we have it all collected. writeComplexMetricObjectArray("users", null, users, "false") }writeDebug(string)
debug(string)
Writes the string to the debug output for the AWK parser. The debug output is only visible when the command runner, or the indeni-collector (in a live system) is run under debug mode. For example, you added this line to an ind script:
Code Block debug("I am a debug string")Then this would result in nothing:
Code Block bash command-runner.sh full-command --ssh indeni,indeni test.ind 10.3.3.72 | grep "I am"
Whereas this (using the --verbose switch) would would print the debug string:
Code Block bash command-runner.sh full-command --verbose --ssh indeni,indeni test.ind 10.3.3.72 | grep "I am" 2016-10-10 07:22:58,309 26823 DEBUG - I am a debug string
...
The break statement jumps out of the innermost for, while, or do loop that encloses it. Some times you don't want to continue the processing in
Multi-Step functions
- writeDynamicVariable(dynamicVariableName, sourceVariable)
Create a "dynamic" variable to pass from one step to the next in a /wiki/spaces/IKP/pages/75890692. E.g., writeDynamicVariable("nics", niclist). - dynamic(dynamicVariableName)
Use the dynamic varibale name in your code. This function will actually replace return as result the variable value. E.g., dynamic("nics")