Class: Dispatch::Rails::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/dispatch/rails/configuration.rb

Constant Summary collapse

MODES =

Install mode. :widget is the default (a UI app embeds the bug-report button); :errors_only is for API-only / headless apps that have no UI to render into — server-side exception capture and manual reporting still work, but the widget and browser-error tags become no-ops.

%i[widget errors_only].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/dispatch/rails/configuration.rb', line 28

def initialize
  @api_key = nil
  @endpoint = "https://dispatchit.app/api/v1/tickets"
  @user = ->(_ctx) { nil }
  @metadata = ->(_ctx) { {} }
  @capture_console = false
  @capture_clicks = true # track the last few clicks as a "user path" for context
  @button_position = "bottom-right"

  # Mode + API-only context
  @mode = :widget
  @context = ->(_ctx) { {} } # extra tags resolved from the controller (API key user, headers, …)
  @send_default_params = false # opt-in: include Rails' filtered_parameters in the event

  # Exception tracking defaults
  @capture_exceptions = true
  @capture_browser_errors = true
  @error_endpoint = nil # derived from endpoint when nil
  @environment = nil    # derived from Rails.env when nil
  @release = nil        # e.g. ENV["GIT_SHA"]
  @enabled_environments = %w[production staging]
  @error_sample_rate = 1.0
  @before_send = nil    # ->(event) { event or nil to drop }

  # Process lifecycle. Report the exception killing the process (a crash
  # during boot, a dying runner) and drain the send queue before exit so
  # deploys/restarts don't drop captured events.
  @capture_at_exit = true
  @shutdown_timeout = 3 # seconds to wait for the queue to drain at exit; 0 skips the flush

  # Structured error responses (off by default — opt-in so we never alter a
  # host app's error contract without being asked).
  @structured_error_responses = false
  @annotate_error_body = false # headers-only unless explicitly enabled
  @report_base_url = nil       # derived from endpoint host when nil

  # Traffic heartbeats. On by default in enabled environments: aggregate
  # counts only (one small POST per flush window, regardless of request
  # volume), so the cost is negligible and the confound guard works out of
  # the box. Sampling is independent of error_sample_rate.
  @capture_traffic = true
  @traffic_sample_rate = 1.0
  @heartbeat_flush_seconds = 60
  @heartbeat_endpoint = nil # derived from endpoint when nil
end

Instance Attribute Details

#annotate_error_body ⇒ Object

Structured error responses (API-only)



22
23
24
 
# File 'lib/dispatch/rails/configuration.rb', line 22

def annotate_error_body
  @annotate_error_body
end

#api_key ⇒ Object

Bug-report widget



13
14
15
 
# File 'lib/dispatch/rails/configuration.rb', line 13

def api_key
  @api_key
end

#before_send ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def before_send
  @before_send
end

#button_position ⇒ Object

Bug-report widget



13
14
15
 
# File 'lib/dispatch/rails/configuration.rb', line 13

def button_position
  @button_position
end

#capture_at_exit ⇒ Object

Process lifecycle (crash-at-exit capture, rake failures, shutdown flush)



20
21
22
 
# File 'lib/dispatch/rails/configuration.rb', line 20

def capture_at_exit
  @capture_at_exit
end

#capture_browser_errors ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def capture_browser_errors
  @capture_browser_errors
end

#capture_clicks ⇒ Object

Bug-report widget



13
14
15
 
# File 'lib/dispatch/rails/configuration.rb', line 13

def capture_clicks
  @capture_clicks
end

#capture_console ⇒ Object

Bug-report widget



13
14
15
 
# File 'lib/dispatch/rails/configuration.rb', line 13

def capture_console
  @capture_console
end

#capture_exceptions ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def capture_exceptions
  @capture_exceptions
end

#capture_traffic ⇒ Object

Traffic heartbeats — per-transaction success counts that let the Dispatch server tell “the error stopped because we fixed it” from “…because the path went quiet” (the confound guard behind fix verification).



26
27
28
 
# File 'lib/dispatch/rails/configuration.rb', line 26

def capture_traffic
  @capture_traffic
end

#context ⇒ Object

Mode + API-only context



15
16
17
 
# File 'lib/dispatch/rails/configuration.rb', line 15

def context
  @context
end

#enabled_environments ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def enabled_environments
  @enabled_environments
end

#endpoint ⇒ Object

Bug-report widget



13
14
15
 
# File 'lib/dispatch/rails/configuration.rb', line 13

def endpoint
  @endpoint
end

#environment ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def environment
  @environment
end

#error_endpoint ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def error_endpoint
  @error_endpoint
end

#error_sample_rate ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def error_sample_rate
  @error_sample_rate
end

#heartbeat_endpoint ⇒ Object

Traffic heartbeats — per-transaction success counts that let the Dispatch server tell “the error stopped because we fixed it” from “…because the path went quiet” (the confound guard behind fix verification).



26
27
28
 
# File 'lib/dispatch/rails/configuration.rb', line 26

def heartbeat_endpoint
  @heartbeat_endpoint
end

#heartbeat_flush_seconds ⇒ Object

Traffic heartbeats — per-transaction success counts that let the Dispatch server tell “the error stopped because we fixed it” from “…because the path went quiet” (the confound guard behind fix verification).



26
27
28
 
# File 'lib/dispatch/rails/configuration.rb', line 26

def heartbeat_flush_seconds
  @heartbeat_flush_seconds
end

#metadata ⇒ Object

Bug-report widget



13
14
15
 
# File 'lib/dispatch/rails/configuration.rb', line 13

def metadata
  @metadata
end

#mode ⇒ Object

Mode + API-only context



15
16
17
 
# File 'lib/dispatch/rails/configuration.rb', line 15

def mode
  @mode
end

#release ⇒ Object

Exception tracking



17
18
19
 
# File 'lib/dispatch/rails/configuration.rb', line 17

def release
  @release
end

#report_base_url ⇒ Object

Structured error responses (API-only)



22
23
24
 
# File 'lib/dispatch/rails/configuration.rb', line 22

def report_base_url
  @report_base_url
end

#send_default_params ⇒ Object

Mode + API-only context



15
16
17
 
# File 'lib/dispatch/rails/configuration.rb', line 15

def send_default_params
  @send_default_params
end

#shutdown_timeout ⇒ Object

Process lifecycle (crash-at-exit capture, rake failures, shutdown flush)



20
21
22
 
# File 'lib/dispatch/rails/configuration.rb', line 20

def shutdown_timeout
  @shutdown_timeout
end

#structured_error_responses ⇒ Object

Structured error responses (API-only)



22
23
24
 
# File 'lib/dispatch/rails/configuration.rb', line 22

def structured_error_responses
  @structured_error_responses
end

#traffic_sample_rate ⇒ Object

Traffic heartbeats — per-transaction success counts that let the Dispatch server tell “the error stopped because we fixed it” from “…because the path went quiet” (the confound guard behind fix verification).



26
27
28
 
# File 'lib/dispatch/rails/configuration.rb', line 26

def traffic_sample_rate
  @traffic_sample_rate
end

#user ⇒ Object

Bug-report widget



13
14
15
 
# File 'lib/dispatch/rails/configuration.rb', line 13

def user
  @user
end

Instance Method Details

#configured? ⇒ Boolean

Returns:

  • (Boolean) 


74
75
76
 
# File 'lib/dispatch/rails/configuration.rb', line 74

def configured?
  api_key.present? && endpoint.present?
end

#effective_environment ⇒ Object 



115
116
117
 
# File 'lib/dispatch/rails/configuration.rb', line 115

def effective_environment
  @environment.presence || (defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : "production")
end

#effective_error_endpoint ⇒ Object

Where exception events are posted. Defaults to the same host as the widget endpoint with the path swapped to the Sentry-compatible /store endpoint.



86
87
88
89
90
 
# File 'lib/dispatch/rails/configuration.rb', line 86

def effective_error_endpoint
  return @error_endpoint if @error_endpoint.present?

  endpoint.to_s.sub(%r{/[^/]+\z}, "/store")
end

#effective_heartbeat_endpoint ⇒ Object

Where per-transaction traffic rollups are posted. Defaults to the same host as the widget endpoint with the path swapped to /heartbeats.



109
110
111
112
113
 
# File 'lib/dispatch/rails/configuration.rb', line 109

def effective_heartbeat_endpoint
  return @heartbeat_endpoint if @heartbeat_endpoint.present?

  endpoint.to_s.sub(%r{/[^/]+\z}, "/heartbeats")
end

#effective_report_base_url ⇒ Object

The base URL (scheme + host) where the Dispatch tenant lives, used to build the human-facing report link surfaced in structured error responses. Falls back to the origin of ‘endpoint` (dispatchit.app).



95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/dispatch/rails/configuration.rb', line 95

def effective_report_base_url
  return @report_base_url.to_s.chomp("/") if @report_base_url.present?

  uri = URI.parse(endpoint.to_s)
  return nil if uri.host.nil?

  port = uri.port && ![80, 443].include?(uri.port) ? ":#{uri.port}" : ""
  "#{uri.scheme}://#{uri.host}#{port}"
rescue StandardError
  nil
end

#environment_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


129
130
131
132
 
# File 'lib/dispatch/rails/configuration.rb', line 129

def environment_enabled?
  list = Array(@enabled_environments).map(&:to_s)
  list.empty? || list.include?(effective_environment)
end

#error_tracking_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/dispatch/rails/configuration.rb', line 119

def error_tracking_enabled?
  configured? && @capture_exceptions
end

#errors_only? ⇒ Boolean

Returns:

  • (Boolean) 


78
79
80
81
82
 
# File 'lib/dispatch/rails/configuration.rb', line 78

def errors_only?
  mode.to_sym == :errors_only
rescue StandardError
  false
end

#traffic_tracking_enabled? ⇒ Boolean

Heartbeats piggyback on the same gating as error capture, plus their own toggle. Off in non-enabled environments (so dev/test never phone home).

Returns:

  • (Boolean) 


125
126
127
 
# File 'lib/dispatch/rails/configuration.rb', line 125

def traffic_tracking_enabled?
  @capture_traffic && error_tracking_enabled? && environment_enabled?
end