Pulse (Stats)

PulseClient

Pulse is Envoy Mobile’s stats library, used for capturing client application time series metrics. Currently the following types of metrics are supported: Counter, Gauge, Timer, and Distribution.

Pulse also supports custom tags (cardinality). For each type of the metrics, there are two ways to add custom tags:

1. on metrics creation

2. on metrics reporting

This library (like all of Envoy Mobile) is under active development.

To leverage Pulse, obtain an instance of a PulseClient from an Envoy Mobile Engine (refer to Starting Envoy for building an engine instance), and use it to create an instance of the type of metric you desire. The following code examples show how to create a Counter. Similar approaches can be used to create the rest of the types.

Kotlin example:

pulseClient.counter(Element("foo"), Element("bar"))

Swift example:

pulseClient.counter(elements: ["foo", "bar"])

The counter method from the PulseClient takes a variable number of elements and returns a Counter instance. The elements provided are used to form a dot(.) delimited string that serves as the identifier of the counter. The string formed from the example code above is foo.bar.

Store the instance of the counter, then use it to increment as necessary.

In addition, to attach custom tags on metric creation:

Kotlin example:

pulseClient.counter(
  Element("foo"), Element("bar"),
  tags = TagsBuilder().add("os", "Android").add("app_type", "rider").build()
)

Swift example:

pulseClient.counter(
  elements: ["foo", "bar"],
  tags: TagsBuilder().add(name: "os", value: "Android").add(name: "app_type", value: "rider").build()
)

Counter

A Counter can be incremented by calling the increment() method when applicable.

The count argument of increment is defaulted with a value of 1.

Example:

// Increment the counter by 1
// Kotlin, Swift
counter.increment()

// Increment the counter by 5
// Kotlin
counter.increment(5)

// Increment the counter by 5
// Swift
counter.increment(count: 5)

A Counter can be incremented with custom tags. To be concise, this doc shows examples of attaching custom tagging for Counter on increment. Similar APIs are available for all metrics types to attach tags on metrics reporting.

Example:

// Increment the counter by 5 with tags
// Kotlin
counter.increment(
  tags: TagsBuilder().add("os", "Android").add("app_type", "rider").build(),
  count: 5
)

// Increment the counter by 5 with tags
// Swift
counter.increment(
  tags: TagsBuilder().add(name: "os", value: "Android").add(name: "app_type", value: "rider").build()
  count: 5
)

Gauge

The value of a Gauge can be incremented, decremented, or reassigned.

Example:

// Set the gauge to 5
// Kotlin
gauge.set(5)

// Swift
gauge.set(value: 5)

// Add 5 to the gauge
// Kotlin
gauge.add(5)

// Swift
gauge.add(amount: 5)

// Subtract 5 from the gauge
// Kotlin
gauge.sub(5)

// Swift
gauge.sub(amount: 5)

Timer

Use Timer to track a distribution of time durations. You can view the cumulative stats like quantile data (p50/p90/etc.) and average durations.

Example:

// Add a new duration to the underlying timer distribution
// Kotlin
timer.recordDuration(5)

// Swift
timer.recordDuration(durationMs: 5)

Distribution

Use Distribution to track a distribution of int values. You can view the cumulative stats like quantile data (p50/p90/etc.), sum, and averages.

Example:

// Add a new value to the underlying distribution
// Kotlin
distribution.recordValue(5)

// Swift
distribution.recordValue(value: 5)