Syntax and parameters of the Wavefront native data format.

The Wavefront data format is supported by Wavefront proxies and by direct ingestion. This page is a reference to the Wavefront data format. See Wavefront Data Naming for best practices.


Supported Data Formats for Metrics

Direct ingestion supports only the Wavefront data format.

Wavefront proxies support:

Metrics Data Format Syntax

Here’s the Wavefront data format for metrics.

<metricName> <metricValue> [<timestamp>] source=<source> [pointTags]

Fields must be space separated and each line must be terminated with the newline character (\n or ASCII hex 0A). See the Data Format Fields table below for details about each parameter.

Wavefront Data Format Fields

Field Required Description Format
metricName Yes Name of the metric. Valid characters are: a-z, A-Z, 0-9, hyphen ("-"), underscore ("_"), dot ("."). Forward slash ("/") and comma (",") are allowed if metricName is enclosed in double quotes. Maximum length for metricName is 256.
metricValue Yes Value of the metric. Number that can be parsed into a double-precision floating point number or a long integer. It can be positive, negative, or 0. In charts, the Wavefront UI represents values using SI and IEC/Binary units.
timestamp No Timestamp of the metric. Number that reflects the epoch seconds of the metric (e.g. 1382754475). When this field is omitted, the timestamp is set to the current time at the Wavefront proxy when the metric arrives.
source Yes Name of an application, host, container, instance, or any other unique source that is sending the metric to Wavefront. Valid characters are: a-z, A-Z, 0-9, hyphen ("-"), underscore ("_"), dot ("."). The length of the source field should be no more than 128 characters. Using host= instead of source= is supported for backward compatibility but not recommended.
pointTags No Custom metadata associated with the metric. An arbitrary number of key-value pairs separated by spaces: <k1>="<v1>" ... <kn>="<vn>". Point tags cannot be empty, i.e. tagKey="" and tagKey= are invalid. Point tags must also satisfy these constraints:
  • Key - Valid characters: alphanumeric, hyphen ("-"), underscore ("_"), dot (".")
  • Value - Enclose tag values with double quotes (" "). If you surround the value with double quotes, any character is allowed, including spaces. To include a double quote, escape it with a backslash, for example, `\"`. A backslash cannot be the last character in the tag value.
Maximum allowed length for a combination of a point tag key and value is 254 characters (255 including the "=" separating key and value). If the value is longer, the point is rejected and logged. Keep the number of distinct time series per metric and host to under 1000.

The string "host" is a reserved word. If you specify a point tag host=<tagValue>, we evaluate it as follows:
  • If the expression also specifies source="<sourceValue>", we add an underbar character to the host point tag. The result is "_host=<tagValue>"
  • If the expression does not specify source=<sourceValue>, we treat "host=" as a source and not as a point tag key.

Video: Point Tags and Source Tags

Watch the following video for an introduction to point tags and source tags:


Valid and Invalid Metrics Examples

The following metrics are valid:

  • request.count 1001
  • system.cpu.loadavg.1m 0.03 1382754475
  • marketing.adsense.impressions 24056 source=campaign1
  • new-york.power.usage 42422 source=localhost datacenter="dc1"

The following metrics are invalid. For each metric, we explain why it’s invalid.

  • system.cpu.load\# 0.03

    • Reason: Metric name has an invalid character (‘#’)
  • system.cpu.loadavg

    • Reason: No metric value
  • cpu0.loadavg.1m 0.03

    • Reason: No source field

Histograms and Spans

Most of our discussion of the histogram and span data formats is on the pages linked below. Here’s an overview.

Histogram Data Format Syntax

Histograms have port requirements and use the following format:

{!M | !H | !D} [<timestamp>] #<points> <metricValue> [... #<points> <metricValue>]
 <metricName> source=<source> [<pointTagKey1>=<value1> ... <pointTagKeyn>=<valuen>]

Span Data Format Syntax

The span format supports several predefined span tags.

<operationName> source=<source> <spanTags> <start_milliseconds> <duration_milliseconds>

Wavefront Data Format Best Practices

Follow best practices for improved query execution speed and meaningful results.

  • Make the metrics the most stable part of your data:
    • Do not include source names in the metric name. Wavefront captures sources separately.
    • Do not include data or timestamps in the metric name. Each point has an associated timestamp.
  • Aim for a metric hierarchy:
    • Partition the top level of the metric hierarchy by including at least one dot.
    • Organize metric names in a meaningful hierarchy from most general to most specific (i.e. system.cpu0.loadavg.1m instead of 1m.loadavg.cpu0.system)
  • For best performance, keep the number of distinct time series per metric and host to under 1000.

See Wavefront Data Naming for a more best practices.