Skip to content

Module HTM::Observability

Defined in lib/htm/observability.rb

Observability module for monitoring and metrics collection

Provides comprehensive monitoring of HTM components including: * Connection pool health monitoring with alerts * Query timing and performance metrics * Cache efficiency tracking * Service health checks * Memory usage statistics

@example Basic usage 

stats = HTM::Observability.collect_all
puts stats[:connection_pool][:status]  # => :healthy

@example Connection pool monitoring 

pool_stats = HTM::Observability.connection_pool_stats
if pool_stats[:status] == :exhausted
  logger.error "Connection pool exhausted!"
end

@example Health check 

if HTM::Observability.healthy?
  puts "All systems operational"
else
  puts "Health check failed: #{HTM::Observability.health_check[:issues]}"
end

Constants

POOL_CRITICAL_THRESHOLD

75% utilization triggers warning

POOL_WARNING_THRESHOLD

Connection pool utilization thresholds

Public Class Methods

cache_stats()

Get query cache statistics - @return [Hash, nil] Cache stats or nil if unavailable

circuit_breaker_stats()

Get circuit breaker states for all services - @return [Hash] Circuit breaker states: - :embedding_service - State and failure count - :tag_service - State and failure count

collect_all()

Collect all observability metrics - @return [Hash] Comprehensive metrics including: - :connection_pool - Pool stats with health status - :cache - Query cache hit rates and size - :circuit_breakers - Service circuit breaker states - :query_timings - Recent query performance - :service_timings - Embedding/tag generation times - :memory_usage - System memory stats

connection_pool_stats()

Get connection pool statistics with health status - @return [Hash] Pool statistics including: - :size - Maximum pool size - :connections - Current total connections - :in_use - Connections currently checked out - :available - Connections available for checkout - :utilization - Usage percentage (0.0-1.0) - :status - Health status (:healthy, :warning, :critical, :exhausted) - :wait_timeout - Connection wait timeout (ms)

health_check()

Perform comprehensive health check - @return [Hash] Health check results: - :healthy - Boolean overall health status - :checks - Individual check results - :issues - Array of identified issues

healthy?()

Quick health check - returns boolean - @return [Boolean] true if system is healthy

memory_stats()

Get memory usage statistics - @return [Hash] Memory stats

query_timing_stats()

Get query timing statistics - @return [Hash] Timing statistics including avg, min, max, p95

record_embedding_timing(duration_ms)

Record embedding generation timing - @param duration_ms [Float] Generation duration in milliseconds

record_query_timing(duration_ms, query_type: :unknown)

Record query timing for metrics - @param duration_ms [Float] Query duration in milliseconds - @param query_type [Symbol] Type of query (:vector, :fulltext, :hybrid)

record_tag_timing(duration_ms)

Record tag extraction timing - @param duration_ms [Float] Extraction duration in milliseconds

reset_metrics!()

Clear all collected timing metrics - @return [void]

service_timing_stats()

Get service timing statistics (embedding and tag extraction) - @return [Hash] Timing stats for embedding and tag services