Class: Harnex::ContextTelemetry

Inherits:
Object
  • Object
show all
Defined in:
lib/harnex/context_telemetry.rb

Overview

Bounded in-memory aggregate for active context-window samples.

It retains only the final valid occupancy sample, independent high-water marks, and counters that make unavailable samples visible without storing raw protocol payloads.

Constant Summary collapse

MEASUREMENT_STATUSES = 
%w[observed estimated].freeze

Instance Method Summary collapse

Constructor Details

#initialize(status:, source:) ⇒ ContextTelemetry

Returns a new instance of ContextTelemetry.



10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/harnex/context_telemetry.rb', line 10

def initialize(status:, source:)
  measurement_status = status.to_s
  unless MEASUREMENT_STATUSES.include?(measurement_status)
    raise ArgumentError, "context telemetry status must be observed or estimated"
  end

  @measurement_status = measurement_status
  @source = source.to_s.empty? ? nil : source.to_s
  @terminal_tokens = nil
  @window_tokens = nil
  @terminal_percent = nil
  @peak_tokens = nil
  @peak_percent = nil
  @samples = 0
  @missing_samples = 0
  @latest_sample_status = nil
  @valid_sample_seen = false
end

Instance Method Details

#record(tokens:, window_tokens:, percent: nil) ⇒ Object 



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'lib/harnex/context_telemetry.rb', line 29

def record(tokens:, window_tokens:, percent: nil)
  @samples += 1
  token_count = nonnegative_integer(tokens)
  window_size = positive_integer(window_tokens)
  pressure_percent = nonnegative_float(percent)
  pressure_percent ||= derived_percent(token_count, window_size)

  if token_count.nil?
    @missing_samples += 1
    @latest_sample_status = "missing"
    return snapshot
  end

  @valid_sample_seen = true
  @terminal_tokens = token_count
  @window_tokens = window_size
  @terminal_percent = pressure_percent
  @peak_tokens = [@peak_tokens, token_count].compact.max
  @peak_percent = [@peak_percent, pressure_percent].compact.max
  @latest_sample_status = @measurement_status
  snapshot
end

#snapshot ⇒ Object 



52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/harnex/context_telemetry.rb', line 52

def snapshot
  {
    status: @valid_sample_seen ? @measurement_status : "missing",
    source: @source,
    terminal_tokens: @terminal_tokens,
    window_tokens: @window_tokens,
    terminal_percent: @terminal_percent,
    peak_tokens: @peak_tokens,
    peak_percent: @peak_percent,
    samples: @samples,
    missing_samples: @missing_samples,
    latest_sample_status: @latest_sample_status
  }
end