Class: Tasker::Telemetry::MetricTypes::Gauge

Inherits:
Object
  • Object
show all
Defined in:
lib/tasker/telemetry/metric_types.rb

Overview

Gauge represents a metric value that can go up or down

Gauges are thread-safe and support atomic set, increment, and decrement operations. They follow fail-fast principles with explicit validation.

Examples:

Production usage

gauge = Gauge.new('active_connections')
gauge.set(100)                     # Set to specific value
gauge.increment(5)                 # +5 connections
gauge.decrement(2)                 # -2 connections
gauge.value                        # Get current value

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, labels: {}, initial_value: 0) ⇒ Gauge

Initialize a new gauge metric

Raises:

  • (ArgumentError) —

    If name is nil or empty, or initial_value is not numeric



152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/tasker/telemetry/metric_types.rb', line 152

def initialize(name, labels: {}, initial_value: 0)
  raise ArgumentError, 'Metric name cannot be nil or empty' if name.nil? || name.strip.empty?

  unless initial_value.is_a?(Numeric)
    raise ArgumentError,
          "Initial value must be numeric, got: #{initial_value.class}"
  end

  @name = name.to_s.freeze
  @labels = labels.freeze
  @value = Concurrent::AtomicReference.new(initial_value)
  @created_at = Time.current.freeze
end

Instance Attribute Details

#created_at ⇒ Time (readonly) 



144
145
146
 
# File 'lib/tasker/telemetry/metric_types.rb', line 144

def created_at
  @created_at
end

#labels ⇒ Hash (readonly) 



141
142
143
 
# File 'lib/tasker/telemetry/metric_types.rb', line 141

def labels
  @labels
end

#name ⇒ String (readonly) 



138
139
140
 
# File 'lib/tasker/telemetry/metric_types.rb', line 138

def name
  @name
end

Instance Method Details

#decrement(amount = 1) ⇒ Numeric

Decrement the gauge by a specified amount

Raises:

  • (ArgumentError) —

    If amount is not numeric or is negative



197
198
199
200
201
202
203
204
205
 
# File 'lib/tasker/telemetry/metric_types.rb', line 197

def decrement(amount = 1)
  unless amount.is_a?(Numeric)
    raise ArgumentError,
          "Gauge decrement amount must be numeric, got: #{amount.class}"
  end
  raise ArgumentError, "Gauge decrement amount must be positive, got: #{amount}" if amount.negative?

  increment(-amount)
end

#description ⇒ String

Get a description of this metric for debugging



230
231
232
233
 
# File 'lib/tasker/telemetry/metric_types.rb', line 230

def description
  label_str = labels.empty? ? '' : format_labels_for_description(labels)
  "#{name}#{label_str} = #{value} (gauge)"
end

#increment(amount = 1) ⇒ Numeric

Increment the gauge by a specified amount

Raises:

  • (ArgumentError) —

    If amount is not numeric



183
184
185
186
187
188
189
190
 
# File 'lib/tasker/telemetry/metric_types.rb', line 183

def increment(amount = 1)
  unless amount.is_a?(Numeric)
    raise ArgumentError,
          "Gauge increment amount must be numeric, got: #{amount.class}"
  end

  @value.update { |current| current + amount }
end

#set(new_value) ⇒ Numeric

Set the gauge to a specific value

Raises:

  • (ArgumentError) —

    If new_value is not numeric



171
172
173
174
175
176
 
# File 'lib/tasker/telemetry/metric_types.rb', line 171

def set(new_value)
  raise ArgumentError, "Gauge value must be numeric, got: #{new_value.class}" unless new_value.is_a?(Numeric)

  @value.set(new_value)
  new_value
end

#to_h ⇒ Hash

Get a hash representation of this metric



217
218
219
220
221
222
223
224
225
 
# File 'lib/tasker/telemetry/metric_types.rb', line 217

def to_h
  {
    name: name,
    labels: labels,
    value: value,
    type: :gauge,
    created_at: created_at
  }
end

#value ⇒ Numeric

Get the current gauge value (thread-safe read)



210
211
212
 
# File 'lib/tasker/telemetry/metric_types.rb', line 210

def value
  @value.get
end