> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/use-groundcover/querying-your-groundcover-data/explore-and-monitors-query-builder.md).

# Data Explorer & Query builder

### Modes Overview

1. **Metrics** – Work with all your available metrics. Great for advanced use cases and custom metrics.
2. **Logs** – Query and visualize Logs data.
3. **Traces** – Query and visualize Traces, similar to logs.
4. **Events** – Query and visualize events, similar to logs.
5. **APM** – Query groundcover's eBPF-generated application metrics (the golden signals) using guided pickers.
6. **RUM -** Query and visualize RUM Events.
7. **Issues** - Query and visualizae issue-oriented signals
8. **Ingestion** - Ingestion and pipeline metrics

{% hint style="info" %}
**RUM** , **Issues** and **Ingestion** are available in Explore only - it is not a Monitor data source.
{% endhint %}

### Metrics

<figure><img src="/files/MlqUH2S76ScoWYMjMtla" alt=""><figcaption></figcaption></figure>

When you select the **Metrics** mode, you’ll work with something akin to Prometheus queries - but simplified.

groundcover supports a wide variety of metrics - [Application](https://docs.groundcover.com/capabilities/application-performance-monitoring/application-metrics) and [Infrastructure](https://docs.groundcover.com/capabilities/infrastructure-monitoring) metrics are automatically generated using our eBPF sensor, and [custom metrics](https://docs.groundcover.com/use-groundcover/scraping-custom-metrics) can be ingested natively.

### ![](/files/O5OYF0T6u3ryPuhtG9Nh)

**Metric Selector:**

* Search and choose a metric.
* View associated labels and metadata (for groundcover’s built-in metrics).
* If the chosen built-in metric’s type is known, the Query Builder automatically applies the best-suited function to streamline your workflow.

<figure><img src="/files/n3L5tDKJvcSNwl5H6BjF" alt=""><figcaption></figcaption></figure>

**Filters Bar (Metrics):**

* Filter by label key/value pairs.
* Use `-` to exclude values
* All filters are ANDed together, but multiple values for the same key form an OR condition.
* Type a key and `:` (e.g `cluster:`) to list its values.
* Use patterns (wildcards, partial matches) to refine results.

<figure><img src="/files/7P7xDNpP77AsT3zNkgm8" alt=""><figcaption></figcaption></figure>

**Aggregation Function Selector:**

* **sum**: Adds up all values.
* **avg**: Calculates the average value.
* **max**: Finds the maximum value.
* **min**: Finds the minimum value.
* **count**: Counts how many data points there are.
* **no aggregation**: Leaves data un-aggregated.

**Aggregation Labels Selector:**

* Select one or more labels to group your results by.

**Limit Selector:**

* Show top or bottom results based on:
  * **Max**: Highest values.
  * **Min**: Lowest values.
  * **Mean**: Highest/lowest average values.
  * **Median**: Highest/lowest median values.
  * **Last**: Highest/lowest most recent values.

**Visualization Type:**

* **Time-series**: View data over time (time range set by the time-picker).
* **Table**: Instant snapshot data.
* **Stats**: One or more KPI numbers.
* **Top list**: Ranked values as horizontal bars
* **Pie**: Share of total across a small number of categories

**Time & Rollup Notes:**

* The **time-picker** defines the time range for your query.

**Advanced Query**

Switching to Advanced Query mode allows you to view and modify the MetricsQL or gcQL query generated by the Query Builder. This mode provides full flexibility for advanced users. However, some changes made in the editor are not reflected back in the Query Builder. The editor is ideal for making manual adjustments that are beyond the capabilities offered in Query Builder mode.

{% hint style="info" %}
Selecting or deselecting Clusters and Environments in the Backend Picker won't affect the metrics displayed.
{% endhint %}

### Logs/Traces

<figure><img src="/files/wib6F9MjHlRSnOkTlJ6r" alt=""><figcaption></figcaption></figure>

**Filters Bar (Logs/Traces):**

* Same label-based filtering as Metrics.
* **Free Text Search (Logs only)**: Search for any substring.
* Exclude terms by prefixing with `-`
* Use `*` as a wildcard.

<figure><img src="/files/0JD3cN1lmOhSuXs5aT7y" alt=""><figcaption></figcaption></figure>

**Measurement Selection (Logs/Traces):**

* **Count**: Count total logs/traces.
* **Count (unique)**: Count distinct values of a chosen field.
* **Avg/Sum/Max/Min**: For numeric fields, perform calculations.
* **Percentiles (P99/P95/P50/P10)**: Show the value at a specific percentile.

**Group By:**

* Group results by fields (e.g., `k8s.namespace`, `service.name`) to break down the data by categories.

**Rollup (Logs/Traces):**

* Choose time buckets (like 1m, 5m) for aggregation. This helps smooth out spikes or show trends over chosen intervals.

**Limit:**

* Limit and sort table data to display only the most relevant rows.

**Visualization Type (Logs/Traces):**

* **Time-series**
* **Table**
* **Stat**
* **Top List**
* **Pie**

<figure><img src="/files/HUMZzC0NqZDsw4WrfAXr" alt=""><figcaption></figcaption></figure>

### RUM

The RUM Query Builder allows you to query RUM data collected by the groundcover SDK.

<figure><img src="/files/zMAgkUyTG8wn8pVIba7R" alt=""><figcaption></figcaption></figure>

It includes the same components as the [Logs/Traces](#logs-traces) builder (Measurement Selection, Group By, Rollup, Limit, Visualization Type), plus an additional selector for Event Type.

The following event types and their properties are available:

<table><thead><tr><th>Event Type</th><th width="273.875">Property</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><strong>Page Loads</strong></td><td><code>page_load_time</code></td><td>Page Load Time</td><td>Numeric</td></tr><tr><td></td><td><code>page_url</code></td><td>Page URL</td><td>String</td></tr><tr><td><strong>Errors</strong></td><td><code>error_fingerprint</code></td><td>Error Fingerprint</td><td>String</td></tr><tr><td></td><td><code>error_message</code></td><td>Error Message</td><td>String</td></tr><tr><td></td><td><code>error_type</code></td><td>Error Type</td><td>String</td></tr><tr><td><strong>Custom Events</strong></td><td><code>custom_event_name</code></td><td>Event Name</td><td>String</td></tr><tr><td><strong>Interactions</strong></td><td><code>dom_event_target.text</code></td><td>Target Text</td><td>String</td></tr><tr><td></td><td><code>dom_event_selector</code></td><td>Target Selector</td><td>String</td></tr><tr><td></td><td><code>dom_event_target.id</code></td><td>Target ID</td><td>String</td></tr><tr><td></td><td><code>dom_event_target.className</code></td><td>Target Class Name</td><td>String</td></tr><tr><td><strong>Performance</strong></td><td><code>performance_metric_name</code></td><td>Metric Name</td><td>String</td></tr><tr><td></td><td><code>performance_metric_value</code></td><td>Metric Value</td><td>Numeric</td></tr><tr><td><strong>Navigations</strong></td><td><code>page_url</code></td><td>URL</td><td>String</td></tr></tbody></table>

#### Global properties available for all RUM events:

* `session_id`
* `service.name`
* `location.path`
* `location.title`
* `user.email`
* `user.organization`
* `user.name`
* `browser.version`
* `browser.name`
* `browser.type`
* `browser.platform`

#### Example

Create a visualization of **Errors** over time grouped by **error\_message** in the **demo** service:

<figure><img src="/files/jr0zS94iqvDC325Z0yVg" alt=""><figcaption></figcaption></figure>

### APM

The APM mode lets you query groundcover's eBPF-generated [application metrics](/capabilities/application-performance-monitoring-apm/application-metrics.md) - the golden signals collected automatically for every workload and resource - without writing PromQL. It runs against groundcover's pre-aggregated APM measurements, so it stays fast and accurate even over long time ranges.

Unlike the Metrics and Logs/Traces builders, APM is a guided, **builder-only** experience: you select a metric and scope it with structured pickers, and groundcover generates the underlying query. There is no code/advanced-query mode for APM.

**Metric Selector:**

* Choose the golden signal to visualize:
  * **Requests** – total request count.
  * **Errors** – count of requests with an error status.
  * **Error Rate** – percentage of requests that errored.
  * **Request Rate** – requests per second.
  * **AVG / P50 / P95 / P99 Latency** – average and percentile latencies.
  * **Total Time Spent** – cumulative time across requests.

**Perspective:**

* Toggle between **Inbound** (traffic the workload serves) and **Outbound** (traffic the workload sends).

**Type (Resource Type):**

* Scope to a protocol - HTTP, gRPC, SQL, Kafka, DNS, and so on.

**Server / Client:**

* Select the workload(s) to query. The picker is labelled **Server** in the Inbound perspective and **Client** in the Outbound perspective.

**Endpoint:**

* Narrow down to specific resources/endpoints (for example, a particular HTTP route).

**Filters, Group By, Limit & Visualization:**

* Work the same way as the other builders - add label filters, group results by labels (e.g. `workload_name`, `namespace`), limit/sort the output, and choose the rollup, chart type, and units.

### Ingestion

The ingestion mode lets you see how much data is being ingested into the groundcover platform. Common use cases for this datasource are:

* Governance over data ingested from different sources&#x20;
* Visualizing ingestion trends over time
* Assisting in reduction of noisy logs and traces

<figure><img src="/files/N4ybR97KVpBcECt8rjn8" alt=""><figcaption></figcaption></figure>

&#x20;                                          Example: Log volume ingestion over time by workload

**Signal Selector:**

Choose the data signal to visualize:

* Logs&#x20;
* Traces

{% hint style="info" %}
Metrics are coming soon - but similar data is available at the [Metric Summary](/use-groundcover/metric-summary.md) page
{% endhint %}

**Volume/Count:**

* Toggle between **Volume** (size of the data measured in bytes) and Count (number of entries).

**Filters, Group By, Limit & Visualization:**

* Work the same way as the other builders - add label filters, group results by labels (e.g. `workload_name`, `namespace`), limit/sort the output, and choose the rollup, chart type, and units.

### Formulas

groundcover supports the use of **Formulas** in most datasources. Formulas allow you to perform arithmetic operations and apply functions to your metrics queries.

**Using Formulas:**

1. **Assign Query Symbols:** each metric query is automatically assigned a letter (A, B, C, etc.).
2. **Construct Formulas:** Combine these letters using operators and functions to create expressions.

**Supported Operators:**

* Addition: `+`
* Subtraction: `-`
* Multiplication: `*`
* Division: `/`
* Modulo: `%`
* Exponentiation: `**`
* Parentheses: `()` for grouping

**Example:**

To calculate the CPU usage percentage where **A** is the used CPU metric and **B** is the total CPU capacity:

```
(A / B) * 100
```

### Examples

Here are a few examples to help you understand how to build and visualize queries using the Query Builder:

Query the top 5 workloads with the highest **average container CPU usage** in the namespaces `demo-ng` and `opentelemetry-demo`.

<figure><img src="/files/f73ov4BaxEGsdS7vJzqr" alt=""><figcaption></figcaption></figure>

Quickly find the **average memory usage** of **workloads** in the namespace `demo-ng`. Instead of crafting a complex query, we simply selected **Container Memory > Usage Amount**.

<figure><img src="/files/NePBwsgDLz06UA0iwSBy" alt=""><figcaption></figcaption></figure>

Query the P99 duration of all HTTP traces across the platform. This query is broad, with no filters applied for clusters, namespaces, or specific services.

<figure><img src="/files/Obm7M1d74topTe1kzOOG" alt=""><figcaption></figcaption></figure>

Narrow it down: Query the P99 duration of HTTP traces, but this time only for outbound traces from a specific workload.

<figure><img src="/files/55IKLZMeMBfHvPYQ3266" alt=""><figcaption></figcaption></figure>

Visualize the distribution of log counts per log level in the cluster demo. This provides a quick snapshot of the log severity levels.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.groundcover.com/use-groundcover/querying-your-groundcover-data/explore-and-monitors-query-builder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.