groundcover Query Language

The groundcover Query Language is a powerful tool for querying and analyzing logs, traces, and events across your infrastructure.

What is the groundcover Query Language?

The groundcover Query Language is inspired by LogsQL but designed specifically for groundcover's observability platform. It uses a pipeline-based syntax where operations flow from left to right using the pipe operator |.

You can use it to:

• Filter logs, traces, and events with flexible search patterns

• Aggregate data with statistical functions (count, avg, percentiles, etc.)

• Join multiple queries

• Transform results with sorting, limiting, field selection, and more

Where Can You Use It?

The query language is available in:

1. Data Explorer - Query and visualize data interactively

2. Monitors - Create alerts based on query results

3. Dashboards - Build custom visualizations

4. APIs - Query data programmatically

Code Mode

Access the query language through Code Mode in the Data Explorer and Monitors query builder. Code Mode gives you full control over your queries with syntax highlighting and auto-completion.

Basic Query Structure

All queries follow this general pattern:

<filters> | <operation1> | <operation2> | ...

Example - Simple filter:

level:error

Find all error logs

Example - Filter with aggregation:

level:error | stats by (workload) count()

Count errors per workload

Example - Full pipeline:

level:error namespace:production | stats by (workload) count() as errors | sort by (errors desc) | limit 10

Top 10 workloads with errors in production

Core Components

Filters

Filters narrow down your data using field-value matching.

level:error

workload:auth-service status_code:>=500

"*timeout*" namespace:prod

Aggregations

Compute metrics from filtered data using stats.

* | stats count()

* | stats by (workload) avg(duration_seconds)

Join Operations

Combine data from multiple queries.

* | stats by (user_id) count() | join by (user_id) (event:purchase | stats by (user_id) count())

Pipeline Operations

Transform results with sort, limit, fields, and more.

* | sort by (timestamp desc)

* | stats by (endpoint) count() | sort by (count desc) | limit 10

* | fields timestamp, level, message, workload

Differences from Other Query Languages

vs. LogsQL

• Case-insensitive by default (LogsQL is case-sensitive)

• Implicit OR for same-field filters: level:error level:warn = level:error OR level:warn

• Time bucketing configured externally, not in stats by (_time:5m)

• Both *value* and ~"value" syntax for substring matching

vs. SQL

• Pipeline-based - Left-to-right flow with | vs. declarative SELECT/FROM/WHERE

• No tables - Query logs/traces/events directly

• Implicit AND - Multiple filters are ANDed automatically

• Function syntax - stats by (field) count() vs. SELECT field, COUNT(*) GROUP BY field