Documentation

Check out our guides and API reference documentation on how to use Rollbar to monitor, debug, and triage errors.

Guides & SDKs    API Reference

Rollbar Query Language (RQL) provides a rich SQL-like interface to the data in Rollbar.

RQL supports running SELECT queries on two logical tables, item_occurrence and deploy. Basic GROUP BY, ORDER BY, LIMIT, and aggregation functions are available, as are arbitrary expressions in the WHERE clause.

Syntax

SELECT, FROM, and WHERE are required. GROUP BY, ORDER BY, and LIMIT are optional.

SELECT * may be used as long as there is no GROUP BY clause. It will return a list of columns similar to the Occurrences tab on Item Detail pages.

Function expressions in GROUP BY are supported only when the same expression is present in the SELECT clause. You can also simply reference a selected column using its index, e.g. GROUP BY 1.

SQL keywords and built-in function names are case-insensitive (i.e. SELECT and select are both fine).

Column names should start with a lowercase letter and may contain letters, numbers, and periods (for specifying a JSON path). If you need any other characters (i.e. a hyphen, or to start with an uppercase letter), escape with backticks (i.e. `request.headers.User-Agent`).

Operators

  • +, -, /, *, DIV, MOD
  • AND, OR, NOT
  • =, !=,
    <>, >, >=, <, <=, IN, NOT IN, BETWEEN,
    NOT BETWEEN, LIKE, NOT LIKE

Built-in Functions

  • count(*): counts all rows
  • count(foo): counts rows where foo is not null
  • count_distinct(foo): counts distinct rows where foo is not null
  • sum(foo): sums value of foo (for rows where not null)
  • avg(foo): average value of foo (for rows where not null)
  • min(foo): minimum value of foo
  • max(foo): maximum value of foo
  • unix_timestamp(): returns the current Unix timestamp, as an integer
  • concat(str1, str2, ...): returns the string resulting from concatenating all arguments
  • concat_ws(sep, str1, str2, ...): returns the string resulting from concatenating the second argument and beyond, separated by the first argument
  • lower(str): converts str to lowercase
  • upper(str): converts str to uppercase
  • left(str, len): returns the len leftmost characters of str
  • right(str, len): returns the len rightmost characters of str
  • substring(str, pos): returns the substring from str starting at pos (all characters from pos until the end)
  • substring(str, pos, len): returns a substring from str starting at pos, at most len characters
  • locate(substr, str): returns the position of the first occurrence of substr in str. (1-indexed)
  • locate(substr, str, pos): returns the position of the first occurrence of substr in str, starting the search at position pos
  • char_length(str): returns the length of str in characters
  • length(str): returns the length of str in bytes
  • if(boolean_expr, value_if_true, value_if_false): evaluates to value_if_true if the expression boolean_expr evalutes to true, value_if_false otherwise

Examples

To find all occurrences of item #47, grouped by request.user_ip with the total count, earliest timestamp, and most recent timestamp, ordered by total count descending and limited to the top 10 rows:

SELECT request.user_ip, min(timestamp), max(timestamp), count(*)
FROM item_occurrence
WHERE item.counter = 47
GROUP BY request.user_ip
ORDER BY count(*) DESC
LIMIT 10

To see the timestamp and message for all occurrences for Items #40 to #50:

SELECT timestamp, body.message.body
FROM item_occurrence
WHERE item.counter BETWEEN 40 AND 50

To see the occurrences of Items #1, 2, and 3:

SELECT *
FROM item_occurrence
WHERE item.counter IN (1,2,3)

To find items that affected the most IPs in the last 3 days, grouped by the item number and ordered by the distinct count of the number of user_ips descending:

SELECT item.counter
FROM item_occurrence
WHERE timestamp > unix_timestamp() - 60 * 60 * 24 * 3
GROUP BY item.counter
ORDER BY count_distinct(request.user_ip) desc

To see all the items with the User-Agent string "python-requests/2.9.1" in a date range, ordered by timestamps descending:

SELECT * 
FROM item_occurrence 
WHERE `request.headers.User-Agent` = "python-requests/2.9.1"  
AND timestamp BETWEEN 1507566716 and 1510245116 
ORDER BY timestamp desc

To grab all the referrer domains an Item #1234 came from, grouped by the domain and limited to the top 1000 rows:

SELECT substring(request.headers.Referer, locate('.', request.headers.Referer), locate('.', request.headers.Referer, locate('.', request.headers.Referer)) - locate('.', request.headers.Referer) - 1)
FROM item_occurrence
WHERE item.counter = 1234
GROUP BY 1
LIMIT 1000

To find all the occurrences of items that occurred on Safari version 9.x in the last day:

SELECT *
FROM item_occurrence
WHERE client.javascript.browser LIKE '%Version/9.%.% Safari/%'
AND timestamp > unix_timestamp() - 60 * 60 * 24

To grab the occurrence counts per item per day for the last three days:

SELECT timestamp div 86400, item.counter, count(*)
FROM item_occurrence
WHERE timestamp > unix_timestamp() - 60 * 60 * 24 * 3
GROUP BY 1, item.counter

Tips

  • Use SELECT * FROM item_occurrence to get a display similar to the Occurrences tab
  • For better performance, filter by item (i.e. WHERE item.counter = 123) or by timestamp (i.e. WHERE timestamp > unix_timestamp() - 86400)
  • RQL will sometimes timeout unless you put a date range, such as WHERE timestamp > unix_timestamp() - 86400.
  • When using GROUP BY or ORDER BY, make sure the group/order clause is also present in the SELECT clause.
  • You cannot GROUP BY a function unless the same expression is present in the SELECT clause.
  • You can reference a column by its index in a GROUP BY, for example GROUP BY 1.
  • You can share the URL with a co-worker and they'll see the same results you do, without having to run the query again.
  • After a query has completed, press Execute again to re-run it.

Limitations

  • At most 1000 rows will be returned per query (though any number of rows may be examined)
  • No DISTINCT, HAVING, subqueries, joins, or unions
  • No ANY, ALL, EXISTS
  • SELECT * cannot be combined with GROUP BY
  • You cannot GROUP BY a function unless the same expression is present in the SELECT clause.
  • Can only be used to examine data within a single project

Schema

item_occurrence

item_occurrence is a table where each row contains data for a single occurrence and the item it is associated with. Column names starting with "item." reference the item, and all other column names reference the occurrence. Column names that do not exist in a particular occurrence evaluate to NULL.

The following columns exist for every row in item_occurrence:

NameDescription
item.idSystem-wide Item ID
item.counterProject-wide Item ID
item.environmentEnvironment name
item.platformPlatform ID
item.frameworkFramework ID
item.hashComputed fingerprint of the item (controls grouping)
item.first_occurrence_idID of the first occurrence
item.first_occurrence_timestampTimestamp of the first occurrence
item.activating_occurrence_idID of the first occurrence since the item was last resolved
item.last_activated_timestampTimestamp the item was last activated
item.last_resolved_timestampTimestamp the item was last resolved
item.last_muted_timestampTimestamp the item was last muted
item.last_occurrence_idID of the most recent occurrence
item.last_occurrence_timestampTimestamp of the most recent occurrence
item.last_modified_byID of the user who last modified this item
item.assigned_user_idID of the user who this item is assigned to
item.levelItem level (50=critical, 40=error, 30=warning, 20=info, 10=debug)
item.resolved_in_versionThe revision the item was last marked as resolved in
item.statusStatus (as an integer: 1=active, 2=resolved, 3=muted)
item.titleComputed title
item.total_occurrencesThe number of occurrences since the last time this item was resolved
occurrence_idSystem-wide Occurrence ID
project_slugThe project's slug
timestampTimestamp of the occurrence, as a Unix timestamp

Many virtual columns will usually exist as well, depending on which Rollbar SDK you are using and what custom data you are sending. Simply use the JSON path to the field you want to query. To see the JSON structure of one of your occurrences, click the "Raw JSON" button on an Occurrence page. The structure will follow the Rollbar API Item Schema.

📘

When querying a virtual column, make sure to wrap it in backticks, e.g.

`request.headers.User-Agent`="python-requests/2.9.1"

Here are some common column names, all of which refer to data for the occurrence:

NameDescription
body.crash_report.rawThe raw crash report (if the occurrence is a crash report)
body.message.bodyThe primary message text (if the occurrence is a message)
body.message.fooAny arbitrary keys of metadata you sent (if the occurrence is a message)
body.trace.exception.classThe exception class name (if the occurrence is a single exception)
body.trace.exception.messageThe exception message (if the occurrence is a single exception)
body.trace_chain.0.exception.classThe first exception class (if the occurrence is a list of nested exceptions)
body.trace_chain.0.exception.messageThe first exception message (if the occurrence is a list of nested exceptions)
client.javascript.browserRaw user agent string (from rollbar.js)
client.javascript.code_versionThe running code version in JavaScript
client.javascript.source_map_enabledWhether or not source map deobfuscation is enabled
client.javascript.guess_uncaught_framesWhether or not frame guessing is enabled
client.runtime_msHow long the page was open before the event occurred (rollbar.js)
code_versionThe version of the application code
contextAn identifier for which part of your application the error came from
custom.fooArbitrary metadata you sent
custom.foo.barNested arbitrary metadata you sent
languageThe name of the reported language for the event
notifier.nameName of the library that sent the item
notifier.versionThe version string of the library that sent the item
person.idA string identifying the user in your system
person.usernameA username string
person.emailAn email string
request.urlFull URL where the error occurred
request.methodThe request method
request.headersObject containing the request headers
request.paramsAny routing parameters
request.GETQuery string parameters
request.query_stringThe raw query string
request.POSTPOST parameters
request.bodyThe raw POST body
request.user_ipThe end user's IP address as a string
server.hostThe server hostname
server.rootPath to the application code root
server.branchName of the checked-out source control branch
server.code_versionString describing the running code version on the server
uuidA string that uniquely identifies the occurrence. See UUIDs

deploy

deploy is a table where each row represents a single deploy. It has the following columns:

NameDescription
idSystem-wide ID
user_idRollbar user_id of the rollbar_username recorded for the deploy
environmentName of the deployed environment
revisionRevision (i.e. git sha or version number) deployed
local_usernameLocal username recorded for the deploy
commentThe deploy comment
timestampTimestamp when the deploy was recorded
project_slugThe project's slug

Constants

Framework IDs

The item.framework property is an integer value which maps as follows:

'unknown': 0,
    'rails': 1,
    'django': 2,
    'pyramid': 3,
    'node-js': 4,
    'pylons': 5,
    'php': 6,
    'browser-js': 7,
    'rollbar-system': 8,  # system messages, like "over rate limit"
    'android': 9,
    'ios': 10,
    'mailgun': 11,
    'logentries': 12,
    'python': 13,
    'ruby': 14,
    'sidekiq': 15,
    'flask': 16,
    'celery': 17,
    'rq': 18,

Platform IDs

The item.platform property is an integer value which maps as follows:

'unknown': 0,
    'browser': 1,
    'flash': 2,
    'android': 3,
    'ios': 4,
    'heroku': 5,
    'google-app-engine': 6,
    'client': 7,

Future Improvements

  • DISTINCT, HAVING clauses
  • More performance optimizations
  • More functions
  • Better progress indicators
  • Saved searches
  • More visualization options (i.e. bar graphs, line graphs, etc.)
  • Download results as CSV/JSON dump (with support for large resultsets)
  • More data tables

Updated 7 months ago

RQL


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.