Learn about the Wavefront native data format.

The Wavefront proxy supports several data formats. This topic describes the Wavefront native data format.

Wavefront Data Format Syntax

<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).

Wavefront Data Format Fields

Field Required Description Format
metricName Yes The 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. Metric naming hierarchy recommendations:
  • 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).
metricValue Yes The value of the metric. A 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. See Units in Chart Axes and Legends.
timestamp No The timestamp of the metric. A number reflecting 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 The name of an application, host, container, instance, or any other unique entity 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 less than 1024 characters. Prior to Wavefront proxy 2.2, this field was named host. host is still supported.
pointTags No Custom metadata associated with the metric. An arbitrary number of key-value pairs separated by spaces: <k1>="<v1>" ... <kn>="<vn>". Point tags must satisfy the following constraints:
  • Key - Valid characters are: alphanumeric, hyphen ("-"), underscore ("_"), dot (".")
  • Value - We recommend enclosing tag values with double quotes (" "). If you surround the value with quotes any character is allowed, including spaces. To include a double quote, escape it with a backslash, for example, `\"`. The backslash cannot be the last character in the tag value.
The 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. Wavefront recommends that you keep the number of distinct time series per metric and host to under 1000.

Valid Metrics

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

Invalid Metrics

  • system.cpu.load\# 0.03 source=test.wavefront.com

    • Reason: Metric name has an invalid character (‘#’)
  • system.cpu.loadavg source=test.wavefront.com

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

    • Reason: No source field

Best Practices for Point Tags

Wavefront recommends that you keep the number of distinct time series per metric and host to under 1000. Whether a time series is distinct depends on the combination of the point tag keys and the point tag values.

For example, assume a metric cpu.idle and a host web1. If you use that metric and host with the point tags env=prod and datacenter=atl, a new time series results. If you use env=dev and datacenter=atl, another distinct time series results.

Using point tags to store highly variable data such as timestamps, login emails, or web session IDs will eventually cause performance issues when your data are queried. That is also true if you specify a time that results in many time series being retrieved. For example timestamp=<now> or even monthofyear=11 can exceed the limit. In contrast, dayofweek=monday or monthofyear=jan are acceptable.

See Series Matching for more info on:

  • Series matching with point tags.
  • Series matching with point tags and the byconstruct.