Sending custom events

You can send your own application events to Honeybadger Insights using the Honeybadger.event method. (For the events the gem captures on its own — web requests, database queries, background jobs, and more — see Automatic instrumentation.)

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. Payloads can include nested hashes and arrays, and are sanitized the same way error context is.

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

Naming events

The event_type is how you’ll filter for these events in every query, so stable, descriptive names pay off. Dot-namespaced names group related events and read naturally in queries: payment.completed, payment.refunded, export.finished. The gem’s own events follow the same convention (sql.active_record, perform.sidekiq).

Fields added automatically

The gem adds a few fields to every event before sending:

Field	Type	Description
ts	string<date-time>	Event timestamp (ISO 8601, UTC). Added unless you provide your own.
request_id	string	Rails request ID, when the event is sent during a web request. Correlates your events with the gem’s automatic events from the same request.
hostname	string	Server hostname. Disable with the events.attach_hostname configuration option.
environment	string	Deploy environment. Disable with the events.attach_environment configuration option.

Fields set via Event context — user IDs, tenant IDs, and other per-request metadata — are also merged into every event.

Delivery

Honeybadger.event doesn’t block: events are queued in memory and sent in batches — when 1,000 events accumulate or every 30 seconds, whichever comes first. The queue holds up to 100,000 events; batch size, timeout, and queue limits are configurable.

When the process exits, the gem sends any remaining queued events (send_data_at_exit, on by default). For cases where you need delivery before continuing — a short-lived script that must not exit early, or work that follows immediately — Honeybadger.flush sends everything queued:

Honeybadger.flush do
  records.each { |r| Honeybadger.event("import.row_processed", id: r.id) }
end

Finding your events

Filter by the event_type you chose:

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

See the BadgerQL guide for aggregations, grouping, and the rest of the query language.

Managing event volume

If some events are noisy or you’d like to reduce quota consumption:

• Filtering events — ignore specific event types, or inspect and halt events with a callback.
• Sampling events — send only a percentage of events.