Metric Event

Description

A Vector metric event represents a numerical operation performed on a time series. Unlike other tools, metrics in Vector are first class citizens, they are not represented as structured logs. This makes them interoperable with various metrics services without the need for any transformation.

Vector's metric data model favors accuracy and correctness over ideological purity. Therefore, Vector's metric types are a conglomeration of various metric types found in the wild, such as Prometheus and Statsd. This ensures metric data is correctly interoperable between systems.

Schema

counter

{
  "metric" : {
    "counter" : {
      "value" : 1
    },
    "kind" : "absolute",
    "name" : "memory_available_bytes",
    "namespace" : "host",
    "tags" : {
      "host" : "my.host.com",
      "instance_id" : "abcd1234"
    },
    "timestamp" : "2020-10-10T17:07:36+00:00"
  }
}

6 items

commonrequired

commonoptionaltable
counter
A single value that can only be incremented or reset to zero value, it cannot be decremented.
- commonrequiredfloat
  value
  The value to increment the counter by. Can only be positive.
  - View examples
enumcommonrequiredstring
kind
The metric value kind.
- Syntax: literal
- Enum, must be one of: "absolute" "incremental"
- View examples
commonrequiredstring
name
The metric name.
- Syntax: literal
- View examples
commonrequiredstring
namespace
The metric namespace. Depending on the service, this will prepend the name or use native namespacing facilities.
- Syntax: literal
- View examples
commonrequiredtable
tags
The metric tags. Key/value pairs, nesting is not allowed.
- commonoptional*
  *
  Key/value pairs, nesting is not allowed.
commonrequiredtimestamp
timestamp
The metric timestamp; when the metric was created.
- View examples

distribution

{
  "metric" : {
    "distribution" : {
      "samples" : {
        "rate" : 12,
        "value" : null
      },
      "statistic" : "histogram"
    },
    "kind" : "absolute",
    "name" : "memory_available_bytes",
    "namespace" : "host",
    "tags" : {
      "host" : "my.host.com",
      "instance_id" : "abcd1234"
    },
    "timestamp" : "2020-10-10T17:07:36+00:00"
  }
}

6 items

commonrequired

commonoptionaltable
distribution
A distribution represents a distribution of sampled values. It is used with services that support global histograms and summaries.
- commonrequired[table]
  samples
  The set of sampled values.
  - commonrequireduint
    rate
    The rate at which this value was sampled.
    - View examples
  - commonrequireduint
    value
    The value being sampled.
- enumcommonrequiredstring
  statistic
  The statistic to be calculated from the values.
  - Syntax: literal
  - Enum, must be one of: "histogram" "summary"
  - View examples
enumcommonrequiredstring
kind
The metric value kind.
- Syntax: literal
- Enum, must be one of: "absolute" "incremental"
- View examples
commonrequiredstring
name
The metric name.
- Syntax: literal
- View examples
commonrequiredstring
namespace
The metric namespace. Depending on the service, this will prepend the name or use native namespacing facilities.
- Syntax: literal
- View examples
commonrequiredtable
tags
The metric tags. Key/value pairs, nesting is not allowed.
- commonoptional*
  *
  Key/value pairs, nesting is not allowed.
commonrequiredtimestamp
timestamp
The metric timestamp; when the metric was created.
- View examples

gauge

{
  "metric" : {
    "gauge" : {
      "value" : 1
    },
    "kind" : "absolute",
    "name" : "memory_available_bytes",
    "namespace" : "host",
    "tags" : {
      "host" : "my.host.com",
      "instance_id" : "abcd1234"
    },
    "timestamp" : "2020-10-10T17:07:36+00:00"
  }
}

6 items

commonrequired

commonoptionaltable
gauge
A gauge represents a point-in-time value that can increase and decrease. Vector's internal gauge type represents changes to that value. Gauges should be used to track fluctuations in values, like current memory or CPU usage.
- commonrequiredfloat
  value
  A specific point-in-time value for the gauge.
  - View examples
enumcommonrequiredstring
kind
The metric value kind.
- Syntax: literal
- Enum, must be one of: "absolute" "incremental"
- View examples
commonrequiredstring
name
The metric name.
- Syntax: literal
- View examples
commonrequiredstring
namespace
The metric namespace. Depending on the service, this will prepend the name or use native namespacing facilities.
- Syntax: literal
- View examples
commonrequiredtable
tags
The metric tags. Key/value pairs, nesting is not allowed.
- commonoptional*
  *
  Key/value pairs, nesting is not allowed.
commonrequiredtimestamp
timestamp
The metric timestamp; when the metric was created.
- View examples

histogram

{
  "metric" : {
    "histogram" : {
      "buckets" : {
        "count" : 1,
        "upper_limit" : null
      },
      "count" : 1,
      "sum" : 1
    },
    "kind" : "absolute",
    "name" : "memory_available_bytes",
    "namespace" : "host",
    "tags" : {
      "host" : "my.host.com",
      "instance_id" : "abcd1234"
    },
    "timestamp" : "2020-10-10T17:07:36+00:00"
  }
}

6 items

commonrequired

commonoptionaltable
histogram
Also called a "timer". A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.
- commonrequired[table]
  buckets
  The set of buckets containing the histogram values.
  - commonrequireduint
    count
    The number of values contained within this bucket.
    - View examples
  - commonrequireduint
    upper_limit
    The upper limit of the samples within the bucket.
- commonrequireduint
  count
  The total number of values contained within the histogram.
  - View examples
- commonrequiredfloat
  sum
  The sum of all values contained within the histogram.
  - View examples
enumcommonrequiredstring
kind
The metric value kind.
- Syntax: literal
- Enum, must be one of: "absolute" "incremental"
- View examples
commonrequiredstring
name
The metric name.
- Syntax: literal
- View examples
commonrequiredstring
namespace
The metric namespace. Depending on the service, this will prepend the name or use native namespacing facilities.
- Syntax: literal
- View examples
commonrequiredtable
tags
The metric tags. Key/value pairs, nesting is not allowed.
- commonoptional*
  *
  Key/value pairs, nesting is not allowed.
commonrequiredtimestamp
timestamp
The metric timestamp; when the metric was created.
- View examples

set

{
  "metric" : {
    "kind" : "absolute",
    "name" : "memory_available_bytes",
    "namespace" : "host",
    "set" : {
      "values" : [
        "value1",
        "value2"
      ]
    },
    "tags" : {
      "host" : "my.host.com",
      "instance_id" : "abcd1234"
    },
    "timestamp" : "2020-10-10T17:07:36+00:00"
  }
}

6 items

commonrequired

enumcommonrequiredstring
kind
The metric value kind.
- Syntax: literal
- Enum, must be one of: "absolute" "incremental"
- View examples
commonrequiredstring
name
The metric name.
- Syntax: literal
- View examples
commonrequiredstring
namespace
The metric namespace. Depending on the service, this will prepend the name or use native namespacing facilities.
- Syntax: literal
- View examples
commonoptionaltable
set
A set represents an array of unique values.
- commonrequired[string]
  values
  The list of unique values.
  - View examples
commonrequiredtable
tags
The metric tags. Key/value pairs, nesting is not allowed.
- commonoptional*
  *
  Key/value pairs, nesting is not allowed.
commonrequiredtimestamp
timestamp
The metric timestamp; when the metric was created.
- View examples

summary

{
  "metric" : {
    "kind" : "absolute",
    "name" : "memory_available_bytes",
    "namespace" : "host",
    "summary" : {
      "count" : 54,
      "quantiles" : {
        "upper_limit" : null,
        "value" : null
      },
      "sum" : 1
    },
    "tags" : {
      "host" : "my.host.com",
      "instance_id" : "abcd1234"
    },
    "timestamp" : "2020-10-10T17:07:36+00:00"
  }
}

6 items

commonrequired

enumcommonrequiredstring
kind
The metric value kind.
- Syntax: literal
- Enum, must be one of: "absolute" "incremental"
- View examples
commonrequiredstring
name
The metric name.
- Syntax: literal
- View examples
commonrequiredstring
namespace
The metric namespace. Depending on the service, this will prepend the name or use native namespacing facilities.
- Syntax: literal
- View examples
commonoptionaltable
summary
Similar to a histogram, a summary samples observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable quantiles over a sliding time window.
- commonrequireduint
  count
  The total number of values contained within the summary.
  - View examples
- commonrequired[table]
  quantiles
  The set of observations.
  - commonrequireduint
    upper_limit
    The upper limit for this quantile range, where 0 ≤ upper_limit ≤ 1.
  - commonrequireduint
    value
    The value of this quantile range.
- commonrequiredfloat
  sum
  The sum of all values contained within the histogram.
  - View examples
commonrequiredtable
tags
The metric tags. Key/value pairs, nesting is not allowed.
- commonoptional*
  *
  Key/value pairs, nesting is not allowed.
commonrequiredtimestamp
timestamp
The metric timestamp; when the metric was created.
- View examples

Components

View all metric-compatible components

How it works

Global histograms and distributions

Some services, namely Datadog, support distributions. Distributions represent a distribution of sampled values and global statisctics are computed downstream by the service. This strategy enables global histograms avoiding the need to guess and determine buckets beforehand.

Dogstatsd

Vector supports the Dogstatsd variant of Statsd, enabling the use of distributions through Statsd.

Interoperability

Metrics are first-class citizens in Vector, they are not represented as structured logs. Therefore, metrics in Vector are fully interoperable betwee disparate metrics services. For example, Vector can ingest metrics from Statsd and output them to Prometheus without any special configuration.

Namespaces

Metric namespaces in Vector are treated separately from the metric name. This allows you to easily change namespaces at the source and sink level and it ensures Vector can map namespaces properly to different metrics services. Some metrics services require the namespace to be prepended to the metric name, while others requier namespaces to be separate.

Tags, labels, & high-cardinality

Metrics tags, also known as labels, allows you to augment metrics with context. Tags are key/value pairs that cannot be nested. A caveat with tags is using high-cardinality labels. You should avoid using high-cardinality labels whenever possible. Vector provides a tag_cardinality_limi transform to protect against the accidental use of high-cardinality values.

#Description

#Schema

#counter

#counter

#value

#kind

#name

#namespace

#tags

*

#timestamp

#distribution

#distribution

#samples

#rate

#value

#statistic

#kind

#name

#namespace

#tags

#*

#timestamp

#gauge

#gauge

#value

#kind

#name

#namespace

#tags

#*

#timestamp

#histogram

#histogram

#buckets

#count

#upper_limit

#count

#sum

#kind

#name

#namespace

#tags

#*

#timestamp

#set

#kind

#name

#namespace

#set

#values

#tags

#*

#timestamp

#summary

#kind

#name

#namespace

#summary

#count

#quantiles

#upper_limit

#value

#sum

#tags

#*

#timestamp

#Components

#How it works

#Global histograms and distributions

#Dogstatsd

#Interoperability

#Namespaces

#Tags, labels, & high-cardinality

Description

Schema

counter

counter

value

kind

name

namespace

tags

timestamp

distribution

distribution

samples

rate

value

statistic

kind

name

namespace

tags

*

timestamp

gauge

gauge

value

kind

name

namespace

tags

*

timestamp

histogram

histogram

buckets

count

upper_limit

count

sum

kind

name

namespace

tags

*

timestamp

set

kind

name

namespace

set

values

tags

*

timestamp

summary

kind

name

namespace

summary

count

quantiles

upper_limit

value

sum

tags

*

timestamp

Components

How it works

Global histograms and distributions

Dogstatsd

Interoperability

Namespaces

Tags, labels, & high-cardinality