Example queries

groundcover recommends using as many "strong" filters as possible, like time filters, workload and namespaces filters, log level filters, etc.

These will help making free text and attribute searches much faster and efficient.

The $__timeFilter condition enforces time range limits on the query, which are selected based on the time window selected for the query.

Types of queries

When querying logs in the platform it's important to distinguish between two types of queries:

1. Instant queries - will return a single value for each group. For example, counting the amount of error logs per workload.

   1. When to use: Threshold-based alerting or when you only need the most recent value

2. Range queries - will return a series of values over time. For example, counting the amount of logs per workload in 5-minute buckets.

   1. When to use: Plotting trends over time

Examples of instant queries

Counting error logs

The query uses the count() operator to get the number of error logs in the defined time window.

SELECT    count()   AS log_count,
          workload  AS workload,
          namespace AS namespace
FROM      groundcover.logs
WHERE     $__timeFilter(timestamp) 
          AND level = 'error'
GROUP     BY workload, namespace

groundcover always saves log levels as lower-cased values, e.g: 'error', 'info'.

Free text search

The query uses the count() operator to get the number of logs generated by the kafkajs-events-consumer workload, which contain the phrase Connection timeout.

SELECT    count()   AS log_count
FROM      groundcover.logs
WHERE     $__timeFilter(timestamp) 
          AND workload = 'kafkajs-events-consumer'
          AND content LIKE '%Connection timeout%'

Selecting and filtering by log attributes

Using formatted logs allows groundcover to automatically extract attributes from the log, which can then be used in alerts and dashboards.

For example, let's look at the following json-formatted log:

{ 
        "http.req.id": "99419211-7283-467f-8d39-b3c4be7a98c2", 
        "http.req.method": "GET",
        "http.req.path": "/product/ZZZZZZZ011", 
        "session": "e17d3d07-13f6-430b-85ed-290863388766", 
        "severity": "debug", 
        "timestamp": "2024-07-11T10:40:42.812301569Z" 
}

The following query uses the string_attributes column to query the "http.req.method" attribute and filter for GET requests:

SELECT    count()   AS log_count
FROM      groundcover.logs
WHERE     $__timeFilter(timestamp) 
          AND string_attributes['http.req.method'] = 'GET'

Examples of range queries

Make sure to select the Time Series query type when using range queries

Distribution of logs based on an attribute

The following query will plot the count of logs grouped by a specific attribute extracted from the logs. It will arrange the counts into 5-minute buckets, showing trend over time.

SELECT 
    toStartOfInterval(timestamp, INTERVAL 5 minute)   AS bucket_timestamp,
    string_attributes['my_attribute']                 AS my_attribute,
    count()                                           AS count
FROM groundcover.logs
WHERE $__timeFilter(timestamp)
      AND workload = 'my_workload'
GROUP by bucket_timestamp, my_attribute
ORDER BY bucket_timestamp ASC