This change enables setting min and max values for gauges. It prevent…

[prinzdezibel]

…s the gauge's value to become smaller/greater than the specified limits. The values are optional and don't change the gauge's behaviour if not given.

Example use case:
A log stream increases or decreases a user session gauge if a corresponding login/logoff log entry is seen. Specifying a minimum value of 0 for the gauge helps to prevent the user session gauge to go negative in case that the very first message that triggers the gauge is a logoff message. This might happen without the proposed changes if the user is already logged in and the prometheus service is restarted, because it resets the gauge values to 0.

[prinzdezibel]

I tried to find another solution for my use case, but couldn't find another way to solve it. But because my use case (counting in/off messages in a log stream to get the active sessions of a user) is so common, I think I might have overlooked something obvious. I would be interested in any advice, in case this is not the best way to solve the problem at hand.

@ArthurSens, @bwplotka, @kakkoyun, @vesari : I need your guidance in this matter. I'm aware that this PR is not completed yet, it misses tests and also documentation. But before doing that I'd like to get your thoughts on it, because I'm not sure my approach to the problem is the way to go...

As I described above, my use case is a gauge that can decrease and increase. But I don't want to have the gauge go negative (in my specific case), because that would indicate a logical error. Therefore I have added a min_value (and also a max_value) to the gauge.

Here is an alloy script that counts active VPN sessions whenever a specific pattern is encountered in the log stream:

loki.process "metric_vpn_sessions" {

    stage.regex {
       expression          = `sessiond\[\d+\]: msg_id="3E00-000(2|4)" (IPSec|SSL) VPN user (?<user>[^@]+)@(?<host>[^\s]+) from (?<external_ip>([0-9]{1,3}\.){3}[0-9]{1,3}) logged (?<state>in|out) assigned virtual IP is (?<internal_ip>([0-9]{1,3}\.){3}[0-9]{1,3})`
       labels_from_groups  = true
    }

    stage.template {
      source   = "delta"
      template = "{{ if eq .state \"in\" }}1{{ else }}-1{{ end }}"
    }

    stage.match {
      selector = `{ state =~ "(in|out)" }`
     
      stage.label_drop { values = [
        "state",
        "external_ip",
        "internal_ip",
       ] }

      stage.metrics {
        metric.gauge {
          name              = "vpn_sessions"
          action            = "add"
          max_idle_duration = "24h"
          min_value         = "0"
          source            = "delta"
        }
      }
    }

   
    forward_to = [loki.write.local.receiver]
}

This works and does what I want thanks to the newly introduced min_value. But I'm wondering how others handle this use case?

I appreciate your thoughts. Thank you.

[bwplotka]

Hi! Thanks for proposing!

So do I understand this right, that you want to ensure some gauge boundaries, for easier later query use, because implementing reliable sub/add operation is not possible (e.g. using log -> metric). First of all minimum 0 gets you away from this case of startup and log-off case, but what if you have 10x log-in and 10x old session log-offs? Then no minimum/max feature would help you and you have an inaccurate metric anyway?

Generally we can argue or not how useful this feature is for general client_golang audience, but the best way is to add a tiny coding wrapper on top of client_golang Set/Add/Sub gauge methods and implement quickly on your code. Why do we need this for general audience at this point? (:

Or... are you rather looking for solution for your instrumentation problem on stateful data (sessions) using stateless mechanisms (on-line log parsing/recording)? In this case Slack, prometheus user group or Loki user group might be a better choice.