> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RUM explorer

> Search the sessions, views, actions, errors, requests, and long tasks of real users, draw them as numbers over time, ranked, in a table, or on a map, and open one row or a whole session.

The explorer lists the rows that real users left, one type at a time. Find them with a field query,
count them over time, and open a row without leaving the list. Open **RUM → Explorer**. Reading RUM data
requires `streams.query`.

A workspace that has no [application](https://docs.molesignal.com/en-US/rum/applications.md) yet shows how to create one instead.

## Types of rows

The tabs under the title choose what a row is. A row is the latest version of its entity: a view that was reported
many times appears once, with its last counts.

| Tab | A row is | The histogram marks |
| - | - | - |
| **Sessions** | One session, derived from its views: user, landing page, duration, counts of views, actions, and errors, browser, and country. | Sessions with errors |
| **Views** | One page view or screen: loading time, Web Vitals, and counts. | Views with errors |
| **Actions** | One click, tap, or custom action. | Actions with frustration |
| **Errors** | One error: message, type, source, handling, and stack. | — |
| **Resources** | One request: method, URL, status, duration, size, and trace. | Failed requests, with a status of `400` or more, or `0` |
| **Long tasks** | One long animation frame, long task, or frozen frame. | — |

## Write a query

The query editor opens folded. Select **Expand query editor**, or **Code** or **Builder**, to open it.

**Code** takes a field query: comparisons of the fields of the open type, joined by `AND`.

| Field query | Meaning |
| - | - |
| `usr.id = 'u-42'` | The field has exactly this value. |
| `view.url_path contains 'checkout'` | The field contains the text. |
| `browser.name != 'Safari'` | The field has another value. |
| `resource.duration >= 1000000000` | A number compares with `=`, `!=`, `>`, `>=`, `<`, and `<=`. |
| `error.issue_id = '3f9c2a71e0b4c8d1'` | The errors of one [issue](https://docs.molesignal.com/en-US/rum/errors.md). |
| `error.fingerprint = ''` | An empty value asks whether the field has no value. `!= ''` asks whether it has one. |

Durations are stored in **nanoseconds**, so `1000000000` is one second. The cell of a table shows them in the unit that fits.

Words that are not comparisons are looked for in the text columns of the open type, such as the user, the page, the
error message, and the request URL. A comparison on a field that the type does not have, or on a field that holds a
JSON document, is ignored and shown as **Ignored**.

**Builder** shows the same query as filters. Select **Filter**, then choose a field, a comparison, and a value.

Run the query with **Run query**, or press `⌘ Enter` or `Ctrl+Enter` in the editor. **Refresh** reads the results
again. The time range sits next to the run button. The explorer opens on the last 24 hours.

## Fields

The **Fields** list beside the results has every field of the open type, in three groups: **Displayed fields**,
the columns of the table; **Indexed fields**, which filter without reading every row; and **Other fields**. Type in
**Find a field** to narrow the list.

* Click the name of a field to list its most common values with their counts, over the rows the query matches.
* **Filter for this value** and **Filter out this value** add the comparison to the query. Select a value that is already
  filtered to remove the filter.
* The eye of a field adds it to the table or removes it. **Back to the default columns** resets the table.
* The plus button of a field starts a comparison on it in the query.

## Results and the histogram

The table shows one row for each result, newest first, with the time of the row first. A row that went wrong is
marked down its left edge. Choose the page size, 100, 200, 500, 1,000, 2,000, or 5,000 rows, and move with
**Previous** and **Next**.

The histogram above the table counts **every** row the query matches over the time range, not only the loaded page,
and says how many rows each bar stands for. Drag across the bars to narrow the time range. Select **Hide histogram** to
close it; the choice is kept.

## Draw the rows as numbers

**Visualize as**, above the results, chooses how the rows the query matches are drawn. **List** is the table of rows and
opens by default. The other four are numbers counted over **every** row the query matches in the time range, not over the
loaded page, so they agree with the list beside them.

| Way | Draws | Takes |
| - | - | - |
| **Timeseries** | One number over time. A percentile, an average, a lowest, or a highest is a line; a count or a sum is a bar, stacked by group. | One measure, up to two groups, up to 20 series |
| **Top list** | The groups ranked by one number, each a bar with the number after it. | One measure, one group |
| **Table** | A row for each group and a column for each number. | Up to six measures, up to two groups |
| **Map** | The countries on a map of the world, each tinted by its number next to the largest. | One measure; the rows are grouped by `geo.country_iso_code` |

The map zooms from the whole world to eight times. Use the buttons at its corner, the wheel or a pinch (about the pointer),
or a double click, and drag a zoomed map to move it. With the map in focus, `+` and `-` zoom, `0` shows the whole world,
and the arrow keys move a zoomed map. A country that is too small to be seen, such as Singapore or Malta, is marked
where it lies. Point at a country to read what it came to. The outlines are Natural Earth's 1:10m country boundaries,
simplified, in the worldview of China, without Antarctica. Taiwan, Hong Kong, and Macao are parts of China: Taiwan is a
piece of its own with no border about it, so that its rows are tinted apart. The availability map of
[Synthetics](https://docs.molesignal.com/en-US/synthetics.md) draws the same shapes.

Select a group of a top list or a table to narrow the query to it, and select it again to let go. Select a head of a table
to order by it: the server ranks by that column, so the rows are the first of that order, not the first of another order
sorted. Click a timeseries to pin its tooltip: **Include** and **Exclude** in it narrow the query to the series under the pointer, or
leave it out. Dragging across the chart narrows the time range, as on the histogram.

When the number is a level of **Largest Contentful Paint**, **Interaction to Next Paint**, or **Cumulative Layout Shift**, the
chart is drawn in seconds, in milliseconds, or as a score, with two dashed lines where the vital turns from good to poor
(2.5 s and 4 s, 200 ms and 500 ms, 0.1 and 0.25), and the numbers of a top list or a table are coloured by their grade.

### What is counted

The row under the query appears when the rows are drawn as numbers. Each change applies at once.

* **Measure** is a function of a field. `count` counts rows. `count_distinct` counts the different values of a field, such as
  `session.id` or `usr.id`. `sum`, `avg`, `min`, `max`, `p50`, `p75`, `p90`, `p95`, and `p99` take a numeric field, and the
  percentiles are estimates. A duration is stored in nanoseconds and is shown in the unit that fits. Select a measure to
  change it; select **Measure** to add one to a table.
* **Group by** tells the rows apart by the values of a field, and **Then by** by a second. A row that has no value in the field
  is counted under **(none)**. A measurement, a time, and a JSON document cannot be grouped by.
* **Bucket** is how long one point of a timeseries is. **Auto** cuts the range into about thirty points, each beginning on a
  multiple of its length on the clock of the page. Only the lengths that cut the range into two to 300 points are offered.
* **Top** is how many groups are drawn: 3 to 20 in a timeseries, 5 to 100 in a top list or a table.

The explorer counts the rows that were kept. When the application [keeps only a share of its sessions](https://docs.molesignal.com/en-US/rum/sampling.md),
the pages that show totals scale them up to every session, and the explorer does not: its list, its histogram, and what it
draws count the rows as they are stored.

A top list and a table open on the field their type is most often ranked by: the browser for sessions, the page for views and
long tasks, the target for actions, the error type for errors, and the host for resources. A timeseries opens on a count of the
rows, not grouped. If the numbers cannot be counted within the time budget, the explorer says **Not available** where they
would be; narrow the time range or the query and run it again.

The way of drawing and what is counted are in the address, so a copy of the address bar shares the chart: `viz` is
`timeseries`, `toplist`, `table`, or `map` (the list leaves it out); `m` is a measure, as `count` or
`p75:view.performance.lcp.timestamp`, once for each; `by` is a group field, once for each; `bucket` is a length such as `5m` or
`1h`; `top` is the number of groups; and `sort` and `dir` order a table. Changing the type keeps the way of drawing and
drops `m`, `by`, and `sort`, which belong to the fields of one type. The numbers are read with
[`aggregate`](https://docs.molesignal.com/en-US/api/rum#measure-rows).

## Open a row

Click a row, or move with the arrow keys and press `Enter`, to open it in a drawer beside the list. The drawer shows the
facts the type is told by, then every field of the row, and the stack of an error. Drag its left edge to resize it.

* `J` and `K`, or the arrows in the head, move to the next and the previous row of the list.
* **Open the session** opens the session the row belongs to.
* A view of a browser opens wide, on **Load waterfall**: the requests it made and the long tasks that blocked it, on one time
  axis from its start. Its fields are in the next section. See [the load of a view](https://docs.molesignal.com/en-US/rum/performance.md#the-load-of-a-view).
* Closing the drawer gives the focus back to the row.

## Open a session

The session page opens from the explorer. It shows:

* the **Replay player** when the session recorded a DOM replay, or the **Action timeline** when it did not. The ruler of the replay
  has a tick for each error (red), for each action that showed a sign of frustration (orange), and for each page after the first
  (grey);
* the **Developer tools** under the replay: **Errors**, **Network**, and **Performance**, described below;
* **User context**: the user, the device, the location, the IP address, the application, the environment, the version, and
  the duration;
* **Pages**: the first and the last page of the visit, and **Detected issues**: errors, crashes, frustration signals, and
  long tasks;
* the **Event timeline**: every view, action, request, error, and long task of the session in the order it happened;
* **Related traces**: the backend traces whose ID a request of the session carried (**Direct**), or, when no request carried
  one, the traces that ran while the session did (**Time-correlated**). Each trace opens on **Traces**.

The head of a trace on **Traces** offers **User session** when a request of a session carried the ID of the trace.

The head of the session offers **Copy link to this moment**, which copies the address with the replay at the moment it is at, and
**Add to playlist**, which puts the session in a [playlist](https://docs.molesignal.com/en-US/rum/playlists.md).

### Developer tools

Under the replay are three tabs, each with a count: **Errors**, **Network**, and **Performance**. They read the events of the
session itself, and they follow the replay.

* The row the replay is at, which is the last that had happened by its moment, is lit with a line at its left. The list scrolls to
  keep it in sight as the replay plays or is moved, and the page under it stays where it is.
* A row moves the replay to its moment and pauses it. Times are minutes and seconds from the beginning of the recording, the ruler of
  the progress bar. A session that recorded no replay has nothing to follow or to move: its times run from the start of the session,
  and a row only tells what happened.
* **Errors** lists the errors of the session in the order they happened: the time, the type, the message, and the issue the
  error was grouped into, which opens on [Errors](https://docs.molesignal.com/en-US/rum/errors.md). The tab is the one the tools open on when the session
  ran into an error, and **Network** is the one when it did not.
* **Network** lists the requests of one view: the time, the method, the host and the path, the status, the kind, the time taken, and
  the size, with a bar for each on the time the requests of the view took. **View** chooses the view. Until one is chosen it is the
  one the replay is in, and **Follow the replay** gives it back. **All views** lists every request of the session. **Show** narrows
  the list to the slow requests (500 ms or more) or the ones that failed. **Waterfall** shows the load of the view as the explorer
  does (see [the load of a view](https://docs.molesignal.com/en-US/rum/performance.md#the-load-of-a-view)).
* **Performance** has a row for each view of the session: LCP, INP, and CLS in the colour of their grade, and how many requests and
  long tasks the view met. A row opens the waterfall of its view in **Network**.

There is no console tab, because the SDKs do not send console output. The tab, the view, and how the requests are shown are in the
address (`tab`, `view`, `display`, and `show`), and so is the moment the replay opens at (`at`, in microseconds since the epoch), where the
replay waits until it is played. The links of [Frustration](https://docs.molesignal.com/en-US/rum/frustration.md) open a session there.

## Tabs, sharing, and the address

The explorer uses the same query tabs as **Logs**: open several queries side by side, rename them, and split the page.
The address of the page is the query on screen. It carries the type (`type`), the field query (`q`), the time range (`time`), and
when the rows are drawn as numbers, how (see [Draw the rows as numbers](#draw-the-rows-as-numbers)), so a copy of the address bar shares the query. **Share** copies a link with a choice of the time range.

## What the explorer reads

The rows are in the [RUM streams](https://docs.molesignal.com/en-US/rum/events.md#where-the-events-are-stored). The query runs through the query engine with the
same masking and limits as **Logs**, and a count that takes too long is reported as unavailable. The columns and their
units are the same as the fields of the [event format](https://docs.molesignal.com/en-US/rum/events.md).

> **[RUM event format](https://docs.molesignal.com/en-US/rum/events.md)**
>
> The fields behind the columns.

> **[RUM applications](https://docs.molesignal.com/en-US/rum/applications.md)**
>
> Create an application and give its token to an SDK.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.