Log in|Playground

Advanced Log Queries

This document provides advanced examples of querying logs using the groundcover API with complex filtering conditions.

Overview

The group parameter supports various filter operations and combinations. This page demonstrates advanced patterns including:

  • OR conditions within a single field

  • NOT conditions (excluding values)

  • Wildcard matching

  • Free text search

OR Conditions on a Single Field

To match multiple values for the same field (OR condition), include multiple filters in the same condition:

Example: Match logs where env is either "prod" OR "dev" AND level is "error"

curl 'https://app.groundcover.com/api/logs/v2/query' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "start": "2025-12-24T13:36:49.143Z",
    "end": "2025-12-24T19:36:49.143Z",
    "group": {
      "operator": "and",
      "conditions": [
        {
          "filters": [{"op": "match", "value": "error"}],
          "key": "level",
          "origin": "root",
          "type": "string"
        },
        {
          "filters": [
            {"op": "match", "value": "prod"},
            {"op": "match", "value": "dev"}
          ],
          "key": "env",
          "origin": "root",
          "type": "string"
        }
      ]
    },
    "limit": 200,
    "skip": 0,
    "sortBy": "timestamp",
    "sortOrder": "desc",
    "selectors": [],
    "optimizeSearch": true
  }'

Structure:

  • Multiple filters in the same conditions entry create an OR relationship

  • In this example, the env field matches if it equals "prod" OR "dev"

  • The overall operator: "and" means both conditions must be satisfied (level=error AND (env=prod OR env=dev))

NOT Conditions (Excluding Values)

To exclude specific values, use the "op": "not_match" operation:

Example: Match logs where level is NOT "error" AND env is "prod"

Structure:

  • Use "op": "not_match" to exclude values

  • This example returns logs where level is anything except "error" AND env is "prod"

Wildcard Matching

To match values that start with, end with, or contain a pattern, use wildcard characters:

Example: Match logs where workload starts with "groundcover" AND level is NOT "error"

Structure:

  • Use * as a wildcard character

  • "groundcover*" matches any value starting with "groundcover" (e.g., "groundcover-backend", "groundcover-frontend")

  • Wildcards can be used with both match and not_match operations

Free Text Search

To search for specific text or phrases within log content (not limited to specific fields), use free text search with phrase_search:

Example: Search for logs containing the phrase "POST /ingest" with additional fields

Structure:

  • Use "op": "phrase_search" for free text search

  • Set "type": "freetext" (instead of "type": "string")

  • Do not include a "key" field - free text search searches across all log content

  • The value can be a single word or a phrase (e.g., "POST /ingest")

  • Free text search searches within the log line content, not specific fields

  • Use selectors to request additional fields. Format: [{"key": "request.method"}, {"key": "cluster"}, {"key": "host.id"}]

Filter Operations

The following filter operations are supported:

Operation
Description
Example

match

Matches the exact value or pattern

{"op": "match", "value": "error"}

not_match

Excludes the exact value or pattern

{"op": "not_match", "value": "error"}

phrase_search

Searches for a phrase in log content (free text)

{"op": "phrase_search", "value": "POST /ingest"}

Combining Conditions

AND Operator

When using "operator": "and", all conditions must be satisfied:

This means: level condition AND env condition must both be true.

OR Within a Field

Multiple filters in the same condition create an OR relationship:

This means: env equals "prod" OR env equals "dev".

Complex Combinations

You can combine AND and OR operations:

This means: level equals "error" AND (env equals "prod" OR env equals "dev").

Best Practices

  1. Wildcard Performance: Use wildcards judiciously as they can impact query performance on large datasets.

  2. NOT Operations: not_match operations can be slower than match operations. Consider if you can achieve the same result with positive matches.

  3. Multiple Filters: When using multiple filters in a single condition (OR), ensure they all apply to the same field.

  4. Consistent Structure: Always include origin: "root" and the appropriate type for each condition.

  5. Testing: Test complex queries with small time ranges first to verify the results before querying large datasets.

Last updated