The Query Builder
The Querybuilder has two modes: simple and advanced. The simple mode allows you to build queries by selecting the desired functions and keys with your mouse.
The advanced mode allows you to enter the full query using the keyboard. Experienced users will find this mode faster, but the syntax is strict and you must remember the different available analytic functions.
Switching between query modes
You can quickly switch between the simple and the advanced mode by clicking the blue link to the top right of the query bar. If you find yourself in the advanced mode with an invalid query, the system prevents you from returning to the simple mode. To return to the simple mode, delete the query or fix the syntax errors.
The following section provides the details required to search your logs in a wide variety of ways. This covers keyword search, KVP search, RegEx search, and analytic functions. The capabilities available and the way you should search your logs varies based on the format of your logs.
Operators
There are two types of operators you can use: logical operators and comparison operators.
Logical operators
Log searches can use the following logical operators to create comprehensive search criteria.
| Logical Operator | Usage | Description |
|---|---|---|
| “AND” | expr1 AND expr2 | Returns log events that match both criteria |
| “OR” | expr1 OR expr2 | Returns log events that match one or both criteria |
| “NOT” or “-” | expr1 NOT expr2 | Returns log events that match expr1 but not expr2 |
Query language logical operators must be in UPPERCASE.
Comparison operators
Comparison operators can be used for KVP search and Regular Expression search.
| Operator | Example | Description |
|---|---|---|
| = | field=value | Returns log events that match the search value – matches numeric and text values |
| != | field!=value | Returns log events that do not match the search value – matches numeric and text values |
| > | field>num | Returns log events with field values higher than the search value |
| >= | field>=num | Returns log events with field values higher than or equal to the search value |
| < | field<num | Returns log events with field values lower than the search value |
| <= | field<num | Returns log events with field values lower than or equal the search value |
Numerical values must be formatted as an integer, floating-point value, or in scientific notation to be properly recognized by the query language. Units are not calculated as part of the comparison, e.g. searching for a value<100bytes would not return a result with value=200bits.
Performing a keyword search
Keyword searches work on all logs regardless of their format. They are case sensitive by default and match a full string until it is delimited by a non-letter character. For example, given the log events below,
the log search matches the events by searching for “etc” or “run” because the text is delimited by whitespace and non-letter characters. This search would not match “hour” but would match “hourly”.
Keyword search can be combined with logical operators, e.g. “starting AND finished” and “starting OR finished”.
When you list a series of keywords, the search automatically assumes an AND between each keyword. If you want to match an exact string, place “Double Quotes” around the search.
Performing a key value pair and JSON search
Log searches automatically parse log events that are in a Key Value Pair (KVP) or JSON format for easy use of advanced analytics. The KVP and JSON parsing doc explains the specific formats the system parses. If your logs are not in a standard KVP or JSON format, you can utilize the regular expression field extraction in LogEntries to gain access to the same advanced analytics.
To understand which KVP and JSON formats, given the log events below, searches can be easily written to return important log events.
The following example searches for all log events with a response time over 25 to return the first two log events:
Add the logical operator OR to include events from containerID 14 to return all three log events:
Analytic functions and visualizations
The log search syntax is designed to be intuitive, easy to use, and follows a SQL-style syntax for analyzing log data:
- Where: Filter to the subset of log events you want to analyze.
- GroupBy: Optional function that arranges data into identical groups based on a specified KVP.
- Calculate: Selects the method of calculation to run.
Basic queries
Count
Returns a count of matched search results. Append calculate(COUNT) to your search query or press the f{x} dropdown followed by the count function (as seen below) to get the number of search results.
Groupby()
You can perform search functions based on grouping identical datasets. In the example below, the logs contain the KVP “status” which represents the HTTP status code for a request from a web server, where(status) groupby(status) calculate(count).
The following query refines this search to match only status codes 300 and above, where(status>=300) groupby(status) calculate(count).
Currently there is a maximum limit of 40 groups that are displayed in a result set. If your groupby search result contains over 1000 keys, the ordering of the result set is estimated based on the most frequent keys.
Advanced LEQL queries
Average
The average modifier works the same as sum, but it computes the mean of the values matching the search criteria. For instance, to get the average value of your sales, you might invoke a search like where(sale_total>0) calculate(AVERAGE:sale_total).
Sum
You can use the sum function to total the values of your name value pairs. If you had a KVP for sale_value and wanted to know the total sales for a specified time period, use the following query: where(sale_total>0) calculate(SUM:sale_total).
Unique
The unique keyword returns the number of unique values for a given key. It takes one parameter: the name of the key. For example, if you have the KVP userID in your log file and want to find the number of unique users where(userID) calculate(UNIQUE:userID).
Min
The min function returns the minimum value of the key for each time period. For example, the query below returns the shortest response time for each time period, where(status=200) calculate(MIN:responseTime).
Max
The max function returns the maximum value of the key for each time period. For example, the query below returns the longest response time for each time period, where(status=200) calculate(Max:responseTime).
Sort() (Advanced Mode Only)
In the advanced mode, you have the ability to sort the results returned by a group by in ascending or descending order, where(status>=300) groupby(status) calculate(count) sort(desc).
The keywords to sort descending are desc and descending. The keywords to sort ascending are asc and ascending.
Timeslice() (Advanced Mode Only)
Automatically calculates 10 equal time intervals when performing a count, min, max or average query. You can manually set the number of time intervals by using the timeslice function. The valid input for timeslice is a number between 1 and 200 (inclusive). The query below used against a 1 hour search period returns the count of 500 errors per minute, where(status=500) calculate(count) timeslice(60).
Percentile()
The percentile option allows you to exclude outliers from your search functions. In the simple mode, you can quickly select either a 95th or 99th percentile search function based on a key value pair which has a numerical number. If you are using the advanced mode, you can specify your own percentile value by using percentile(80):key_value_pair in their calculate function. For example, if you specified calculate(percentile(99):service), you'd see the following:
Saving your searches
Searches can be saved. Click the star icon to save your search.
Click the dropdown icon to display the saved searches.
To edit a saved log search in order to give it a nickname or change the query, click the edit query link that displays when you mouse over a saved search. The Edit Query dialog displays.
- Enter the query nickname in the Query Nickname field.
- If needed, edit the query in the Query String field.
