View Source StatsdMetric (statsd_metric v1.0.0)

A fast StatsD / DogStatsD metric encoder and single-pass parser.

StatsdMetric supports all standard StatsD metric types:

  • Counter
  • Gauge
  • Histogram
  • Timer
  • Set
  • Meter

It also supports DogStatsD sample rates and tags.

Encoding Example

iex> metric = %StatsdMetric{key: "name.spaced", value: 1.0, type: :counter}
iex> StatsdMetric.encode(metric)
["name.spaced", 58, "1.0", 124, "c"]

iex> metric = %StatsdMetric{key: "name.spaced", value: 1.0, type: :counter}
iex> StatsdMetric.encode_to_string(metric)
"name.spaced:1.0|c"

Directly encoding stat parameters is also supported:

iex> StatsdMetric.encode_parts("name.spaced", 1.0, :counter)
["name.spaced", 58, "1.0", 124, "c"]

iex> StatsdMetric.encode_parts_to_string("name.spaced", 1.0, :counter)
"name.spaced:1.0|c"

Parsing Example

iex> StatsdMetric.decode!("name.spaced:1.0|c|@0.1|#foo:bar")
[%StatsdMetric{
  key: "name.spaced",
  value: 1.0,
  type: :counter,
  sample_rate: 0.1,
  tags: %{"foo" => "bar"}
}]

Multiple metrics separated by a newline are also supported:

iex> StatsdMetric.decode!("first.metric:1.0|c|@0.1|#foo:bar\nsecond.metric:15.0|g|#foo:bar")
[
  %StatsdMetric{
    key: "first.metric",
    value: 1.0,
    type: :counter,
    sample_rate: 0.1,
    tags: %{"foo" => "bar"}
  },
  %StatsdMetric{
    key: "second.metric",
    value: 15.0,
    type: :gauge,
    tags: %{"foo" => "bar"}
  }
]

Summary

Functions

Parses StatsD metrics into a list of %StatsdMetric{}.

Parses StatsD metrics into a list of %StatsdMetric{}.

Encodes a %StatsdMetric{} into a StatsD metric IO list.

Encodes stat parameters into a StatsD metric IO list.

Encodes stat parameters into a StatsD metric string.

Encodes a %StatsdMetric{} into a StatsD metric string.

Types

@type t() :: %StatsdMetric{
  key: String.t(),
  sample_rate: float() | nil,
  tags: map() | nil,
  type: atom(),
  value: float()
}

Functions

@spec decode(binary()) ::
  {:ok,
   [
     %StatsdMetric{
       key: term(),
       sample_rate: term(),
       tags: term(),
       type: term(),
       value: term()
     }
   ]}
  | {:error, atom()}

Parses StatsD metrics into a list of %StatsdMetric{}.

iex> StatsdMetric.decode("name.spaced:1.0|c|@0.1|#foo:bar")
{:ok, [%StatsdMetric{
  key: "name.spaced",
  value: 1.0,
  type: :counter,
  sample_rate: 0.1,
  tags: %{"foo" => "bar"}
}]}
@spec decode!(binary()) :: [
  %StatsdMetric{
    key: term(),
    sample_rate: term(),
    tags: term(),
    type: term(),
    value: term()
  }
]

Parses StatsD metrics into a list of %StatsdMetric{}.

iex> StatsdMetric.decode!("name.spaced:1.0|c|@0.1|#foo:bar")
[%StatsdMetric{
  key: "name.spaced",
  value: 1.0,
  type: :counter,
  sample_rate: 0.1,
  tags: %{"foo" => "bar"}
}]

If any of the metrics are invalid, it raises one of:

@spec encode(t()) :: iolist()

Encodes a %StatsdMetric{} into a StatsD metric IO list.

iex> StatsdMetric.encode(%StatsdMetric{key: "name.spaced", value: 1.0, type: :counter})
["name.spaced", 58, "1.0", 124, "c"]
Link to this function

encode_parts(key, val, type, opts \\ [])

View Source
@spec encode_parts(binary(), integer() | float(), atom(), keyword()) :: iolist()

Encodes stat parameters into a StatsD metric IO list.

iex> StatsdMetric.encode_parts("name.spaced", 1.0, :counter)
["name.spaced", 58, "1.0", 124, "c"]
Link to this function

encode_parts_to_string(key, val, type, opts \\ [])

View Source
@spec encode_parts_to_string(binary(), integer() | float(), atom(), keyword()) ::
  binary()

Encodes stat parameters into a StatsD metric string.

iex> StatsdMetric.encode_parts_to_string("name.spaced", 1.0, :counter)
"name.spaced:1.0|c"
Link to this function

encode_to_string(metric)

View Source
@spec encode_to_string(t()) :: binary()

Encodes a %StatsdMetric{} into a StatsD metric string.

iex> StatsdMetric.encode_to_string(%StatsdMetric{key: "name.spaced", value: 1.0, type: :counter})
"name.spaced:1.0|c"