Skip to content

Module: HTM::Telemetry

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 [] for full implementation details

@example 

HTM.configure do |config|
  config.telemetry_enabled = true
end
@example 
# Export to OTLP endpoint
ENV['OTEL_METRICS_EXPORTER'] = 'otlp'
ENV['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318'

Class Methods

cache_operations()

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

@example 

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

embedding_latency()

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

@example 

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 

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 [OpenTelemetry::Metrics::Histogram, NullInstrument] The histogram to record to

@param [Hash] Attributes to attach to the measurement

@return [Object] The result of the block

@yield [] The block to measure

@example 

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 

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 

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