Class: DilisensePepClient::Metrics

Inherits:
Object
  • Object
show all
Defined in:
lib/dilisense_pep_client/metrics.rb

Overview

Comprehensive metrics collection and monitoring system for FinTech operations

This class provides enterprise-grade metrics collection specifically designed for financial services applications that require detailed operational monitoring, performance tracking, and regulatory compliance reporting.

The metrics system supports four fundamental metric types:

  • Counters: Ever-increasing values (e.g., total requests, errors)

  • Gauges: Values that can increase or decrease (e.g., active connections, memory usage)

  • Histograms: Distribution of values over time (e.g., response times, request sizes)

  • Timers: Specialized histograms for measuring operation duration

Features:

  • Thread-safe concurrent operations using concurrent-ruby

  • FinTech-specific metric categories (screening, compliance, security)

  • Business metrics for PEP screening operations

  • Prometheus export format for monitoring integration

  • Memory-efficient histogram storage with automatic value rotation

  • Comprehensive tagging system for metric dimensions

  • Built-in percentile calculations (P50, P95, P99)

  • Security and compliance event tracking

  • Circuit breaker metrics integration

Examples:

Basic counter usage

metrics = Metrics.new
metrics.increment_counter("api_requests", tags: { endpoint: "/v1/check" })

Timing operations

result = metrics.time_operation("database_query") do
  database.execute_query(sql)
end

Recording screening events

metrics.record_screening_request(
  type: "individual",
  search_terms_count: 2,
  user_id: "user123"
)

Constant Summary collapse

METRIC_TYPES =

Standard metric types supported by the system Each type has specific behaviors and use cases for monitoring

{
  counter: :counter,        # Monotonically increasing values
  gauge: :gauge,           # Values that can increase or decrease
  histogram: :histogram,   # Distribution of values with percentiles
  timer: :timer           # Specialized histogram for timing operations
}.freeze
CATEGORIES =

FinTech-specific metric categories for organized monitoring Each category groups related metrics for easier analysis and alerting

{
  screening: "screening",      # PEP/sanctions screening operations
  performance: "performance",  # Response times, throughput, resource usage
  security: "security",       # Authentication, authorization, security events
  compliance: "compliance",   # Regulatory compliance, audit events
  reliability: "reliability", # Circuit breakers, failures, retries
  business: "business"        # Business KPIs, user activity, revenue metrics
}.freeze

Instance Method Summary collapse

Constructor Details

#initialize(service_name: "dilisense_pep_client") ⇒ Metrics

Initialize a new metrics collection instance

Parameters:

  • service_name (String) (defaults to: "dilisense_pep_client") —

    Name of the service for metric prefixing (default: “dilisense_pep_client”)



68
69
70
71
72
73
 
# File 'lib/dilisense_pep_client/metrics.rb', line 68

def initialize(service_name: "dilisense_pep_client")
  @service_name = service_name
  @metrics = Concurrent::Map.new  # Thread-safe metric storage
  @start_time = Time.now  # Track service uptime
  @mutex = Mutex.new  # Synchronize metric creation operations
end

Instance Method Details

#decrement_counter(name, value: 1, tags: {}, category: :screening) ⇒ Object 



97
98
99
 
# File 'lib/dilisense_pep_client/metrics.rb', line 97

def decrement_counter(name, value: 1, tags: {}, category: :screening)
  increment_counter(name, value: -value, tags: tags, category: category)
end

#decrement_gauge(name, value: 1, tags: {}, category: :performance) ⇒ Object 



121
122
123
 
# File 'lib/dilisense_pep_client/metrics.rb', line 121

def decrement_gauge(name, value: 1, tags: {}, category: :performance)
  increment_gauge(name, value: -value, tags: tags, category: category)
end

#export_prometheus_format ⇒ Object 



325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
 
# File 'lib/dilisense_pep_client/metrics.rb', line 325

def export_prometheus_format
  output = []
  
  @metrics.each do |name, metric|
    case metric[:type]
    when :counter
      output << "# TYPE #{name} counter"
      output << format_prometheus_line(name, metric[:value].value, metric[:tags])
    when :gauge
      output << "# TYPE #{name} gauge"
      output << format_prometheus_line(name, metric[:value].value, metric[:tags])
    when :histogram
      output << "# TYPE #{name} histogram"
      histogram_data = metric[:histogram_data]
      tags = metric[:tags]
      
      output << format_prometheus_line("#{name}_count", histogram_data[:count].value, tags)
      output << format_prometheus_line("#{name}_sum", histogram_data[:sum].value, tags)
      
      [0.5, 0.95, 0.99].each do |quantile|
        percentile_tags = tags.merge(quantile: quantile)
        output << format_prometheus_line("#{name}_quantile", calculate_percentile(metric, quantile), percentile_tags)
      end
    end
  end
  
  output.join("\n")
end

#get_all_metrics(category: nil) ⇒ Object 



297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/dilisense_pep_client/metrics.rb', line 297

def get_all_metrics(category: nil)
  metrics_data = {}
  
  @metrics.each do |name, metric|
    next if category && !name.include?(CATEGORIES[category])
    
    metrics_data[name] = get_metric(name)
  end
  
  metrics_data
end

#get_metric(name, category: nil) ⇒ Object

Retrieve metrics data



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/dilisense_pep_client/metrics.rb', line 263

def get_metric(name, category: nil)
  metric_name = category ? build_metric_name(name, category) : name
  metric = @metrics[metric_name]
  
  return nil unless metric
  
  case metric[:type]
  when :counter, :gauge
    {
      name: metric_name,
      type: metric[:type],
      value: metric[:value].value,
      tags: metric[:tags],
      last_updated: metric[:last_updated]
    }
  when :histogram
    histogram_data = metric[:histogram_data]
    {
      name: metric_name,
      type: metric[:type],
      count: histogram_data[:count].value,
      sum: histogram_data[:sum].value,
      mean: calculate_mean(metric),
      min: metric[:min],
      max: metric[:max],
      p50: calculate_percentile(metric, 0.5),
      p95: calculate_percentile(metric, 0.95),
      p99: calculate_percentile(metric, 0.99),
      tags: metric[:tags],
      last_updated: metric[:last_updated]
    }
  end
end

#get_summary ⇒ Object 



309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/dilisense_pep_client/metrics.rb', line 309

def get_summary
  {
    service_name: @service_name,
    uptime_seconds: Time.now - @start_time,
    total_metrics: @metrics.size,
    categories: get_metrics_by_category,
    last_updated: @metrics.values.map { |m| m[:last_updated] }.max,
    system_info: {
      ruby_version: RUBY_VERSION,
      platform: RUBY_PLATFORM,
      process_id: Process.pid,
      memory_usage: get_memory_usage
    }
  }
end

#increment_counter(name, value: 1, tags: {}, category: :screening) ⇒ Object

Increment a counter metric by specified value Counter metrics track monotonically increasing values like total requests, errors, or events

Examples:

Track API requests

increment_counter("api_requests", tags: { endpoint: "/v1/check", method: "POST" })

Track errors with multiple increments

increment_counter("errors_total", value: 5, category: :reliability)

Parameters:

  • name (String, Symbol) —

    Name of the counter metric

  • value (Integer) (defaults to: 1) —

    Value to increment by (default: 1)

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

    Tag dimensions for the metric (e.g., { endpoint: “/api/v1” })

  • category (Symbol) (defaults to: :screening) —

    Metric category for organization (default: :screening)



88
89
90
91
92
93
94
95
 
# File 'lib/dilisense_pep_client/metrics.rb', line 88

def increment_counter(name, value: 1, tags: {}, category: :screening)
  metric_name = build_metric_name(name, category)
  metric = get_or_create_metric(metric_name, :counter, tags)
  metric[:value].add(value)  # Thread-safe atomic increment
  metric[:last_updated] = Time.now

  log_metric_update(:counter, metric_name, value, tags)
end

#increment_gauge(name, value: 1, tags: {}, category: :performance) ⇒ Object 



111
112
113
114
115
116
117
118
119
 
# File 'lib/dilisense_pep_client/metrics.rb', line 111

def increment_gauge(name, value: 1, tags: {}, category: :performance)
  metric_name = build_metric_name(name, category)
  metric = get_or_create_metric(metric_name, :gauge, tags)
  new_value = metric[:value].increment(value)
  metric[:last_updated] = Time.now

  log_metric_update(:gauge, metric_name, new_value, tags)
  new_value
end

#record_api_call(endpoint:, status_code:, duration_ms:, response_size: nil) ⇒ Object 



204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/dilisense_pep_client/metrics.rb', line 204

def record_api_call(endpoint:, status_code:, duration_ms:, response_size: nil)
  tags = { 
    endpoint: endpoint,
    status_code: status_code,
    status_class: "#{status_code.to_s[0]}xx"
  }
  
  increment_counter("api_requests_total", tags: tags, category: :performance)
  record_histogram("api_duration_ms", duration_ms, tags: tags, category: :performance)
  
  if response_size
    record_histogram("api_response_size_bytes", response_size, tags: tags, category: :performance)
  end
  
  if status_code >= 400
    increment_counter("api_errors_total", tags: tags, category: :reliability)
  end
end

#record_circuit_breaker_event(service:, state:, failure_count: 0) ⇒ Object 



251
252
253
254
255
256
257
258
259
260
 
# File 'lib/dilisense_pep_client/metrics.rb', line 251

def record_circuit_breaker_event(service:, state:, failure_count: 0)
  tags = { service: service, state: state }
  
  increment_counter("circuit_breaker_events_total", tags: tags, category: :reliability)
  set_gauge("circuit_breaker_failure_count", failure_count, tags: tags, category: :reliability)
  
  if state == "open"
    increment_counter("circuit_breaker_trips_total", tags: tags, category: :reliability)
  end
end

#record_compliance_event(framework:, event_type:, status:) ⇒ Object 



237
238
239
240
241
242
243
244
245
246
247
248
249
 
# File 'lib/dilisense_pep_client/metrics.rb', line 237

def record_compliance_event(framework:, event_type:, status:)
  tags = { 
    framework: framework,
    event_type: event_type,
    status: status
  }
  
  increment_counter("compliance_events_total", tags: tags, category: :compliance)
  
  if status == "violation"
    increment_counter("compliance_violations_total", tags: tags, category: :compliance)
  end
end

#record_histogram(name, value, tags: {}, category: :performance) ⇒ Object

Histogram metrics - distribution of values



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/dilisense_pep_client/metrics.rb', line 126

def record_histogram(name, value, tags: {}, category: :performance)
  metric_name = build_metric_name(name, category)
  metric = get_or_create_metric(metric_name, :histogram, tags)
  
  histogram_data = metric[:histogram_data]
  histogram_data[:count].increment
  histogram_data[:sum].add(value)
  histogram_data[:values] << value
  
  # Keep only last 1000 values to prevent memory issues
  if histogram_data[:values].size > 1000
    histogram_data[:values].shift(histogram_data[:values].size - 1000)
  end
  
  metric[:last_updated] = Time.now
  update_histogram_stats(metric, value)

  log_metric_update(:histogram, metric_name, value, tags)
end

#record_screening_request(type:, search_terms_count: 1, user_id: nil) ⇒ Object

Business metrics specific to PEP screening



167
168
169
170
171
172
173
174
175
176
 
# File 'lib/dilisense_pep_client/metrics.rb', line 167

def record_screening_request(type:, search_terms_count: 1, user_id: nil)
  tags = { 
    screening_type: type, 
    terms_count: search_terms_count,
    user_id: user_id ? "present" : "absent"
  }
  
  increment_counter("screening_requests_total", tags: tags, category: :business)
  set_gauge("active_screening_sessions", get_active_sessions_count, category: :business)
end

#record_screening_response(type:, records_found:, processing_time_ms:, data_sources: [], cache_hit: false) ⇒ Object 



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/dilisense_pep_client/metrics.rb', line 178

def record_screening_response(
  type:, 
  records_found:, 
  processing_time_ms:, 
  data_sources: [], 
  cache_hit: false
)
  tags = { 
    screening_type: type,
    records_found: records_found > 0 ? "found" : "none",
    cache_status: cache_hit ? "hit" : "miss"
  }
  
  increment_counter("screening_responses_total", tags: tags, category: :business)
  record_histogram("screening_processing_time_ms", processing_time_ms, tags: tags, category: :performance)
  
  if records_found > 0
    record_histogram("screening_records_found", records_found, tags: tags, category: :business)
    increment_counter("potential_matches_total", value: records_found, tags: tags, category: :compliance)
  end
  
  data_sources.each do |source|
    increment_counter("data_source_usage_total", tags: tags.merge(source: source), category: :business)
  end
end

#record_security_event(event_type:, severity:, user_id: nil) ⇒ Object 



223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/dilisense_pep_client/metrics.rb', line 223

def record_security_event(event_type:, severity:, user_id: nil)
  tags = { 
    event_type: event_type,
    severity: severity,
    user_present: user_id ? "yes" : "no"
  }
  
  increment_counter("security_events_total", tags: tags, category: :security)
  
  if severity == :critical
    increment_counter("critical_security_events_total", tags: tags, category: :security)
  end
end

#reset_metric(name, category: nil) ⇒ Object 



361
362
363
364
 
# File 'lib/dilisense_pep_client/metrics.rb', line 361

def reset_metric(name, category: nil)
  metric_name = category ? build_metric_name(name, category) : name
  @metrics.delete(metric_name)
end

#reset_metrics! ⇒ Object 



354
355
356
357
358
359
 
# File 'lib/dilisense_pep_client/metrics.rb', line 354

def reset_metrics!
  @mutex.synchronize do
    @metrics.clear
    Logger.logger.info("Metrics reset", service_name: @service_name)
  end
end

#set_gauge(name, value, tags: {}, category: :performance) ⇒ Object

Gauge metrics - values that can go up or down



102
103
104
105
106
107
108
109
 
# File 'lib/dilisense_pep_client/metrics.rb', line 102

def set_gauge(name, value, tags: {}, category: :performance)
  metric_name = build_metric_name(name, category)
  metric = get_or_create_metric(metric_name, :gauge, tags)
  metric[:value].value = value
  metric[:last_updated] = Time.now

  log_metric_update(:gauge, metric_name, value, tags)
end

#time_operation(name, tags: {}, category: :performance, &block) ⇒ Object

Timer metrics - measure duration of operations



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/dilisense_pep_client/metrics.rb', line 147

def time_operation(name, tags: {}, category: :performance, &block)
  start_time = Time.now
  
  begin
    result = block.call
    duration = (Time.now - start_time) * 1000 # Convert to milliseconds
    record_histogram("#{name}_duration_ms", duration, tags: tags, category: category)
    increment_counter("#{name}_success_total", tags: tags, category: category)
    
    result
  rescue => error
    duration = (Time.now - start_time) * 1000
    record_histogram("#{name}_duration_ms", duration, tags: tags.merge(status: "error"), category: category)
    increment_counter("#{name}_error_total", tags: tags.merge(error_type: error.class.name), category: category)
    
    raise
  end
end