Skip to content

Module HTM::Telemetry

Defined in lib/htm/telemetry.rb

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.

  • @see notes/ot.md for full implementation details

@example Enable telemetry 

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

@example Set destination via environment 

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

Public Class Methods

cache_operations()

Counter for cache operations (hits, misses) - @return [OpenTelemetry::Metrics::Counter, NullInstrument]

@example Record a cache hit 

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

embedding_latency()

Histogram for embedding generation latency - @return [OpenTelemetry::Metrics::Histogram, NullInstrument]

@example Record latency 

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

enabled?()

Check if telemetry is enabled and SDK is available - @return [Boolean] true if telemetry should be active

job_counter()

Counter for job execution (enqueued, completed, failed) - @return [OpenTelemetry::Metrics::Counter, NullInstrument]

@example Record a completed job 

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

measure(histogram, attributes = {})

Measure execution time of a block and record to a histogram - @param histogram [OpenTelemetry::Metrics::Histogram, NullInstrument] The histogram to record to - @param attributes [Hash] Attributes to attach to the measurement - @return [Object] The result of the block - @yield The block to measure

@example Measure embedding generation 

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

meter()

Get the meter for creating instruments - @return [OpenTelemetry::Metrics::Meter, NullMeter] Real or null meter

reset!()

Reset telemetry state (for testing) - @return [void]

sdk_available?()

Check if OpenTelemetry SDK is installed - @return [Boolean] true if SDK can be loaded

search_latency()

Histogram for search operation latency - @return [OpenTelemetry::Metrics::Histogram, NullInstrument]

@example Record latency 

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

setup()

Initialize OpenTelemetry SDK

Called automatically when telemetry is enabled. Safe to call multiple times. - @return [void]

tag_latency()

Histogram for tag extraction latency - @return [OpenTelemetry::Metrics::Histogram, NullInstrument]

@example Record latency 

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