brainzlab 0.1.27 → 0.1.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b57a1a89ace36a6d6529526de7fbe3830959bd18d874052689a02baf21d2aae
-  data.tar.gz: cc0b0e99695dbd64ff561206df0e6e45ac619f666a04424e6b99633577c77e13
+  metadata.gz: 66b1827b6976d4cc3f0b16536eda54ac36ebc3fdba1f49369d93089198a99d73
+  data.tar.gz: 6a5d234eb169b6401ff226fe0944006fc3fea60df64a574aeb86f98466fd7c7d
 SHA512:
-  metadata.gz: 190513dceb2037e41a274b6e930735c8d918b674effbed07cb8077321eb9ebf6ffac328acaa050d18d80f4e488db58ccf8b60ac96687eb650a98c055804ad9e5
-  data.tar.gz: 6a51f042aedafa0e7995e6f17e2c17b2551fbd0415fb5b3b60d54980974e9c03f11b59ce3a696368042ac99faaa1387163122d7bcb4b01e9de0c7d7fc1cc02c2
+  metadata.gz: 2e958e58fdf83b5b472e3353a3f14b5b8d8a39315942eb74668735a2faefef9413d561b06b511bfff63fe2f633e8261320d3a8a7a25cf269ff0454283bfe6e36
+  data.tar.gz: 7601dbd331048b5fc8dd184c218ce9605ef010efd47d5b51fbeee52506f692bd4bad768219a4b8ad95562e9e28a006696886643c492fae303008ae8ca8c2795f

data/lib/brainzlab/configuration.rb

@@ -42,6 +42,7 @@ module BrainzLab
                   :pulse_buffer_size,
                   :pulse_flush_interval,
                   :pulse_sample_rate,
+                  :pulse_sample_tier,
                   :pulse_excluded_paths,
                   :flux_enabled,
                   :flux_url,
@@ -254,7 +255,12 @@ module BrainzLab
       @pulse_auto_provision = true
       @pulse_buffer_size = 50
       @pulse_flush_interval = 5
-      @pulse_sample_rate = nil
+      # Trace sampling. Explicit rate (0.0–1.0) wins; otherwise derived from the
+      # tier. Defaults to the "internal" tier so the Brainz fleet samples ~10%
+      # (error traces are always kept). Client-facing apps set
+      # BRAINZLAB_PULSE_TIER=client (or PULSE_SAMPLE_RATE) to keep everything.
+      @pulse_sample_rate = (v = ENV['PULSE_SAMPLE_RATE'] || ENV['BRAINZLAB_PULSE_SAMPLE_RATE']).nil? || v.to_s.strip.empty? ? nil : v.to_f
+      @pulse_sample_tier = (ENV['BRAINZLAB_PULSE_TIER'] || 'internal').to_s.strip.downcase
       @pulse_excluded_paths = %w[/health /ping /up /assets]
 
       # Flux settings
@@ -509,6 +515,23 @@ module BrainzLab
       pulse_api_key || secret_key
     end
 
+    # Per-tier default trace sample rates. Internal (the Brainz fleet's own
+    # telemetry) samples aggressively; client/critical keep everything. Error
+    # traces are always kept regardless (see Pulse::Tracer).
+    PULSE_TIER_SAMPLE_RATES = {
+      'internal' => 0.1,
+      'standard' => 0.5,
+      'client'   => 1.0,
+      'critical' => 1.0
+    }.freeze
+
+    # Effective 0.0–1.0 trace sample rate: explicit rate wins, else the tier's
+    # default, else 1.0 (sample everything) for unknown tiers.
+    def effective_pulse_sample_rate
+      rate = pulse_sample_rate || PULSE_TIER_SAMPLE_RATES.fetch(pulse_sample_tier, 1.0)
+      rate.to_f.clamp(0.0, 1.0)
+    end
+
     def flux_valid?
       key = flux_ingest_key || flux_api_key || secret_key
       !key.nil? && !key.empty?

data/lib/brainzlab/pulse/client.rb

@@ -20,6 +20,13 @@ module BrainzLab
       def send_trace(payload)
         return unless @config.pulse_enabled && @config.pulse_valid?
 
+        # Per-trace sampling — the single chokepoint every trace path funnels
+        # through (request middleware, jobs, sidekiq, delayed_job, grape, manual
+        # traces). Decided once per complete trace (spans travel inline in the
+        # payload, so they never orphan) and BEFORE buffering, so dropped traces
+        # never reach the buffer/batch. Error traces are always kept.
+        return unless keep_trace?(payload)
+
         if @config.pulse_buffer_size > 1
           buffer_trace(payload)
         else
@@ -61,6 +68,15 @@ module BrainzLab
 
       private
 
+      # Keep error traces always; otherwise keep with probability = the
+      # effective per-tier sample rate (internal=0.1, standard=0.5, client=1.0).
+      def keep_trace?(payload)
+        return true if payload[:error] == true || payload['error'] == true
+
+        rate = @config.effective_pulse_sample_rate
+        rate >= 1.0 || rand < rate
+      end
+
       def buffer_trace(payload)
         should_flush = false
 

data/lib/brainzlab/pulse/tracer.rb

@@ -38,6 +38,8 @@ module BrainzLab
         trace = current_trace
         return unless trace
 
+        # Sampling is applied at the single send chokepoint (Pulse::Client#send_trace),
+        # which every trace path funnels through — so finish_trace just builds + sends.
         ended_at = Time.now.utc
         duration_ms = ((ended_at - trace[:started_at]) * 1000).round(2)
 

data/lib/brainzlab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BrainzLab
-  VERSION = '0.1.27'
+  VERSION = '0.1.29'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: brainzlab
 version: !ruby/object:Gem::Version
-  version: 0.1.27
+  version: 0.1.29
 platform: ruby
 authors:
 - BrainzLab
@@ -246,7 +246,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby SDK for BrainzLab observability
 test_files: []