Skip to content

OpenMetrics Format Specification

OpenMetrics is today's de-facto standard for transmitting cloud-native metrics at scale. For now, Gufo Agent supports only text representation for reading metrics from third-party sources and to expose all collected metrics.

This chapter gets a quick introduction into the format and inteded for external plugins developers. See OpenMetrics Specification for a formal explanation.

Lets see a simple example:

sample1.txt
1
2
3
4
5
6
7
8
9
# HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

The file consist of the metric families. Each family starts with descriptors:

sample1.txt
1
2
3
4
5
6
7
8
9
# HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

followed by the samples:

sample1.txt
1
2
3
4
5
6
7
8
9
# HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

Descriptors

sample1.txt
1
2
3
4
5
6
7
8
9
# HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

The descriptor line has format:

# <type> <metric_name> <value>

Where:

  • <type> is a type of descriptor.
  • <metric_name> is a name of the following metric.
  • <value> - descriptor-specific value.

Gufo Agent recognizes following descriptor type:

  • HELP - Brief textual description of the metrics family.

    sample1.txt
    1
2
3
4
5
6
7
8
9
    # HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

  • TYPE - Metric type. One of:

    sample1.txt
    1
2
3
4
5
6
7
8
9
    # HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

    • gauge - Measurement result.
    • counter - Incrementaly increased counter.

  • UNIT - Measurement units, now ignored.

Samples

sample1.txt
1
2
3
4
5
6
7
8
9
# HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

Each metric family consists of one or more samples. Sample line has following format:

<metric_name>[<labels>] <value>[ <timestamp>]

Where:

  • <metric_name> - Name of the metric.
  • <labels> - Optional labels are enclosed between { and }.
  • <value> - Measured value.
  • <timestamp> - Optional timestamp in seconds from the UNIX epoch.

EOF mark

sample1.txt
1
2
3
4
5
6
7
8
9
# HELP job_success Successful job
# TYPE job_success counter
job_success{dc="east",dept="business"} 12
job_success{dc="west",dept="tech"} 12
# HELP job_failed Failed job
# TYPE job_failed counter
job_failed{dc="east",dept="business"} 1
job_failed{dc="west",dept="tech"} 4
# EOF

End-of-file mark placed to the end of the output. Though it is advisored for the Gufo Agent, other OpenMetrics implementations may require it.