Query Language 

A query always starts with a log type and can include one or more conditions to filter the results.

Query Format  

Use the following format to search logs:

logtype="logtype_name" and conditions

Where:

logtype - Specifies the type of logs to search.

logtype_name - The display name of the log type, such as access, execute, application, or schedule.

conditions - Additional criteria used to filter matching logs.

Example:  

logtype="access" and request_uri contains "/api"

This query returns Access Logs where the request URI contains /api.

Supported Operators   

The query language supports logical, numeric, string, and null-check operators for filtering logs.

Basic Operators

Numeric Operators

Example:  

logtype="access" and time_taken > 5000

Returns logs where the request took more than 5000 milliseconds.

String Operators

Example: 

logtype="application" and message contains "timeout"

Returns application logs containing the word timeout.

Aggregation Operators

Aggregation operators are used to summarize and analyze log data.

Examples include:

• count

• count_distinct

• sum

• avg

• groupby

• histo

• timeslice

For detailed information, refer to Aggregation Queries.  

Query Types     

The query language supports two main types of queries:

1. Log Fetch Queries

2. Aggregation Queries

Log Fetch Queries     

Log Fetch Queries are used to retrieve logs that match specific criteria.

Syntax:  

When specifying time-based values in queries, use the following notation:

Examples: 

Find Access Logs where the request took less than 10 seconds:

logtype="access" and time_taken < 10s

Retrieve logs containing specific text:

logtype="application" and message contains "validation failed"

Aggregation Queries     

Aggregation Queries are used to summarize and analyze log data rather than displaying individual log records.

These queries help answer questions such as:

• How many logs match a condition?

• Which module generated the most failures?

• Which request URI is accessed most frequently?

• What is the average execution time?

• How many requests, executions, or scheduled activities occurred during a specific time interval (for example, every minute, hour, or day)?

Format  :  

logtype="logtype_name" and condition groupby field_name timeslice interval

For detailed information, refer to Aggregation Queries.

Tips for Writing Queries   

• Always start with a logtype.

• Use and to narrow results.

• Use or to broaden results.

• Use contains for partial text searches.

• Use exact matches (=) when searching for specific values.

• Use auto-suggestions to discover available fields and supported values.

Common Search Queries   

logtype="access"

logtype="access" and zuid="5873965"

logtype="access" and status>=200 and status<300

logtype="access" and status>=400 

Aggregation Queries  

Aggregation queries help you analyze and summarize log data instead of retrieving individual log records.

They are useful when you need insights such as counts, trends, distributions, performance metrics, and frequently occurring values.

For example, aggregation queries can help answer questions such as:

• How many failed executions occurred?

• Which module generated the most failures?

• What is the average execution time?

• How many unique users accessed a service?

• How has activity changed over time?

Aggregation Query Structure   

Aggregation queries use aggregation operators to summarize or group matching logs.

Examples: 

Count matching logs:

logtype="access" count

Group logs by a field:

logtype="access" groupby status

Analyze activity over time:

logtype="access" timeslice 1h

Types of Aggregation   

The Logs query language supports two types of aggregation:

• Metric Aggregation

• Bucket Aggregation

Metric Aggregation   

Metric aggregations calculate values from matching logs and return summarized results.

Supported Operators  

Metric aggregations are commonly used for performance analysis, usage statistics, and identifying trends in numeric data.

Bucket Aggregation   

Bucket aggregations group logs into categories or intervals.

Supported Operators  

Aggregation Options   

The having operator is not supported with the histo operator.

Using groupby   

The groupby operator groups logs based on a selected field.

Syntax:

logtype="logtype_name" groupby field_name

Multiple groupby Fields  

logtype="logtype_name" groupby field1, field2

You can group results using up to 4 fields in a single query.

Sorting Results  

Sort by field value:

logtype="access" groupby zuid sort _field desc

Sort by count:

logtype="access" groupby zuid sort _count asc

Limiting Results:

logtype="access" groupby zuid limit 100

1. Default limit: 10
2. Maximum limit: 1000

Filtering Aggregated Results:  

logtype="access" groupby request_url having _count > 1000

groupby Limitations   

• groupby can only be used on supported fields.

• Results sorted by _count cannot be paginated.

• String values longer than 100 characters may be truncated.

• Counts and top values may be approximate in very large datasets.

In large datasets, grouped counts and top values may be approximate due to the distributed nature of log indexing and aggregation.  

Using histo  

The histo operator groups numeric values into intervals.

Syntax:  

logtype="logtype_name" histo field_name interval

Example: 

logtype="access" histo time_taken 1000

Custom Ranges  

logtype="access" histo time_taken range(10,10 to 100,100 to 1000,1000)

This groups values into:

• Less than 10 ms

• 10 ms to 100 ms

• 100 ms to 1000 ms

• Greater than 1000 ms

Using timeslice   

The timeslice operator groups logs into time intervals.

Supported Units  

Syntax: 

logtype="logtype_name" timeslice interval

Example:  

logtype="access" timeslice 1h

Sorting Results  

Sort by count:

logtype="access" timeslice 5m sort _count

Sort by interval:

logtype="access" timeslice 5m sort _field desc

Sorting Aggregation Results   

Aggregation results can be sorted using calculated values.

Example:

logtype="access" groupby request_url sort avg(time_taken) desc

logtype="access" groupby request_url having _count > 1000 sort avg(time_taken) desc

Query Constraints    

count Operator   

The count operator can only be used at the end of a query.

Valid:

logtype="execute" and status="failed" count

Invalid:

logtype="execute" count and status="failed"

After the count operator, no additional criteria or aggregation operators can be added.

count and count_distinct   

The count and count_distinct operators cannot be used together in the same query.

Common Aggregation Queries   

Analyze Request Performance   

Find the maximum time taken to process a request

logtype="access" max(time_taken)

Get maximum and minimum processing time for card creation requests

logtype="access" and request_url contains "/job" and method contains "post" max(time_taken)
min(time_taken)

Analyze Usage   

Get unique URLs that took more than 10 seconds to process

logtype="access" and time_taken > 10s groupby request_url

Group and Categorize Logs   

Get frequently accessed request URLs with count

logtype="access" count(request_url) groupby request_url

Get frequently accessing remote IP for each module

logtype="access" distinct(zuid) groupby _zl_host

Analyze Trends   

Get log distribution over time

logtype="access" and request_url contains "/job" timeslice 1h