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 applications by enabling Insights 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`
	`stats.sidekiq`
`solid_queue`	`stats.solid_queue`
`karafka`	`consumer.consumed.karafka`
	`error.occurred.karafka`
	`statistics_emitted.karafka`
`net_http`	`request.net_http`
`autotuner`	`report.autotuner`
	`stats.autotuner`
`system`	`report.system`
`puma`	`stats.puma`

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

Customizing 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
solid_queue:
  insights:
    events: true
    metrics: false
puma:
  insights:
    events: true
    metrics: false
autotuner:
  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 event_type and key(symbol)/value:

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.

Sampling events

If you find that you'd like to report fewer events in order to minimize your quota consumption, you can conditionally send a certain percentage of events:

yaml

# config/honeybadger.yml
insights:
  sample_rate: 10

This will send 10% of events not associated with a request, and all events for 10% of requests.

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

Event Context

You can add custom metadata to the events sent to Honeybadger Insights by using the Honeybadger.event_context method. This metadata will be included in each event sent within the same thread.

Warning

This will add the metadata to all events sent, so be careful not to include too much data. Try to keep it to simple key/value pairs.

For example, you can add user ID information to all events (via a Rails controller):

ruby

  

class ApplicationController < ActionController::Base
  before_action :set_honeybadger_context

  private

  def set_honeybadger_context
    if current_user
      Honeybadger.event_context(user_id: current_user.id, user_email: current_user.email)
    end
  end
end

Event context is not automatically propagated to other threads. If you want to add context to events in a different thread, you can use the Honeybadger.get_event_context method to get the current context and pass it to the Honeybadger.event method:

ruby

  

class MyJob < ApplicationJob
  def perform(user_id)
    # Get context from the main thread
    context = Honeybadger.get_event_context

    Thread.new do
      # Set the context in the new thread
      Honeybadger.event_context(context)

      # Do some work here
      Honeybadger.event("background_work", { user_id: user_id, status: "completed" })
    end
  end
end

Block-Scoped Context

You can also set event context for a specific block of code using a block form:

ruby

  

Honeybadger.event_context(user_id: 123) do
  # All events within this block will include the user_id context
  Honeybadger.event("user_action", { action: "login" })
  Honeybadger.event("user_action", { action: "logout" })
end
# Context is automatically cleared after the block

Clearing Event Context

You can clear the current event context at any time:

ruby

Honeybadger.event_context.clear!

Metrics

The Honeybadger Ruby gem does more than just send events when they occur in your app. You can also enable 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.