debugbundle 2.1.2 → 2.1.3
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/README.md +194 -164
- data/lib/debugbundle/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ed63517f7a7215979c0fbd337d89a5d0209e20832649181f238146624afdf47c
|
|
4
|
+
data.tar.gz: e889040151410ddfbc181e1b04c7b78a604d525d2c11eeb69d85ccbd0f911ab5
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 463f001e83ad2506acb1d011b664408aff5af03d72fe2405458ff9f0b9752383f2328a2824a721e56f2a784798cf07a791f931dee629e539b3c623d85de3d53c
|
|
7
|
+
data.tar.gz: f0fcabc9b7c7762a41188c041ea72be0e9d472cf706db486151b5dee743e5b1d2fdc69015f283cd30daa73e2169e94522931297285c83bd20253e75236b0ff0b
|
data/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# debugbundle
|
|
2
2
|
|
|
3
|
-
Patch 2.1.
|
|
3
|
+
Patch 2.1.3 protects invitation and organisation-transfer credentials in captured text while preserving public APIs and event schemas. Upgrade the DebugBundle distribution to adopt the protection.
|
|
4
4
|
|
|
5
5
|
Ruby SDK for DebugBundle.
|
|
6
6
|
|
|
@@ -14,11 +14,179 @@ Version 2.0 changes capture and hook timing. Existing installed 1.5.x applicatio
|
|
|
14
14
|
|
|
15
15
|
Mandatory privacy checks reuse at most 256 field-name decisions and 256 unchanged scalar strings of at most 128 bytes within each projection. Returned values remain independently owned. Every value and repeated key still counts against the existing resource budgets; both caches are discarded before the next event or policy.
|
|
16
16
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
17
|
+
## Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
gem install debugbundle
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Or add it to your Gemfile and run `bundle install`:
|
|
24
|
+
|
|
25
|
+
```ruby
|
|
26
|
+
gem "debugbundle"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Initialize
|
|
30
|
+
|
|
31
|
+
<a id="quick-start"></a>
|
|
32
|
+
|
|
33
|
+
Initialize once at application startup with `DEBUGBUNDLE_PROJECT_TOKEN` set in the server environment. Initialization arms best-effort process exception capture. Add framework and logger adapters below.
|
|
34
|
+
|
|
35
|
+
```ruby
|
|
36
|
+
require "debugbundle"
|
|
37
|
+
|
|
38
|
+
DebugBundle.init(
|
|
39
|
+
project_token: ENV["DEBUGBUNDLE_PROJECT_TOKEN"],
|
|
40
|
+
environment: "production",
|
|
41
|
+
service: "api"
|
|
42
|
+
)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Integrations
|
|
46
|
+
|
|
47
|
+
Rails, Rack, Sidekiq, Ruby Logger, Semantic Logger and browser relay handlers are supported.
|
|
48
|
+
|
|
49
|
+
### Capture setup details
|
|
50
|
+
|
|
51
|
+
`DebugBundle.init(...)` arms best-effort process exception capture automatically through `at_exit` and thread exception hooks. These hooks wake the sender without waiting for delivery; shutdown exceptions can be lost if the process exits before the sender finishes. Automatic delivery runs on one background sender thread when the configured batch size or flush interval is reached. Remote configuration uses a separate bounded poller so a slow fetch cannot hold delivery. An explicit `flush` waits for the sender for at most five seconds and reports whether delivery completed. Call it during a controlled shutdown window when delivery is required. A forked child starts fresh workers on its first SDK use and drops inherited parent events, context, and probes while retaining the parent's capture restrictions until remote configuration refreshes.
|
|
52
|
+
|
|
53
|
+
### Framework Integrations
|
|
54
|
+
|
|
55
|
+
| Surface | Integration |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| Rack | `DebugBundle::Rack::Middleware` |
|
|
58
|
+
| Rails | Railtie bootstrap, Rack middleware, and auto-mounted relay route |
|
|
59
|
+
| Sidekiq | `DebugBundle::Sidekiq::ServerMiddleware` |
|
|
60
|
+
| Ruby Logger | `DebugBundle.capture_logger(logger)` |
|
|
61
|
+
| Semantic Logger | `DebugBundle.capture_semantic_logger` |
|
|
62
|
+
| Browser relay | `DebugBundle::Relay::Handler` or `DebugBundle::Rack::RelayMiddleware` |
|
|
63
|
+
|
|
64
|
+
### Browser Relay
|
|
65
|
+
|
|
66
|
+
Ruby backends can receive browser events at `POST /debugbundle/browser` through the relay handler.
|
|
67
|
+
|
|
68
|
+
Rails applications can let the Railtie append that route automatically, or override it with:
|
|
69
|
+
|
|
70
|
+
- `config.debugbundle.relay_enabled = false` to disable automatic mounting
|
|
71
|
+
- `config.debugbundle.relay_path = "/debugbundle/browser"` to change the mounted path
|
|
72
|
+
- `config.debugbundle.relay_allowed_origins = ["https://app.example.com"]` to pin allowed origins
|
|
73
|
+
- `config.debugbundle.relay_rate_limit_per_minute = 120` to adjust per-IP rate limiting
|
|
74
|
+
- `config.debugbundle.relay_rate_limit_store = Rails.cache` to share rate limiting across processes
|
|
75
|
+
- `config.debugbundle.relay_handler = custom_handler` to supply a custom relay handler
|
|
76
|
+
|
|
77
|
+
Rack applications can mount the same handler explicitly:
|
|
78
|
+
|
|
79
|
+
```ruby
|
|
80
|
+
relay_handler = DebugBundle::Relay::Handler.new(
|
|
81
|
+
project_mode: :connected,
|
|
82
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
83
|
+
endpoint: "https://api.debugbundle.com/v1/events",
|
|
84
|
+
allowed_origins: ["https://app.example.com"]
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
use DebugBundle::Rack::RelayMiddleware, handler: relay_handler
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Relay behavior:
|
|
91
|
+
|
|
92
|
+
- same-origin is the safe default when you do not set explicit allowed origins
|
|
93
|
+
- use explicit allowed origins when the frontend and backend live on different hosts
|
|
94
|
+
- requests must use `Content-Type: application/json`
|
|
95
|
+
- request bodies are capped at 256 KB
|
|
96
|
+
- per-IP rate limiting defaults to 60 requests per minute
|
|
97
|
+
- browser-supplied DebugBundle credentials are stripped before delivery, preserving credential isolation
|
|
98
|
+
- browser `service`, `environment`, and correlation fields are preserved unless you explicitly override them in the relay handler
|
|
99
|
+
- local-only mode writes validated browser events to `.debugbundle/local/events`
|
|
100
|
+
- connected durable mode writes validated browser events to `.debugbundle/local/browser-relay-spool` before forwarding to the configured endpoint
|
|
101
|
+
- set `relay_durable_write: false` when you intentionally want connected forwarding without the local spool write
|
|
102
|
+
- to disable the relay entirely, leave the route unmounted or set `relay_enabled = false`
|
|
103
|
+
- a missing token means connected forwarding cannot succeed; treat that as a server config error and leave the route disabled until the server-side token is fixed
|
|
104
|
+
|
|
105
|
+
### Manual capture and logging
|
|
106
|
+
|
|
107
|
+
```ruby
|
|
108
|
+
require "logger"
|
|
109
|
+
|
|
110
|
+
DebugBundle.capture_logger(Logger.new($stdout))
|
|
111
|
+
|
|
112
|
+
begin
|
|
113
|
+
perform_checkout
|
|
114
|
+
rescue => error
|
|
115
|
+
DebugBundle.capture_exception(error, context: { order_id: 123 })
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
DebugBundle.capture_message("worker started", level: :info)
|
|
119
|
+
DebugBundle.flush
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## First-event verification
|
|
123
|
+
|
|
124
|
+
Use an explicit setup event in a development or staging application, then confirm the matching service and environment in a received event or incident. Initialization, a healthy status and an empty queue are not delivery receipts. Keep the application running long enough for delivery; use bounded flushing only in tests or controlled teardown, never in a request handler.
|
|
125
|
+
|
|
126
|
+
Use an explicit test message or exception during setup:
|
|
127
|
+
|
|
128
|
+
```ruby
|
|
129
|
+
require "debugbundle"
|
|
130
|
+
|
|
131
|
+
DebugBundle.init(
|
|
132
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
133
|
+
service: "debugbundle-first-event",
|
|
134
|
+
environment: "staging"
|
|
135
|
+
)
|
|
136
|
+
|
|
137
|
+
DebugBundle.capture_message("debugbundle first-event verification", level: :error)
|
|
138
|
+
DebugBundle.flush
|
|
139
|
+
puts [DebugBundle.status, DebugBundle.last_event_at].inspect
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Then confirm the event through your mock ingestion endpoint, a staging project, or the DebugBundle CLI verification flow.
|
|
143
|
+
|
|
144
|
+
This repository also ships a clean-install app-driven smoke harness that validates the built gem and the published gem path:
|
|
145
|
+
|
|
146
|
+
```sh
|
|
147
|
+
make smoke
|
|
148
|
+
make smoke-published VERSION=1.5.0
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`make smoke` builds the gem, installs it into a fresh RubyGems home, drives a Rack request plus a browser relay batch through the public SDK surface, validates event envelope shape, and confirms the mock ingestion endpoint receives the expected service, environment, SDK metadata, and correlation fields. For version 2.0, it also forks the installed client and verifies exactly one child event without replaying the parent's buffered event.
|
|
152
|
+
|
|
153
|
+
For connected delivery, confirm the event in DebugBundle and inspect its incident with the CLI. For local-file delivery, run `debugbundle process` followed by `debugbundle inspect <incident-id>`. A local file or mock endpoint receipt proves only that destination; it does not prove cloud acceptance.
|
|
154
|
+
|
|
155
|
+
## Configuration
|
|
156
|
+
|
|
157
|
+
<a id="configuration-reference"></a>
|
|
158
|
+
|
|
159
|
+
Configuration sources and precedence:
|
|
160
|
+
|
|
161
|
+
1. Explicit arguments passed to `DebugBundle.init(...)`, `DebugBundle::Client.new(...)`, or `DebugBundle::Relay::Handler.new(...)`.
|
|
162
|
+
2. Rails `config.debugbundle.*` values when the Railtie wires the default client or relay route.
|
|
163
|
+
3. Environment variables only when your application chooses to pass them into those explicit Ruby calls. The gem does not auto-read arbitrary config env vars on its own.
|
|
164
|
+
4. Remote probe directives and capture policy returned by `GET /v1/sdk/config` after a connected client initializes.
|
|
165
|
+
|
|
166
|
+
Capture-policy fields are server-owned and must not be supplied in local SDK config. The Ruby SDK enforces the server response locally after initialization.
|
|
167
|
+
|
|
168
|
+
| Option | Default | Purpose |
|
|
169
|
+
| --- | --- | --- |
|
|
170
|
+
| `project_token` | required for connected capture | Write-only DebugBundle project token used by server-side transport. |
|
|
171
|
+
| `service` | `ruby-service` | Service name used in event envelopes. |
|
|
172
|
+
| `environment` | `development` | Runtime environment. |
|
|
173
|
+
| `endpoint` | `https://api.debugbundle.com/v1/events` | Connected ingestion endpoint. |
|
|
174
|
+
| `enabled` | `true` | Disable all capture without removing instrumentation. |
|
|
175
|
+
| `project_mode` | `connected` | `connected` or `local_only`. |
|
|
176
|
+
| `local_events_dir` | `.debugbundle/local/events` | Local event file destination. |
|
|
177
|
+
| `spool_dir` | `.debugbundle/local/browser-relay-spool` | Relay durable spool destination. |
|
|
178
|
+
| `redact_fields` | `[]` | Additional sensitive field names merged with built-in redaction defaults. Rails `filter_parameters` are added automatically. |
|
|
179
|
+
| `batch_size` | `25` | Wake the background sender when this many events are buffered. |
|
|
180
|
+
| `flush_interval` | `5` | Flush interval in seconds. |
|
|
181
|
+
| `sample_rate` | `1.0` | Fraction of events kept before transport. |
|
|
182
|
+
| `log_level` | `warning` | Minimum captured log severity. |
|
|
183
|
+
| `relay_enabled` | `true` | Enable relay handling when using the Rails helper surface. |
|
|
184
|
+
| `relay_rate_limit_per_minute` | `60` | Per-IP rate limit for browser relay requests. |
|
|
185
|
+
| `relay_durable_write` | `true` | Write relay batches to the local spool before connected forwarding. |
|
|
186
|
+
| `max_probe_labels` | `50` | Max distinct probe labels kept in memory. |
|
|
187
|
+
| `max_probe_entries_per_label` | `10` | Max entries retained per probe label. |
|
|
188
|
+
| `probe_flush_on_error` | `true` | Attach probe buffers to captured exceptions. |
|
|
189
|
+
| `probes_poll_interval` | `60` | Remote config poll interval in seconds. |
|
|
22
190
|
|
|
23
191
|
## Evidence in 2.1.0
|
|
24
192
|
|
|
@@ -37,7 +205,7 @@ the option enabled, report application-observed outcomes inside an operation:
|
|
|
37
205
|
require "securerandom"
|
|
38
206
|
|
|
39
207
|
client = DebugBundle::Client.new(
|
|
40
|
-
project_token: ENV.fetch("
|
|
208
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
41
209
|
capture_recovery_observations: true
|
|
42
210
|
)
|
|
43
211
|
|
|
@@ -125,83 +293,6 @@ create a delivered marker. Installed/runtime qualification passed before publica
|
|
|
125
293
|
|
|
126
294
|
`capture_logger(logger)` respects the logger level, Rails silence and disabled output. Lazy message blocks are evaluated by the native logger: zero times when suppressed and once when accepted. Native return values and application block exceptions are preserved. DebugBundle applies its own configured minimum capture level after the logger accepts a message.
|
|
127
295
|
|
|
128
|
-
## Installation
|
|
129
|
-
|
|
130
|
-
```ruby
|
|
131
|
-
gem "debugbundle"
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
## Quick Start
|
|
135
|
-
|
|
136
|
-
```ruby
|
|
137
|
-
require "debugbundle"
|
|
138
|
-
require "logger"
|
|
139
|
-
|
|
140
|
-
DebugBundle.init(
|
|
141
|
-
project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
|
|
142
|
-
service: "checkout-api",
|
|
143
|
-
environment: ENV.fetch("APP_ENV", "production")
|
|
144
|
-
)
|
|
145
|
-
|
|
146
|
-
DebugBundle.capture_logger(Logger.new($stdout))
|
|
147
|
-
|
|
148
|
-
begin
|
|
149
|
-
perform_checkout
|
|
150
|
-
rescue => error
|
|
151
|
-
DebugBundle.capture_exception(error, context: { order_id: 123 })
|
|
152
|
-
end
|
|
153
|
-
|
|
154
|
-
DebugBundle.capture_message("worker started", level: :info)
|
|
155
|
-
DebugBundle.flush
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
`DebugBundle.init(...)` arms best-effort process exception capture automatically through `at_exit` and thread exception hooks. These hooks wake the sender without waiting for delivery; shutdown exceptions can be lost if the process exits before the sender finishes. Automatic delivery runs on one background sender thread when the configured batch size or flush interval is reached. Remote configuration uses a separate bounded poller so a slow fetch cannot hold delivery. An explicit `flush` waits for the sender for at most five seconds and reports whether delivery completed. Call it during a controlled shutdown window when delivery is required. A forked child starts fresh workers on its first SDK use and drops inherited parent events, context, and probes while retaining the parent's capture restrictions until remote configuration refreshes.
|
|
159
|
-
|
|
160
|
-
## Framework Integrations
|
|
161
|
-
|
|
162
|
-
| Surface | Integration |
|
|
163
|
-
| --- | --- |
|
|
164
|
-
| Rack | `DebugBundle::Rack::Middleware` |
|
|
165
|
-
| Rails | Railtie bootstrap, Rack middleware, and auto-mounted relay route |
|
|
166
|
-
| Sidekiq | `DebugBundle::Sidekiq::ServerMiddleware` |
|
|
167
|
-
| Ruby Logger | `DebugBundle.capture_logger(logger)` |
|
|
168
|
-
| Semantic Logger | `DebugBundle.capture_semantic_logger` |
|
|
169
|
-
| Browser relay | `DebugBundle::Relay::Handler` or `DebugBundle::Rack::RelayMiddleware` |
|
|
170
|
-
|
|
171
|
-
## Configuration Reference
|
|
172
|
-
|
|
173
|
-
Configuration sources and precedence:
|
|
174
|
-
|
|
175
|
-
1. Explicit arguments passed to `DebugBundle.init(...)`, `DebugBundle::Client.new(...)`, or `DebugBundle::Relay::Handler.new(...)`.
|
|
176
|
-
2. Rails `config.debugbundle.*` values when the Railtie wires the default client or relay route.
|
|
177
|
-
3. Environment variables only when your application chooses to pass them into those explicit Ruby calls. The gem does not auto-read arbitrary config env vars on its own.
|
|
178
|
-
4. Remote probe directives and capture policy returned by `GET /v1/sdk/config` after a connected client initializes.
|
|
179
|
-
|
|
180
|
-
Capture-policy fields are server-owned and must not be supplied in local SDK config. The Ruby SDK enforces the server response locally after initialization.
|
|
181
|
-
|
|
182
|
-
| Option | Default | Purpose |
|
|
183
|
-
| --- | --- | --- |
|
|
184
|
-
| `project_token` | required for connected capture | Write-only DebugBundle project token used by server-side transport. |
|
|
185
|
-
| `service` | `ruby-service` | Service name used in event envelopes. |
|
|
186
|
-
| `environment` | `development` | Runtime environment. |
|
|
187
|
-
| `endpoint` | `https://api.debugbundle.com/v1/events` | Connected ingestion endpoint. |
|
|
188
|
-
| `enabled` | `true` | Disable all capture without removing instrumentation. |
|
|
189
|
-
| `project_mode` | `connected` | `connected` or `local_only`. |
|
|
190
|
-
| `local_events_dir` | `.debugbundle/local/events` | Local event file destination. |
|
|
191
|
-
| `spool_dir` | `.debugbundle/local/browser-relay-spool` | Relay durable spool destination. |
|
|
192
|
-
| `redact_fields` | `[]` | Additional sensitive field names merged with built-in redaction defaults. Rails `filter_parameters` are added automatically. |
|
|
193
|
-
| `batch_size` | `25` | Wake the background sender when this many events are buffered. |
|
|
194
|
-
| `flush_interval` | `5` | Flush interval in seconds. |
|
|
195
|
-
| `sample_rate` | `1.0` | Fraction of events kept before transport. |
|
|
196
|
-
| `log_level` | `warning` | Minimum captured log severity. |
|
|
197
|
-
| `relay_enabled` | `true` | Enable relay handling when using the Rails helper surface. |
|
|
198
|
-
| `relay_rate_limit_per_minute` | `60` | Per-IP rate limit for browser relay requests. |
|
|
199
|
-
| `relay_durable_write` | `true` | Write relay batches to the local spool before connected forwarding. |
|
|
200
|
-
| `max_probe_labels` | `50` | Max distinct probe labels kept in memory. |
|
|
201
|
-
| `max_probe_entries_per_label` | `10` | Max entries retained per probe label. |
|
|
202
|
-
| `probe_flush_on_error` | `true` | Attach probe buffers to captured exceptions. |
|
|
203
|
-
| `probes_poll_interval` | `60` | Remote config poll interval in seconds. |
|
|
204
|
-
|
|
205
296
|
## Install Examples by Mode
|
|
206
297
|
|
|
207
298
|
### Connected mode
|
|
@@ -210,7 +301,7 @@ Capture-policy fields are server-owned and must not be supplied in local SDK con
|
|
|
210
301
|
require "debugbundle"
|
|
211
302
|
|
|
212
303
|
DebugBundle.init(
|
|
213
|
-
project_token: ENV.fetch("
|
|
304
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
214
305
|
service: "checkout-api",
|
|
215
306
|
environment: "production",
|
|
216
307
|
endpoint: "https://api.debugbundle.com/v1/events"
|
|
@@ -223,7 +314,7 @@ DebugBundle.init(
|
|
|
223
314
|
require "debugbundle"
|
|
224
315
|
|
|
225
316
|
DebugBundle.init(
|
|
226
|
-
project_token: ENV.fetch("
|
|
317
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
227
318
|
service: "checkout-api",
|
|
228
319
|
environment: "development",
|
|
229
320
|
project_mode: :local_only,
|
|
@@ -238,7 +329,7 @@ require "debugbundle"
|
|
|
238
329
|
require "rack"
|
|
239
330
|
|
|
240
331
|
client = DebugBundle.init(
|
|
241
|
-
project_token: ENV.fetch("
|
|
332
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
242
333
|
service: "checkout-api",
|
|
243
334
|
environment: "production"
|
|
244
335
|
)
|
|
@@ -259,7 +350,7 @@ end
|
|
|
259
350
|
require "debugbundle"
|
|
260
351
|
|
|
261
352
|
DebugBundle.init(
|
|
262
|
-
project_token: ENV.fetch("
|
|
353
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
263
354
|
service: "checkout-api",
|
|
264
355
|
environment: Rails.env
|
|
265
356
|
)
|
|
@@ -275,7 +366,7 @@ end
|
|
|
275
366
|
require "debugbundle"
|
|
276
367
|
|
|
277
368
|
DebugBundle.init(
|
|
278
|
-
project_token: ENV.fetch("
|
|
369
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
279
370
|
service: "checkout-worker",
|
|
280
371
|
environment: ENV.fetch("APP_ENV", "production")
|
|
281
372
|
)
|
|
@@ -294,7 +385,7 @@ require "debugbundle"
|
|
|
294
385
|
require "logger"
|
|
295
386
|
|
|
296
387
|
DebugBundle.init(
|
|
297
|
-
project_token: ENV.fetch("
|
|
388
|
+
project_token: ENV.fetch("DEBUGBUNDLE_PROJECT_TOKEN"),
|
|
298
389
|
service: "checkout-api"
|
|
299
390
|
)
|
|
300
391
|
|
|
@@ -321,47 +412,6 @@ Post-V1 integrations remain out of scope here: Resque, Delayed Job, GoodJob, Sne
|
|
|
321
412
|
- Keep Rack, Rails, and Sidekiq inside the supported lanes above.
|
|
322
413
|
- Do not mix unsupported framework majors into examples or deployment templates.
|
|
323
414
|
|
|
324
|
-
## Browser Relay
|
|
325
|
-
|
|
326
|
-
Ruby backends can receive browser events at `POST /debugbundle/browser` through the relay handler.
|
|
327
|
-
|
|
328
|
-
Rails applications can let the Railtie append that route automatically, or override it with:
|
|
329
|
-
|
|
330
|
-
- `config.debugbundle.relay_enabled = false` to disable automatic mounting
|
|
331
|
-
- `config.debugbundle.relay_path = "/debugbundle/browser"` to change the mounted path
|
|
332
|
-
- `config.debugbundle.relay_allowed_origins = ["https://app.example.com"]` to pin allowed origins
|
|
333
|
-
- `config.debugbundle.relay_rate_limit_per_minute = 120` to adjust per-IP rate limiting
|
|
334
|
-
- `config.debugbundle.relay_rate_limit_store = Rails.cache` to share rate limiting across processes
|
|
335
|
-
- `config.debugbundle.relay_handler = custom_handler` to supply a custom relay handler
|
|
336
|
-
|
|
337
|
-
Rack applications can mount the same handler explicitly:
|
|
338
|
-
|
|
339
|
-
```ruby
|
|
340
|
-
relay_handler = DebugBundle::Relay::Handler.new(
|
|
341
|
-
project_mode: :connected,
|
|
342
|
-
project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
|
|
343
|
-
endpoint: "https://api.debugbundle.com/v1/events",
|
|
344
|
-
allowed_origins: ["https://app.example.com"]
|
|
345
|
-
)
|
|
346
|
-
|
|
347
|
-
use DebugBundle::Rack::RelayMiddleware, handler: relay_handler
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
Relay behavior:
|
|
351
|
-
|
|
352
|
-
- same-origin is the safe default when you do not set explicit allowed origins
|
|
353
|
-
- use explicit allowed origins when the frontend and backend live on different hosts
|
|
354
|
-
- requests must use `Content-Type: application/json`
|
|
355
|
-
- request bodies are capped at 256 KB
|
|
356
|
-
- per-IP rate limiting defaults to 60 requests per minute
|
|
357
|
-
- browser-supplied DebugBundle credentials are stripped before delivery, preserving credential isolation
|
|
358
|
-
- browser `service`, `environment`, and correlation fields are preserved unless you explicitly override them in the relay handler
|
|
359
|
-
- local-only mode writes validated browser events to `.debugbundle/local/events`
|
|
360
|
-
- connected durable mode writes validated browser events to `.debugbundle/local/browser-relay-spool` before forwarding to the configured endpoint
|
|
361
|
-
- set `relay_durable_write: false` when you intentionally want connected forwarding without the local spool write
|
|
362
|
-
- to disable the relay entirely, leave the route unmounted or set `relay_enabled = false`
|
|
363
|
-
- a missing token means connected forwarding cannot succeed; treat that as a server config error and leave the route disabled until the server-side token is fixed
|
|
364
|
-
|
|
365
415
|
## Remote Probes
|
|
366
416
|
|
|
367
417
|
Probe buffers stay local and flush on captured exceptions by default. Paid-tier projects can also activate probes for immediate `probe_event` shipping through the polled remote config.
|
|
@@ -411,35 +461,6 @@ Status meanings:
|
|
|
411
461
|
|
|
412
462
|
The release rule here is fail-safe, not fail-open: connected mode with a missing token must never pretend capture is healthy.
|
|
413
463
|
|
|
414
|
-
## First-Event Verification
|
|
415
|
-
|
|
416
|
-
Use an explicit test message or exception during setup:
|
|
417
|
-
|
|
418
|
-
```ruby
|
|
419
|
-
require "debugbundle"
|
|
420
|
-
|
|
421
|
-
DebugBundle.init(
|
|
422
|
-
project_token: ENV.fetch("DEBUGBUNDLE_TOKEN"),
|
|
423
|
-
service: "debugbundle-first-event",
|
|
424
|
-
environment: "staging"
|
|
425
|
-
)
|
|
426
|
-
|
|
427
|
-
DebugBundle.capture_message("debugbundle first-event verification", level: :error)
|
|
428
|
-
DebugBundle.flush
|
|
429
|
-
puts [DebugBundle.status, DebugBundle.last_event_at].inspect
|
|
430
|
-
```
|
|
431
|
-
|
|
432
|
-
Then confirm the event through your mock ingestion endpoint, a staging project, or the DebugBundle CLI verification flow.
|
|
433
|
-
|
|
434
|
-
This repository also ships a clean-install app-driven smoke harness that validates the built gem and the published gem path:
|
|
435
|
-
|
|
436
|
-
```sh
|
|
437
|
-
make smoke
|
|
438
|
-
make smoke-published VERSION=1.5.0
|
|
439
|
-
```
|
|
440
|
-
|
|
441
|
-
`make smoke` builds the gem, installs it into a fresh RubyGems home, drives a Rack request plus a browser relay batch through the public SDK surface, validates event envelope shape, and confirms the mock ingestion endpoint receives the expected service, environment, SDK metadata, and correlation fields. For version 2.0, it also forks the installed client and verifies exactly one child event without replaying the parent's buffered event.
|
|
442
|
-
|
|
443
464
|
## Examples
|
|
444
465
|
|
|
445
466
|
- Rack app: [examples/rack_app.rb](examples/rack_app.rb)
|
|
@@ -506,10 +527,19 @@ label. Check the deployed SDK/wrapper version, instrumentation, scope, expiry,
|
|
|
506
527
|
policy, sampling and delivery receipts. See the [probe recipes](https://debugbundle.com/docs/probes#bounded-checkpoint-recipes).
|
|
507
528
|
|
|
508
529
|
|
|
509
|
-
|
|
530
|
+
<a id="unreleased-acceptance-credential-privacy"></a>
|
|
531
|
+
|
|
532
|
+
### Acceptance-credential privacy
|
|
510
533
|
|
|
511
|
-
The
|
|
534
|
+
The SDK scrubs standalone `dbundle_invite_`,
|
|
512
535
|
`dbundle_org_invite_` and `dbundle_org_transfer_` acceptance secrets before
|
|
513
536
|
SDK-owned retention or transmission. See the [shared qualification record](https://github.com/debugbundle/debugbundle/blob/main/spec/business-credential-redaction.md).
|
|
514
|
-
|
|
515
|
-
|
|
537
|
+
Existing installations receive this protection when upgraded to a version that includes it.
|
|
538
|
+
|
|
539
|
+
## Maintainer performance checks
|
|
540
|
+
|
|
541
|
+
`make evidence-performance` compares the same exception/recovery calls with
|
|
542
|
+
evidence disabled and enabled, including a full warning queue. It reports capture
|
|
543
|
+
time, allocated Ruby objects and retained bytes, and verifies original-error
|
|
544
|
+
priority and the existing queue/diagnostic ceilings. Setup and cleanup are excluded;
|
|
545
|
+
the existing `sdk-safety-perf` timing limits remain unchanged.
|
data/lib/debugbundle/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: debugbundle
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 2.1.
|
|
4
|
+
version: 2.1.3
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- DebugBundle
|
|
8
8
|
bindir: exe
|
|
9
9
|
cert_chain: []
|
|
10
|
-
date: 2026-11-
|
|
10
|
+
date: 2026-11-15 00:00:00.000000000 Z
|
|
11
11
|
dependencies:
|
|
12
12
|
- !ruby/object:Gem::Dependency
|
|
13
13
|
name: base64
|