Module: Checkend

Defined in:
lib/checkend.rb,
lib/checkend/client.rb,
lib/checkend/notice.rb,
lib/checkend/worker.rb,
lib/checkend/testing.rb,
lib/checkend/version.rb,
lib/checkend/configuration.rb,
lib/checkend/notice_builder.rb,
lib/checkend/integrations/rack.rb,
lib/checkend/integrations/rails.rb,
lib/checkend/integrations/rails.rb,
lib/checkend/integrations/sidekiq.rb,
lib/checkend/filters/ignore_filter.rb,
lib/checkend/filters/sanitize_filter.rb,
lib/checkend/integrations/active_job.rb

Overview

Checkend is the main module for the Checkend Ruby SDK.

Use Checkend.configure to set up the SDK, then Checkend.notify to report errors.

Examples:

Basic configuration

Checkend.configure do |config|
  config.api_key = 'your-ingestion-key'
end

Reporting an error

begin
  # risky code
rescue => e
  Checkend.notify(e)
end

Defined Under Namespace

Modules: Filters, Integrations, Testing Classes: Client, Configuration, Notice, NoticeBuilder, Worker

Constant Summary collapse

VERSION = 
'1.0.0'

Class Method Summary collapse

Class Method Details

.clear! ⇒ Object

Clear all thread-local context



154
155
156
157
 
# File 'lib/checkend.rb', line 154

def clear!
  Thread.current[:checkend_context] = nil
  Thread.current[:checkend_user] = nil
end

.configuration ⇒ Configuration

Get the current configuration

Returns:



33
34
35
 
# File 'lib/checkend.rb', line 33

def configuration
  @configuration ||= Configuration.new
end

.configure {|Configuration| ... } ⇒ Configuration

Configure the Checkend SDK

Yields:

Returns:



41
42
43
44
45
 
# File 'lib/checkend.rb', line 41

def configure
  yield(configuration) if block_given?
  start! if configuration.valid?
  configuration
end

.context ⇒ Hash

Get the current thread-local context

Returns:

  • (Hash) —

    the context hash



127
128
129
 
# File 'lib/checkend.rb', line 127

def context
  Thread.current[:checkend_context] ||= {}
end

.current_user ⇒ Hash?

Get the current user

Returns:

  • (Hash, nil) —

    the user hash



149
150
151
 
# File 'lib/checkend.rb', line 149

def current_user
  Thread.current[:checkend_user]
end

.flush(timeout: nil) ⇒ Object

Flush pending notices, blocking until sent

Parameters:

  • timeout (Integer) (defaults to: nil) —

    seconds to wait



74
75
76
 
# File 'lib/checkend.rb', line 74

def flush(timeout: nil)
  @worker&.flush(timeout: timeout)
end

.logger ⇒ Logger

Get the logger

Returns:

  • (Logger) —

    the logger instance



177
178
179
 
# File 'lib/checkend.rb', line 177

def logger
  configuration.resolved_logger
end

.notify(exception, context: {}, request: nil, user: nil, fingerprint: nil, tags: []) ⇒ Hash?

Report an exception to Checkend

Parameters:

  • exception (Exception) —

    the exception to report

  • context (Hash) (defaults to: {}) —

    additional context data

  • request (Hash) (defaults to: nil) —

    request information

  • user (Hash) (defaults to: nil) —

    user information

  • fingerprint (String) (defaults to: nil) —

    custom fingerprint for grouping

  • tags (Array<String>) (defaults to: []) —

    tags for filtering

Returns:

  • (Hash, nil) —

    the API response or nil if not sent



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/checkend.rb', line 89

def notify(exception, context: {}, request: nil, user: nil, fingerprint: nil, tags: [])
  return nil unless should_notify?
  return nil if configuration.ignore_exception?(exception)

  notice = NoticeBuilder.build(
    exception: exception,
    context: context,
    request: request,
    user: user,
    fingerprint: fingerprint,
    tags: tags
  )

  # Run before_notify callbacks
  return nil unless before_notify_callbacks_allow?(notice)

  send_notice(notice)
end

.notify_sync(exception, **options) ⇒ Hash?

Report an exception synchronously (blocking)

Useful for CLI tools, tests, or when you need confirmation of delivery.

Parameters:

  • exception (Exception) —

    the exception to report

  • options (Hash) —

    same options as notify

Returns:

  • (Hash, nil) —

    the API response or nil if not sent



115
116
117
118
119
120
 
# File 'lib/checkend.rb', line 115

def notify_sync(exception, **options)
  return nil unless should_notify?

  notice = NoticeBuilder.build(exception: exception, **options)
  client.send_notice(notice)
end

.reset! ⇒ void

This method returns an undefined value.

Reset all SDK state (useful for testing)



162
163
164
165
166
167
168
169
170
 
# File 'lib/checkend.rb', line 162

def reset!
  stop!(timeout: 0) if @started
  @configuration = nil
  @client = nil
  @worker = nil
  @started = false
  @at_exit_installed = nil
  clear!
end

.set_context(hash) ⇒ Object

Set context data for the current thread

Parameters:

  • hash (Hash) —

    context data to merge



134
135
136
137
 
# File 'lib/checkend.rb', line 134

def set_context(hash)
  Thread.current[:checkend_context] ||= {}
  Thread.current[:checkend_context].merge!(hash)
end

.set_user(user_hash) ⇒ Object

Set user information for the current thread

Parameters:

  • user_hash (Hash) —

    user data (id, email, name, etc.)



142
143
144
 
# File 'lib/checkend.rb', line 142

def set_user(user_hash)
  Thread.current[:checkend_user] = user_hash
end

.start! ⇒ Object

Start the SDK (initialize client, worker, etc.)

Called automatically after configure if configuration is valid.



50
51
52
53
54
55
56
57
58
 
# File 'lib/checkend.rb', line 50

def start!
  return if @started

  @started = true
  @client = Client.new(configuration)
  @worker = Worker.new(configuration) if configuration.async
  install_at_exit_hook
  log_info("Started (environment: #{configuration.environment}, async: #{configuration.async})")
end

.stop!(timeout: nil) ⇒ Object

Stop the SDK and clean up resources

Parameters:

  • timeout (Integer) (defaults to: nil) —

    seconds to wait for pending notices



63
64
65
66
67
68
69
 
# File 'lib/checkend.rb', line 63

def stop!(timeout: nil)
  @worker&.shutdown(timeout: timeout)
  @worker = nil
  @started = false
  @client = nil
  log_info('Stopped')
end