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:

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:

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:

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.

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

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

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:

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:

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:

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:

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:

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.

Caution

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):

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:

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:

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:

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.