Metrics
A metric is a measurement of a specific piece of data with a specific time stamp. For example, taking a person's temperature is a metric - it has a value (such as 103) and a time (such as today at 8:01 AM). Most metrics used in indeni are numeric in form and are called double metrics (DOUBLE_METRIC). They will be a number with a decimal point, such as 0.0, 1.0, 103.51, etc. Metrics that are not numeric, or are more complicated than just a number, are called complex metrics (COMPLEX_METRIC).
We use a DOUBLE_METRIC to describe a current state (like is a BGP peer up or down) or a numeric value that has a timestamp (like temperature). We use a COMPLEX_METRIC to describe a current configuration (human or script controlled), or in some cases, a current state when it requires more than just a 0 or 1 value.
A metric has a type (such as "under-the-tongue-temperature"), tags (which we'll get into later) and a few other aspects (also, we'll get into later).
Tags
Tags are a way of differentiating metrics of the same type, on the same device. For example, consider the "water-remaining" metric. What do you do if you have two water tanks? You can't just write double metrics for each of them without noting which belongs to which tank, that will be confusing!
Hence, the need for tags. You can add as many tags as you want. You must make sure these tags are identifiers for the metric. They are not just "auxillary" information. They actual describe the object holding the metric in a way that shouldn't change for that object.
For example, this is OK:
Issuing a metric with a tag called "id" and a value of "1" for water tank 1 and "2" for water tank "2". This means two metrics are issued, differentiated by the value under the "id" tag associated with the metric.
This is not OK:
Issuing a metric with a tag called "full" and a value of "yes" if the tank is full and "no" if the tank isn't full. This is because tags cannot change for a given object over time.
Metric Tag Types
The counter type represents a non-negative integer which monotonically increases until it reaches a maximum value of 2^32-1 (4294967295 decimal), when it wraps around and starts increasing again from zero.
What's a good counter analogy?
A counter is like an odometer. It only counts one way, it retains its value over time, unless that value is incremented, and when it hits its max, it goes back to zero.
The gauge type represents a non-negative integer, which may increase or decrease, but shall never exceed a maximum value. The maximum value can not be greater than 2^32-1 (4294967295 decimal). The value of a Gauge has its maximum value whenever the information being modeled is greater or equal to that maximum value; if the information being modeled subsequently decreases below the maximum value, the Gauge also decreases.
What's a good gauge analogy?
A gauge is more like a tachometer or a speedometer. It's telling you what's going on, at that moment. What happened five minutes ago has no inherent relationship to what's happening now, or what will be happening in five minutes. It's a point in time measurement.
Some metric and tag names are known, or reserved, for certain purposes. The "reserved" ones should never be used by you, as they will result in conflicts. The "known" one should be used as often as possible. Ideally, for each supported device, all of the "known" ones would be implemented through collection scripts.
NOTE: Device Tags and Metric Tags are different. Device Tags provide information regarding the device itself, whereas Metric Tags provide information regarding the metric.