Sending Events to Insights

Honeybadger's Ruby gem (v5.11+) can be used to send events to Insights.

Automatic Instrumentation

You can instrument your Ruby and Rails apps by enabling the automatic instrumentation in your honeybadger.yml configuration file:

yaml

insights:
  enabled: true

Event Captures

Enabling automatic instrumentation will send the following events to Honeybadger, where they will be displayed in the Insights section of your project:

Plugin	Event Type (`event_type::str`)
`rails`	`process_action.action_controller`
	`send_file.action_controller`
	`redirect_to.action_controller`
	`halted_callback.action_controller`
	`unpermitted_parameters.action_controller`
	`write_fragment.action_controller`
	`read_fragment.action_controller`
	`expire_fragment.action_controller`
	`cache_read.active_support`
	`cache_read_multi.active_support`
	`cache_generate.active_support`
	`cache_fetch_hit.active_support`
	`cache_write.active_support`
	`cache_write_multi.active_support`
	`cache_increment.active_support`
	`cache_decrement.active_support`
	`cache_delete.active_support`
	`cache_delete_multi.active_support`
	`cache_cleanup.active_support`
	`cache_prune.active_support`
	`cache_exist?.active_support`
	`exist_fragment?.action_controller`
	`render_template.action_view`
	`render_partial.action_view`
	`render_collection.action_view`
	`sql.active_record`
	`process.action_mailer`
	`service_upload.active_storage`
	`service_download.active_storage`
`active_job`	`enqueue_at.active_job`
	`enqueue.active_job`
	`enqueue_retry.active_job`
	`enqueue_all.active_job`
	`perform.active_job`
	`retry_stopped.active_job`
	`discard.active_job`
`sidekiq`	`perform.sidekiq`
	`enqueue.sidekiq`
`karafka`	`consumer.consumed.karafka`
	`error.occurred.karafka`
`net_http`	`request.net_http`
`autotuner`	`report.autotuner`
`system`	`report.system`

To find these events, filter by event_type::str using any of the types above. Here's an example BadgerQL query that you can use:

  

fields @ts, @preview
| filter event_type::str == "perform.sidekiq"
| sort @ts

Disabling Insights for a Specific Plugin

When Insights is active, all plugins are enabled if the required library is present. For example, if Sidekiq is present in your app, the Sidekiq plugin will be loaded. You can disable automatic Insights instrumentation for a specific plugin by adding a configuration like this:

yaml

sidekiq:
  insights:
    enabled: false

This will only affect Insights-related data capture and not the error notification portion of the plugin.

Some plugins allow for an easy way to choose if you want to capture events, metrics, or both for a particular plugin. The following configuration options are available:

yaml

  

rails:
  insights:
    events: true
    metrics: false
karafka:
  insights:
    events: true
    metrics: false
sidekiq:
  insights:
    events: true
    metrics: false
net_http:
  insights:
    events: true
    metrics: false

Event options are all true by default. It is recommened to turn off events for plugins that may be producing more data than you actually need. Metric data collection is false by default since most metrics can be calculated from events.

By default, the net_http plugin logs the domain name of any request as part of the event payload. You can enabling logging of the full URL by setting the following configuration:

  

net_http:
  insights:
    full_url: true

Ignoring Events

For some applications, certain default events may be unecessary or excessively data heavy. To specify events to ignore, use the events.ignore configuration option. Here you can specify a list of event types for the gem to ignore. They can be either a string or a regex.

yaml

  

events:
  ignore:
    - 'enqueue.sidekiq'
    - !ruby/regexp '/.*.active_storage/'

You may also ignore events based on event data by specifying a hash object.

yaml

  

events:
  ignore:
    - event_type: 'chatty_events'
      custom_data: 'ignore_me'

This will ignore events that have been created with the matching key symbols:

ruby

Honeybadger.event('chatty_events', custom_data: 'ignore_me') # will not be sent to Insights

You can also use the before_event callback to inspect or modify event data, as well as calling halt! to prevent the event from being sent to Honeybadger:

ruby

  

# config/initializers/honeybadger.rb
Honeybadger.configure do |config|
  config.before_event do |event|
    # Ignore health check requests
    if event.event_type == "process_action.action_controller" && event[:controller] == "Rails::HealthController"
      event.halt!
    end

    # DB-backed job backends can generate a lot of useless queries
    if event.event_type == "sql.active_record" && event[:query].match?(/good_job|solid_queue/)
      event.halt!
    end
  end
end

before_event can be called multiple times to add multiple callbacks.

Default Ignored Events

The gem comes configured to ignore a few events that can be chatty and not useful:

sql.active_record events with queries that contain only "BEGIN" or "COMMIT".
sql.active_record events for database backed background processing gems (SolidQueue and GoodJob).
process_action.action_controller events for Rails::HealthController actions.

Manually Sending Events

You can also send events to Honeybadger using the Honeybadger.event method:

ruby

  

Honeybadger.event('user_activity', {
  action: 'registration',
  user_id: 123
})

The first argument is the type of the event (event_type) and the second argument is an object containing any additional data you want to include.

Honeybadger.event can also be called with a single argument as an object containing the data for the event:

ruby

  

Honeybadger.event({
  event_type: 'user_activity',
  action: 'registration',
  user_id: 123
})

A timestamp field (ts) will be automatically added to the event data if it is not provided, regardless of the method used to send the event.

These events may be found using the following BadgerQL query:

  

fields @ts, @preview
| filter event_type::str == "user_activity"
| filter action::str == "registration"
| sort @ts

More Automatic Instrumentation

The Honeybadger Ruby gem does more than just send events when they occur in your app. When you enable Insights, you also enable automatic metric collection. Check out Collecting and Reporting Metrics for more information.

Sending Rails Logs to Insights

If you are already using the Rails logger to track events in your application, you can send those events to Insights by using a structured logging gem.