Module: HTM::Telemetry

Defined in:
lib/htm/telemetry.rb

Overview

OpenTelemetry-based observability for HTM

Provides opt-in metrics collection with zero overhead when disabled. Uses the null object pattern - when telemetry is disabled or the SDK is not available, all metric operations are no-ops.

Examples:

Enable telemetry

HTM.configure do |config|
  config.telemetry_enabled = true
end

Set destination via environment

# Export to OTLP endpoint
ENV['OTEL_METRICS_EXPORTER'] = 'otlp'
ENV['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318'

See Also:

  • for full implementation details

Defined Under Namespace

Classes: NullInstrument, NullMeter

Class Method Summary collapse

Class Method Details

.cache_operations ⇒ OpenTelemetry::Metrics::Counter, NullInstrument

Counter for cache operations (hits, misses)

Examples:

Record a cache hit

Telemetry.cache_operations.add(1, attributes: { 'operation' => 'hit' })

Returns:



191
192
193
194
195
196
197
 
# File 'lib/htm/telemetry.rb', line 191

def cache_operations
  @cache_operations ||= meter.create_counter(
    'htm.cache.operations',
    unit: 'count',
    description: 'Cache hit/miss counts'
  )
end

.embedding_latency ⇒ OpenTelemetry::Metrics::Histogram, NullInstrument

Histogram for embedding generation latency

Examples:

Record latency

Telemetry.embedding_latency.record(145, attributes: { 'provider' => 'ollama', 'status' => 'success' })

Returns:



146
147
148
149
150
151
152
 
# File 'lib/htm/telemetry.rb', line 146

def embedding_latency
  @embedding_latency ||= meter.create_histogram(
    'htm.embedding.latency',
    unit: 'ms',
    description: 'Embedding generation latency in milliseconds'
  )
end

.enabled? ⇒ Boolean

Check if telemetry is enabled and SDK is available

Returns:

  • (Boolean) —

    true if telemetry should be active



56
57
58
 
# File 'lib/htm/telemetry.rb', line 56

def enabled?
  HTM.configuration.telemetry_enabled && sdk_available?
end

.job_counter ⇒ OpenTelemetry::Metrics::Counter, NullInstrument

Counter for job execution (enqueued, completed, failed)

Examples:

Record a completed job

Telemetry.job_counter.add(1, attributes: { 'job' => 'embedding', 'status' => 'success' })

Returns:



131
132
133
134
135
136
137
 
# File 'lib/htm/telemetry.rb', line 131

def job_counter
  @job_counter ||= meter.create_counter(
    'htm.jobs',
    unit: 'count',
    description: 'Job execution counts by type and status'
  )
end

.measure(histogram, attributes = {}) { ... } ⇒ Object

Measure execution time of a block and record to a histogram

Examples:

Measure embedding generation

result = Telemetry.measure(Telemetry.embedding_latency, 'provider' => 'ollama') do
  generate_embedding(text)
end

Parameters:

  • histogram (OpenTelemetry::Metrics::Histogram, NullInstrument) —

    The histogram to record to

  • attributes (Hash) (defaults to: {}) —

    Attributes to attach to the measurement

Yields:

  • The block to measure

Returns:

  • (Object) —

    The result of the block



215
216
217
218
219
220
221
 
# File 'lib/htm/telemetry.rb', line 215

def measure(histogram, attributes = {})
  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
  result = yield
  elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
  histogram.record(elapsed_ms, attributes: attributes)
  result
end

.meter ⇒ OpenTelemetry::Metrics::Meter, NullMeter

Get the meter for creating instruments

Returns:

  • (OpenTelemetry::Metrics::Meter, NullMeter) —

    Real or null meter



98
99
100
101
102
103
 
# File 'lib/htm/telemetry.rb', line 98

def meter
  return NullMeter.instance unless enabled?

  setup
  @meter ||= OpenTelemetry.meter_provider.meter('htm')
end

.reset! ⇒ void

This method returns an undefined value.

Reset telemetry state (for testing)



109
110
111
112
113
114
115
116
117
118
 
# File 'lib/htm/telemetry.rb', line 109

def reset!
  @meter = nil
  @job_counter = nil
  @embedding_latency = nil
  @tag_latency = nil
  @search_latency = nil
  @cache_operations = nil
  @setup_complete = false
  # Don't reset @sdk_available - that's a system property
end

.sdk_available? ⇒ Boolean

Check if OpenTelemetry SDK is installed

Returns:

  • (Boolean) —

    true if SDK can be loaded



64
65
66
67
68
69
70
71
72
73
 
# File 'lib/htm/telemetry.rb', line 64

def sdk_available?
  return @sdk_available if defined?(@sdk_available)

  @sdk_available = begin
    require 'opentelemetry-metrics-sdk'
    true
  rescue LoadError
    false
  end
end

.search_latency ⇒ OpenTelemetry::Metrics::Histogram, NullInstrument

Histogram for search operation latency

Examples:

Record latency

Telemetry.search_latency.record(50, attributes: { 'strategy' => 'vector' })

Returns:



176
177
178
179
180
181
182
 
# File 'lib/htm/telemetry.rb', line 176

def search_latency
  @search_latency ||= meter.create_histogram(
    'htm.search.latency',
    unit: 'ms',
    description: 'Search operation latency in milliseconds'
  )
end

.setup ⇒ void

This method returns an undefined value.

Initialize OpenTelemetry SDK

Called automatically when telemetry is enabled. Safe to call multiple times.



82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/htm/telemetry.rb', line 82

def setup
  return unless enabled?
  return if @setup_complete

  OpenTelemetry::SDK.configure do |c|
    c.service_name = 'htm'
  end

  @setup_complete = true
  HTM.logger.info "Telemetry: OpenTelemetry SDK initialized"
end

.tag_latency ⇒ OpenTelemetry::Metrics::Histogram, NullInstrument

Histogram for tag extraction latency

Examples:

Record latency

Telemetry.tag_latency.record(250, attributes: { 'provider' => 'ollama', 'status' => 'success' })

Returns:



161
162
163
164
165
166
167
 
# File 'lib/htm/telemetry.rb', line 161

def tag_latency
  @tag_latency ||= meter.create_histogram(
    'htm.tag.latency',
    unit: 'ms',
    description: 'Tag extraction latency in milliseconds'
  )
end