9.2. Typed output format

Both "show info" and "show stat" support a mode where each output value comes
with its type and sufficient information to know how the value is supposed to
be aggregated between processes and how it evolves.
 
In all cases, the output consists in having a single value per line with all
the information split into fields delimited by colons (':').
 
The first column designates the object or metric being dumped. Its format is
specific to the command producing this output and will not be described in this
section. Usually it will consist in a series of identifiers and field names.
 
The second column contains 3 characters respectively indicating the origin, the
nature and the scope of the value being reported. The first character (the
origin) indicates where the value was extracted from. Possible characters are :
 
  M   The value is a metric. It is valid at one instant any may change depending
      on its nature .
 
  S   The value is a status. It represents a discrete value which by definition
      cannot be aggregated. It may be the status of a server ("UP" or "DOWN"),
      the PID of the process, etc.
 
  K   The value is a sorting key. It represents an identifier which may be used
      to group some values together because it is unique among its class. All
      internal identifiers are keys. Some names can be listed as keys if they
      are unique (eg: a frontend name is unique). In general keys come from the
      configuration, even though some of them may automatically be assigned. For
      most purposes keys may be considered as equivalent to configuration.
 
  C   The value comes from the configuration. Certain configuration values make
      sense on the output, for example a concurrent connection limit or a cookie
      name. By definition these values are the same in all processes started
      from the same configuration file.
 
  P   The value comes from the product itself. There are very few such values,
      most common use is to report the product name, version and release date.
      These elements are also the same between all processes.
 
The second character (the nature) indicates the nature of the information
carried by the field in order to let an aggregator decide on what operation to
use to aggregate multiple values. Possible characters are :
 
  A   The value represents an age since a last event. This is a bit different
      from the duration in that an age is automatically computed based on the
      current date. A typical example is how long ago did the last session
      happen on a server. Ages are generally aggregated by taking the minimum
      value and do not need to be stored.
 
  a   The value represents an already averaged value. The average response times
      and server weights are of this nature. Averages can typically be averaged
      between processes.
 
  C   The value represents a cumulative counter. Such measures perpetually
      increase until they wrap around. Some monitoring protocols need to tell
      the difference between a counter and a gauge to report a different type.
      In general counters may simply be summed since they represent events or
      volumes. Examples of metrics of this nature are connection counts or byte
      counts.
 
  D   The value represents a duration for a status. There are a few usages of
      this, most of them include the time taken by the last health check and
      the time a server has spent down. Durations are generally not summed,
      most of the time the maximum will be retained to compute an SLA.
 
  G   The value represents a gauge. It's a measure at one instant. The memory
      usage or the current number of active connections are of this nature.
      Metrics of this type are typically summed during aggregation.
 
  L   The value represents a limit (generally a configured one). By nature,
      limits are harder to aggregate since they are specific to the point where
      they were retrieved. In certain situations they may be summed or be kept
      separate.
 
  M   The value represents a maximum. In general it will apply to a gauge and
      keep the highest known value. An example of such a metric could be the
      maximum amount of concurrent connections that was encountered in the
      product's life time. To correctly aggregate maxima, you are supposed to
      output a range going from the maximum of all maxima and the sum of all
      of them. There is indeed no way to know if they were encountered
      simultaneously or not.
 
  m   The value represents a minimum. In general it will apply to a gauge and
      keep the lowest known value. An example of such a metric could be the
      minimum amount of free memory pools that was encountered in the product's
      life time. To correctly aggregate minima, you are supposed to output a
      range going from the minimum of all minima and the sum of all of them.
      There is indeed no way to know if they were encountered simultaneously
      or not.
 
  N   The value represents a name, so it is a string. It is used to report
      proxy names, server names and cookie names. Names have configuration or
      keys as their origin and are supposed to be the same among all processes.
 
  O   The value represents a free text output. Outputs from various commands,
      returns from health checks, node descriptions are of such nature.
 
  R   The value represents an event rate. It's a measure at one instant. It is
      quite similar to a gauge except that the recipient knows that this measure
      moves slowly and may decide not to keep all values. An example of such a
      metric is the measured amount of connections per second. Metrics of this
      type are typically summed during aggregation.
 
  T   The value represents a date or time. A field emitting the current date
      would be of this type. The method to aggregate such information is left
      as an implementation choice. For now no field uses this type.
 
The third character (the scope) indicates what extent the value reflects. Some
elements may be per process while others may be per configuration or per system.
The distinction is important to know whether or not a single value should be
kept during aggregation or if values have to be aggregated. The following
characters are currently supported :
 
  C   The value is valid for a whole cluster of nodes, which is the set of nodes
      communicating over the peers protocol. An example could be the amount of
      entries present in a stick table that is replicated with other peers. At
      the moment no metric use this scope.
 
  P   The value is valid only for the process reporting it. Most metrics use
      this scope.
 
  S   The value is valid for the whole service, which is the set of processes
      started together from the same configuration file. All metrics originating
      from the configuration use this scope. Some other metrics may use it as
      well for some shared resources (eg: shared SSL cache statistics).
 
  s   The value is valid for the whole system, such as the system's hostname,
      current date or resource usage. At the moment this scope is not used by
      any metric.
 
Consumers of these information will generally have enough of these 3 characters
to determine how to accurately report aggregated information across multiple
processes.
 
After this column, the third column indicates the type of the field, among "s32"
(signed 32-bit integer), "s64" (signed 64-bit integer), "u32" (unsigned 32-bit
integer), "u64" (unsigned 64-bit integer), "str" (string). It is important to
know the type before parsing the value in order to properly read it. For example
a string containing only digits is still a string an not an integer (eg: an
error code extracted by a check).
 
Then the fourth column is the value itself, encoded according to its type.
Strings are dumped as-is immediately after the colon without any leading space.
If a string contains a colon, it will appear normally. This means that the
output should not be exclusively split around colons or some check outputs
or server addresses might be truncated.