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 +4 -4
- data/CHANGELOG.md +12 -0
- data/lib/brainzlab/pulse/client.rb +57 -1
- data/lib/brainzlab/pulse/metric_buffer.rb +128 -0
- data/lib/brainzlab/pulse.rb +4 -2
- data/lib/brainzlab/version.rb +1 -1
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 1a5e45616c86bfb16c81bf506b428a4aca149f71ea9b6888c92329d2738876c2
|
|
4
|
+
data.tar.gz: 335891991652de956d08b83d9d7c64d683059832da2998cbd7a017561a4ec8ff
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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
|
-
|
|
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
|
data/lib/brainzlab/pulse.rb
CHANGED
|
@@ -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
|
data/lib/brainzlab/version.rb
CHANGED
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.
|
|
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:
|
|
252
|
+
rubygems_version: 4.0.10
|
|
252
253
|
specification_version: 4
|
|
253
254
|
summary: Ruby SDK for BrainzLab observability
|
|
254
255
|
test_files: []
|