brainzlab 0.1.33 → 0.1.35

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9a9a15a426d4a6853086c9a36851e57bd14736c5d11dbeb70fb510fe5fc1c10
-  data.tar.gz: 19f26af342b3d9150eacb2615da08fa063cc671388f7b97a87b207cd210cf6fc
+  metadata.gz: bf1207ec18676d63267312a25c4bcbe2519a1ddc70ceb5bb34ac58f7a83e29d2
+  data.tar.gz: d8ea421af25cae73f94d4741eed9a404c6297477088eaf3df9b4a000675824da
 SHA512:
-  metadata.gz: b149c1fbf2c0f13fa34d0b2d2e6df634a1dc01f087f8174ba58fcc0bf05ea0301365721131e03441bf0af7e3b443d5a86acc5dfa141ba4fa9af2c24c610782a9
-  data.tar.gz: 737cd856a43c4c3555a566653692fd32d04798e464e24bad80d189610b82e81c0d0b2860cda232fae66063477b21687858c14e5178050a771af6745b9741d46f
+  metadata.gz: 2bee3ad0497520af5744ccd898360f389ac30bf599382d4af14f871d2b1f30659a5879a8ad5a6dfcfd1bf008445e0262a1d2fa5887d00146128099cda99410b3
+  data.tar.gz: 0760d616e2b3a32c2c408098d5a69d4a68d3d3ab52f3dbde121d2994c4498bb5c26cbc24fd6d569a3f41d6614cceca3075a9f06df1bbdea1bd5f9da399da2861

data/README.md

@@ -198,6 +198,44 @@ config.pulse_excluded_paths = ['/health', '/ping', '/up', '/assets']
 config.pulse_sample_rate = 1.0          # 1.0 = 100%
 ```
 
+### Query plans (EXPLAIN)
+
+Off by default. When enabled, a query slower than the threshold gets an
+`EXPLAIN` run against your own database and the plan travels with the span, so
+Pulse can tell you *why* a query is slow instead of only that it is.
+
+```ruby
+config.pulse_explain_enabled = true   # default: false
+config.pulse_explain_threshold = 500  # ms; defaults to slow_query_threshold
+config.pulse_explain_timeout = 2      # seconds to wait for a plan
+```
+
+Or via environment: `BRAINZLAB_PULSE_EXPLAIN_ENABLED`,
+`BRAINZLAB_PULSE_EXPLAIN_THRESHOLD`, `BRAINZLAB_PULSE_EXPLAIN_TIMEOUT`.
+
+What it will and will not do:
+
+- **Read-only statements only.** A write is never explained.
+- **Plain `EXPLAIN`, never `EXPLAIN ANALYZE`** — the statement is planned, not run.
+- **One plan per distinct statement**, not one per occurrence.
+- **A timeout**, so a slow planner cannot stall a request.
+- **Failures are swallowed.** If the database refuses the `EXPLAIN`, the span is
+  recorded without a plan; instrumentation never breaks the app.
+
+It does issue one extra query per newly-seen slow statement, which is why you opt
+in rather than opt out.
+
+### Configuration validation
+
+`BrainzLab.configure` validates the configuration when your block finishes and
+raises `BrainzLab::ConfigurationError` listing everything that is wrong, rather
+than letting a typo turn into missing telemetry. The common one:
+
+```ruby
+config.pulse_sample_rate = 50   # raises — sample rates are fractions
+config.pulse_sample_rate = 0.5  # 50%
+```
+
 ### Distributed Tracing
 
 Pulse supports distributed tracing across services using W3C Trace Context and B3 propagation.

data/lib/brainzlab/beacon/client.rb

@@ -204,9 +204,9 @@ module BrainzLab
         BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{structured_error.message}")
 
         # Call on_error callback if configured
-        if @config.on_error
-          @config.on_error.call(structured_error, { service: 'Beacon', operation: operation })
-        end
+        return unless @config.on_error
+
+        @config.on_error.call(structured_error, { service: 'Beacon', operation: operation })
       end
 
       def handle_response_error(response, operation)
@@ -216,9 +216,7 @@ module BrainzLab
         BrainzLab.debug_log("[Beacon::Client] #{operation} failed: #{structured_error.message}")
 
         # Call on_error callback if configured
-        if @config.on_error
-          @config.on_error.call(structured_error, { service: 'Beacon', operation: operation })
-        end
+        @config.on_error&.call(structured_error, { service: 'Beacon', operation: operation })
 
         structured_error
       end