Gauges

In a car, you can see multiple Gauges. Fuel, speed, engine temperature, distance covered, … etc. All those values represent a state in the car, not an event that happened and finished.

For example, cars have a sensor for the doors to inform the driver if all doors are closed or any of them is open. Pulling the door knob, or moving the door slightly to open it more or close it a little don’t affect the sensor. Those are events that affect the state of the door, the events themselves started and ended, but the state of the door remains until another event happens.

The state is represented by Gauges, the events that affected the Gauge value are different and you’ll cover those in the next lesson.

In the very first lesson, you’ve set a gauge that had the value of the count of objects in the TheMetStore. Every time you perform a search with a different keyword, the gauge value will change. If you stop searching, the gauge value will stay to the last value given to it, and it will keep updating Grafana with this value as long as the app is running.

This graph on Grafana shows the state of the gauge over a 10 mins duration. It doesn’t mean there are 10 values. It doesn’t inform you how many times a search is performed.

Here are some examples and notes about how gauges should be used:

• A gauge can represent the memory usage of an app or the number of online users.
• Gauges are meant to be on the application level not on a feature level.
• If you use it to count how many items are displayed on a screen, then the user closed the screen and went to another on the app, your gauge will be confusing and will still be transmitting the last value on your dashboard which will give you false info.
• Setting it to zero is also incorrect since it would mean the screen is not showing any items, not that the screen is closed.

It’s important to understand how a metric works to be able to correctly understand the data it represents.

This is how you create a gauge in OpenTelemetry:

let openTelemetry = OpenTelemetry.instance // 1
    
let meter = openTelemetry.meterProvider.meterBuilder(name: "NAME_OF_METRICS_GROUP").build() // 2

var gauge = meter.gaugeBuilder(name: "NAME_OF_THE_GAUGE").build()  // 3

gauge.record(value: 5.0)  // 4

1. First you get the instance of OpenTelemetry
2. Create a meter with a name to represent the metrics group. This string is to help you organize your dashboards and metrics you’re collecting as you can have a large number of metrics from different apps and systems.
3. Create a gauge through its builder by providing a name for that gauge.
4. Finally, you record the value.

Recording a different value to a new gauge with the same GroupName and GaugeName will overwrite the old value, even if its a different instance.