Filtering

Many endpoints that return information about errors and events support a filters parameter which can be used to restrict the data returned.

Filter object

The filter object is a hash of Event Field keys containing an array of filter values. Each filter value has a type and a value to filter on. The type determines the type of comparison that will be performed.

Filters are composed of an array of hashes. Each hash contains a type and a value. Valid types are eq, ne, and empty, though not all Event Fields support filtering on all of these.

Any number of Event Fields can be supplied and results must match each event field (logical AND). Different filter values for an event field will combined according to the following rules.

Field value comparison

These compare whether an Event Field is equal (eq) or not equal (ne) to a given value. Filter values for each Event Field are combined logically as shown:

If ne filter types are supplied alongside eq, the ne are discarded to avoid a logically ambiguous combination.

Note that the ne type is not supported for the time based filters event.since and event.before.

Field emptiness

These filter based on the presence or absence of any value for a given field. The filter type is empty, and takes true or false values. If an ambiguous value is supplied it is assumed true.

Field emptiness filters combine with field value comparisons eq and ne as follows:

If both true and false values are supplied for a given Event Field, true will be preferred, except for Event Field error.assigned_to.

Encoding in URL parameters

The filters are generally sent as URL parameters. The object should be encoded as follows:

Event fields

Each project has a set of default Event Fields, which represent metadata captured on Error events. These are available to filter by plus any custom event fields that have been created via the API or any custom filters that have been added via the dashboard.

To find the available Event Fields on a project use List the Event Fields for a Project.

Time filters can either be supplied in ISO 8601 format or as relative times in the format <number><period>. If using ISO 8601, times must use the extended format and be in UTC (e.g. 2018-05-20T00:00:00Z). For relative times, the past seven days could be requested as 7d. Valid values for <period> are:

Filtering errors vs. filtering events

While any of a project's Event Fields can be passed as a filter to any endpoint that supports filtering, some fields are more applicable to Errors and others are more applicable to Events.

For example, an Event Field like error.status or error.assigned_to would make more sense when filtering at the Error level, since all Events grouped within a particular error would share the same status and assignee. Conversely, a filter like user.email or app.release_stage is applied at the Event level, since different Events within a particular Error may happen to different users or in different release stages.

If an endpoint that returns Errors is passed an Event-level filter, it will return Errors that include at least one Event that matches the filter. Event-level information within the Error, like the count of relevant Events, will reflect the filters applied.

Trace fields and Performance Filtering

Trace Fields are similar to Event Fields, but instead capture performance monitoring metadata as span attributes. These can be used for filtering spans in BugSnag.

To find available Trace Fields on a project, use List the Trace Fields for a Project.

As above, time filters can either be supplied in ISO 8601 format or as relative times in the format <number><period>. If using ISO 8601, times must use the extended format and be in UTC (e.g. 2018-05-20T00:00:00Z). For relative times, the past seven days could be requested as 7d. Valid values for <period> are:

Examples

Open errors with events in the last day

This example will filter for events of errors that have a status of open that occurred in the last day:

or as URL parameters:

Events affecting two specific users on a specific day

This example will filter for events that occurred for either user1@example.com or user2@example.com on January 1st, 2017:

or as URL parameters:

Events that have user data

This example will filter for any events that have a user ID:

or as URL parameters:

Errors that are new and aren't assigned to anyone

This example will filter for errors that have a status of new but are not assigned to a particular user.

or as URL parameters: