brainzlab 0.1.36 → 0.1.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4ff0306e7d8fe78a37efbc84090d9ffc65dbfa46f76f5ada564304368a5d218a
4
- data.tar.gz: 79ab8e0b681d14468a6cd24577c3850bd0ce0800d547bc7bb5020ff69cb40054
3
+ metadata.gz: 1a5e45616c86bfb16c81bf506b428a4aca149f71ea9b6888c92329d2738876c2
4
+ data.tar.gz: 335891991652de956d08b83d9d7c64d683059832da2998cbd7a017561a4ec8ff
5
5
  SHA512:
6
- metadata.gz: cdb11db4fd944c0978bedf6e619061269e21c334a036bfb3d5d4b7d3d9c9f50317e87434d8915e5adfefc8d6f2c37f9da3cf75dfefd7776eb1edc6f90ad0b818
7
- data.tar.gz: eecd6d8197389329c70971e93fc9d2cbede53eea1866e181182a1c38f5d8f273585e44c071c440cb495f03e822928ed7dd8d6ffd527791022ba31b05760e8016
6
+ metadata.gz: c6a12e0de0e1fe1d878152ebb5edd15359afaf0b93940da6823b001e4e77b7d31350d5d81f70eb562df5ab72f949c52c534b04af1b9543434f4dd16f9f46a139
7
+ data.tar.gz: f9b97f86513fa87255ed0c0cd3887fe3faab8185f1c0686d345d72f85b1e016fd78b555929516d095e287c03ecb3e3861fd6a5554c72c58980aab24c67ee092c
data/CHANGELOG.md CHANGED
@@ -2,6 +2,18 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [0.1.37] - Unreleased
6
+
7
+ ### Changed
8
+
9
+ - **Pulse metrics are now batched.** `Pulse.counter`, `gauge`, `histogram` and `record_metric` used to make one `POST /api/v1/metrics` per point, and during instrumentation spawned one thread per point (cache instrumentation emits two points per cache operation). They now accumulate in `Pulse::MetricBuffer` and go out through `POST /api/v1/metrics/batch` from a single background thread: when `pulse_buffer_size` points are pending or every `pulse_flush_interval` seconds (defaults 50 and 5). No HTTP happens on the calling thread and each process has at most one batch in flight. Setting `pulse_buffer_size = 1` keeps the old one-by-one behaviour.
10
+ - The backlog is capped at 20 batches (oldest points dropped) so a Pulse outage cannot grow host memory. Pending points are flushed at process exit, for at most 5 seconds. The buffer is fork-safe: each worker gets its own, and a child never resends what it inherited.
11
+ - Points that would get a whole batch rejected (`value` not a number or string; NaN, Infinity or invalid bytes that `JSON.generate` refuses) are dropped on their own.
12
+
13
+ ### Note
14
+
15
+ `Pulse.record_metric` no longer returns the HTTP response when batching is on, and a point can now wait up to `pulse_flush_interval` seconds before leaving the process. A process that ends with `exit!` skips `at_exit` and loses what is pending.
16
+
5
17
  ## [0.1.36] - 2026-10-29
6
18
 
7
19
  ### Fixed
@@ -3,6 +3,7 @@
3
3
  require 'net/http'
4
4
  require 'uri'
5
5
  require 'json'
6
+ require_relative 'metric_buffer'
6
7
 
7
8
  module BrainzLab
8
9
  module Pulse
@@ -43,8 +44,32 @@ module BrainzLab
43
44
 
44
45
  def send_metric(payload)
45
46
  return unless @config.pulse_enabled && @config.pulse_valid?
47
+ return post('/api/v1/metrics', payload) unless batching_metrics?
46
48
 
47
- post('/api/v1/metrics', payload)
49
+ metric_buffer.add(payload)
50
+ end
51
+
52
+ def send_metrics(payloads)
53
+ return unless @config.pulse_enabled && @config.pulse_valid?
54
+
55
+ sendable = payloads.select { |payload| sendable_metric?(payload) }
56
+ return if sendable.empty?
57
+
58
+ post('/api/v1/metrics/batch', { metrics: sendable })
59
+ end
60
+
61
+ def batching_metrics?
62
+ @config.pulse_buffer_size > 1
63
+ end
64
+
65
+ # Entrega las métricas pendientes y termina el hilo de fondo.
66
+ def shutdown
67
+ @metric_buffer&.shutdown
68
+ end
69
+
70
+ # Descarta las métricas pendientes y termina el hilo de fondo, sin tocar la red.
71
+ def stop
72
+ @metric_buffer&.stop
48
73
  end
49
74
 
50
75
  def send_span(payload)
@@ -68,6 +93,35 @@ module BrainzLab
68
93
 
69
94
  private
70
95
 
96
+ # Fork-safety: el hilo de fondo no sobrevive a un fork (workers de Puma). Cada
97
+ # proceso necesita su propio buffer, si no sus métricas se quedarían sin enviar.
98
+ def metric_buffer
99
+ @mutex.synchronize do
100
+ if @metric_buffer.nil? || @metric_buffer_pid != Process.pid
101
+ @metric_buffer = MetricBuffer.new(
102
+ batch_size: @config.pulse_buffer_size,
103
+ flush_interval: @config.pulse_flush_interval
104
+ ) { |batch| send_metrics(batch) }
105
+ @metric_buffer_pid = Process.pid
106
+ end
107
+ @metric_buffer
108
+ end
109
+ end
110
+
111
+ # Pulse rechaza el lote entero con un 422 si un value no es número ni string, y
112
+ # JSON.generate falla con NaN, Infinity o tags con bytes inválidos. Un solo punto
113
+ # así no puede llevarse por delante a los demás.
114
+ def sendable_metric?(payload)
115
+ value = payload[:value]
116
+ return false unless value.nil? || value.is_a?(Numeric) || value.is_a?(String)
117
+
118
+ JSON.generate(payload)
119
+ true
120
+ rescue JSON::GeneratorError, EncodingError => e
121
+ log_error("Dropped metric #{payload[:name].inspect}: #{e.message}")
122
+ false
123
+ end
124
+
71
125
  # Keep error traces always; otherwise keep with probability = the
72
126
  # effective per-tier sample rate (internal=0.1, standard=0.5, client=1.0).
73
127
  def keep_trace?(payload)
@@ -182,6 +236,8 @@ module BrainzLab
182
236
 
183
237
  data = if body.is_a?(Hash) && body[:traces]
184
238
  { count: body[:traces].size }
239
+ elsif body.is_a?(Hash) && body[:metrics]
240
+ { count: body[:metrics].size }
185
241
  elsif body.is_a?(Hash) && body[:name]
186
242
  { name: body[:name] }
187
243
  else
@@ -0,0 +1,128 @@
1
+ # frozen_string_literal: true
2
+
3
+ module BrainzLab
4
+ module Pulse
5
+ # Agrupa las métricas y las entrega desde un único hilo de fondo.
6
+ #
7
+ # La instrumentación emite desde el hilo de la petición: aquí nunca se hace
8
+ # HTTP en ese hilo, y un solo lote en vuelo por proceso acota la carga que un
9
+ # proceso puede poner sobre Pulse.
10
+ class MetricBuffer
11
+ # Con Pulse caído cada lote tarda hasta ~1 min en agotar reintentos. Sin este
12
+ # tope la cola crecería sin límite en la memoria de la app huésped.
13
+ MAX_PENDING_BATCHES = 20
14
+ DEFAULT_SHUTDOWN_TIMEOUT = 5 # segundos; debe caber en el grace period del pod
15
+
16
+ def initialize(batch_size:, flush_interval:, shutdown_timeout: DEFAULT_SHUTDOWN_TIMEOUT, &sender)
17
+ @batch_size = batch_size
18
+ @flush_interval = flush_interval
19
+ @shutdown_timeout = shutdown_timeout
20
+ @sender = sender
21
+ @max_pending = batch_size * MAX_PENDING_BATCHES
22
+ @pending = []
23
+ @dropped = 0
24
+ @closed = false
25
+ @mutex = Mutex.new
26
+ @wakeup = ConditionVariable.new
27
+ @owner_pid = Process.pid
28
+
29
+ at_exit { shutdown }
30
+ end
31
+
32
+ def add(metric)
33
+ @mutex.synchronize do
34
+ return if @closed
35
+
36
+ if @pending.size >= @max_pending
37
+ @pending.shift
38
+ @dropped += 1
39
+ end
40
+ @pending << metric
41
+ ensure_worker
42
+ @wakeup.signal if @pending.size >= @batch_size
43
+ end
44
+ nil
45
+ end
46
+
47
+ # Entrega lo pendiente y termina, sin pasar de shutdown_timeout.
48
+ def shutdown
49
+ # Un hijo forkeado hereda este at_exit y una copia de la cola: enviarla
50
+ # duplicaría los puntos que el padre sí va a entregar.
51
+ return unless Process.pid == @owner_pid
52
+
53
+ worker = @mutex.synchronize do
54
+ @closed = true
55
+ ensure_worker unless @pending.empty?
56
+ @wakeup.signal
57
+ @worker
58
+ end
59
+ worker&.join(@shutdown_timeout)
60
+ nil
61
+ end
62
+
63
+ # Descarta lo pendiente y termina, sin tocar la red.
64
+ def stop
65
+ @mutex.synchronize do
66
+ @closed = true
67
+ @pending.clear
68
+ @wakeup.signal
69
+ end
70
+ nil
71
+ end
72
+
73
+ def pending_size
74
+ @mutex.synchronize { @pending.size }
75
+ end
76
+
77
+ private
78
+
79
+ # Se llama con @mutex tomado. El hilo no sobrevive a un fork ni a una
80
+ # excepción que no sea StandardError, por eso se revisa en cada add.
81
+ def ensure_worker
82
+ return if @worker&.alive?
83
+
84
+ @worker = Thread.new { run }
85
+ @worker.report_on_exception = false
86
+ end
87
+
88
+ def run
89
+ loop do
90
+ batch, dropped, finished = next_batch
91
+ BrainzLab.debug_log("[Pulse] Dropped #{dropped} metrics: delivery is falling behind") if dropped.positive?
92
+ deliver(batch) unless batch.empty?
93
+ break if finished
94
+ end
95
+ end
96
+
97
+ def next_batch
98
+ @mutex.synchronize do
99
+ wait_for_batch
100
+ batch = @pending.shift(@batch_size)
101
+ dropped = @dropped
102
+ @dropped = 0
103
+ [batch, dropped, @closed && @pending.empty?]
104
+ end
105
+ end
106
+
107
+ def wait_for_batch
108
+ deadline = monotonic_now + @flush_interval
109
+ until @closed || @pending.size >= @batch_size
110
+ remaining = deadline - monotonic_now
111
+ break unless remaining.positive?
112
+
113
+ @wakeup.wait(@mutex, remaining)
114
+ end
115
+ end
116
+
117
+ def deliver(batch)
118
+ @sender.call(batch)
119
+ rescue StandardError => e
120
+ BrainzLab.debug_log("[Pulse] Metric batch send failed: #{e.message}")
121
+ end
122
+
123
+ def monotonic_now
124
+ Process.clock_gettime(Process::CLOCK_MONOTONIC)
125
+ end
126
+ end
127
+ end
128
+ end
@@ -83,9 +83,10 @@ module BrainzLab
83
83
  ensure_provisioned!
84
84
  return unless BrainzLab.configuration.pulse_valid?
85
85
 
86
- if BrainzLab.instrumenting?
86
+ if BrainzLab.instrumenting? && !client.batching_metrics?
87
87
  # During instrumentation, send in background thread to avoid
88
- # blocking the host app with synchronous HTTP
88
+ # blocking the host app with synchronous HTTP. The batching path
89
+ # never does HTTP on the calling thread.
89
90
  Thread.new { client.send_metric(payload) }
90
91
  else
91
92
  client.send_metric(payload)
@@ -176,6 +177,7 @@ module BrainzLab
176
177
  end
177
178
 
178
179
  def reset!
180
+ @client.stop if @client.respond_to?(:stop)
179
181
  @client = nil
180
182
  @tracer = nil
181
183
  @provisioner = nil
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module BrainzLab
4
- VERSION = '0.1.36'
4
+ VERSION = '0.1.37'
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: brainzlab
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.36
4
+ version: 0.1.37
5
5
  platform: ruby
6
6
  authors:
7
7
  - BrainzLab
@@ -179,6 +179,7 @@ files:
179
179
  - lib/brainzlab/pulse/client.rb
180
180
  - lib/brainzlab/pulse/explain_capture.rb
181
181
  - lib/brainzlab/pulse/instrumentation.rb
182
+ - lib/brainzlab/pulse/metric_buffer.rb
182
183
  - lib/brainzlab/pulse/propagation.rb
183
184
  - lib/brainzlab/pulse/provisioner.rb
184
185
  - lib/brainzlab/pulse/tracer.rb
@@ -248,7 +249,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
248
249
  - !ruby/object:Gem::Version
249
250
  version: '0'
250
251
  requirements: []
251
- rubygems_version: 3.6.9
252
+ rubygems_version: 4.0.10
252
253
  specification_version: 4
253
254
  summary: Ruby SDK for BrainzLab observability
254
255
  test_files: []