Boolean, comparison, numeric, datetime, and other functions
CloudWatch Logs Insights supports many other operations and functions in queries, as explained in the following sections.
Topics
Arithmetic operators
Arithmetic operators accept numeric data types
as arguments
and return numeric results.
Use arithmetic operators
in the filter
and fields
commands
and
as arguments for other functions.
Operation | Description |
---|---|
|
Addition |
|
Subtraction |
|
Multiplication |
|
Division |
|
Exponentiation
( |
|
Remainder or modulus
( |
Boolean operators
Use the Boolean operators and
, or
, and not
.
Note
Use Boolean operators only in functions that return a value of TRUE or FALSE.
Comparison operators
Comparison operators accept all data types
as arguments
and return a Boolean result.
Use comparison operations
in the filter
command
and
as arguments for other functions.
Operator | Description |
---|---|
|
Equal |
|
Not equal |
|
Less than |
|
Greater than |
|
Less than or equal to |
|
Greater than or equal to |
Numeric operators
Numeric operations accept numeric data types
as arguments
and return numeric results.
Use numeric operations in the filter
and fields
commands
and
as arguments for other functions.
Operation | Result type | Description |
---|---|---|
|
number |
Absolute value |
|
number |
Round
to ceiling (the smallest integer
that is
greater than the value
of |
|
number |
Round
to floor (the largest integer
that is
smaller than the value
of |
|
number |
Returns the largest value |
|
number |
Returns the smallest value |
|
number |
Natural log |
|
number |
Square root |
Structure types
A map or list is a structure type in CloudWatch Logs Insights that allows you to access and use attributes for queries.
To get a map or list
Use jsonParse
to parse a field that's a json string into a map or a list.
fields jsonParse(@message) as json_message
To access attributes
Use the dot access operator (map.attribute) to access items in a map. If an attribute in a map contains special characters, use backticks to enclose the attribute name (map.attributes.`special.char`).
fields jsonParse(@message) as json_message | stats count() by json_message.status_code
Use the bracket access operator (list[index]) to retrieve an item at a specific position within the list.
fields jsonParse(@message) as json_message | filter json_message.users[1].action = "PutData"
Wrap special characters in backticks (``) when special characters are present in the key name.
fields jsonParse(@message) as json_message | filter json_message.`user.id` = "123"
To flatten a list
Use unnest
to flatten a list into multiple records.
For more information, see Unnest.
fields jsonParse(@message) as js | unnest js.accounts into account | filter account.type = "internal"
To stringify a map or list
Use jsonStringify
to stringify a map for aggregation.
fields jsonParse(@message) as map | stats count() by jsonStringify(map)
Note
Using map and list in dedup
,pattern
, sort
, and stats
isn't supported.
Maps and lists are treated as null for string, number, and datetime functions.
Comparing map and list to any other fields result in false
.
Datetime functions
Datetime functions
Use datetime functions
in the fields
and filter
commands
and
as arguments
for other functions.
Use these functions
to create time buckets
for queries
with aggregate functions.
Use time periods
that consist
of a number
and one of the following:
ms
for millisecondss
for secondsm
for minutesh
for hours
For example,
10m
is 10 minutes,
and 1h
is 1 hour.
Note
Use the most appropriate time unit for your datetime function.
CloudWatch Logs caps your request according to the time unit that you choose. For example,
it caps 60 as the maximum value for any request that uses s
. So, if you specify
bin(300s)
, CloudWatch Logs actually implements this as 60 seconds, because 60 is the number of seconds in a minute
so CloudWatch Logs won't use a number higher than 60 with s
. To create a 5-minute bucket,
use bin(5m)
instead.
The cap for ms
is 1000, the caps for s
and m
are 60,
and the cap for h
is 24.
The following table contains a list of the different datetime functions that you can use in query commands. The table lists each function's result type and contains a description of each function.
Tip
When you create a query command, you can use the time interval selector to select a time period that you want to query. For example, you can set a time period between 5 and 30-minute intervals; 1, 3, and 12-hour intervals; or a custom time frame. You also can set time periods between specific dates.
Function | Result type | Description |
---|---|---|
|
Timestamp |
Rounds the value of You can use this to group multiple log entries together in a query. The following example returns the count of exceptions per hour:
The following time units and abbreviations are supported with the
|
|
Timestamp |
Truncates the timestamp to the given period. For example, |
|
Timestamp |
Rounds up the timestamp to the given period and then truncates. For example, |
|
Timestamp |
Interprets the input field as the number of milliseconds since the Unix epoch and converts it to a timestamp. |
|
number |
Converts the timestamp
found
in the named field
into a number representing the milliseconds since the Unix epoch.
For example,
|
Note
Currently, CloudWatch Logs Insights doesn't support filtering logs with human readable timestamps.
General functions
General functions
Use general functions in the fields
and filter
commands and arguments for other functions.
Function | Result type | Description |
---|---|---|
|
Boolean |
Returns |
|
LogField |
Returns the first non-null value from the list |
JSON functions
JSON functions
Use JSON functions to operate JSON strings.
Function | Result type | Description |
---|---|---|
|
Map | List | Empty |
Returns a map or list when the input is a string representation of a JSON object or JSON array. Returns an empty value if the input is not one of the representation. For more information, see Structure types. |
|
String |
Takes a map or list as input to produce a JSON string with sorted keys. The output is plaintext when the input is a boolean, number, and timestamp. For more information, see Structure types. |
IP address string functions
IP address string functions
Use IP address string functions
in the filter
and fields
commands
and
as arguments
for other functions.
Function | Result type | Description |
---|---|---|
|
boolean |
Returns |
|
boolean |
Returns |
|
boolean |
Returns |
|
boolean |
Returns |
|
boolean |
Returns |
|
boolean |
Returns |
String functions
String functions
Use string functions
in the fields
and filter
commands
and
as arguments
for other functions.
Function | Result type | Description |
---|---|---|
|
Number |
Returns |
|
Number |
Returns |
|
string |
Concatenates the strings. |
|
string |
If the function does not have a second argument, it removes white space from the left of the string. If the
function has a second string argument, it does not remove white space. Instead, it removes the characters
in |
|
string |
If the function does not have a second argument, it removes white space from the right of the string. If the
function has a second string argument, it does not remove white space. Instead, it removes the characters
of |
|
string |
If the function does not have a second argument, it removes white space from both ends of the string. If the
function has a second string argument, it does not remove white space. Instead, it removes the characters
of |
|
number |
Returns the length of the string in Unicode code points. |
|
string |
Converts the string to uppercase. |
|
string |
Converts the string to lowercase. |
|
string |
Returns a substring from the index specified by the number argument to the end of
the string. If the function has a second number argument, it contains the length of the
substring to be retrieved. For example, |
|
string |
Replaces all instances of For example,
the function |
|
number |
Returns 1 if |