Boolean, comparison, numeric, datetime, and other functions - Amazon CloudWatch Logs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

# Boolean, comparison, numeric, datetime, and other functions

CloudWatch Logs Insights supports many other operations and functions in queries, as explained in the following sections.

## 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

`a + b`

`a - b`

Subtraction

`a * b`

Multiplication

`a / b`

Division

`a ^ b`

Exponentiation (`2 ^ 3` returns `8`)

`a % b`

Remainder or modulus (`10 % 3` returns `1`)

## 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

`abs(a: number)`

number

Absolute value

`ceil(a: number)`

number

Round to ceiling (the smallest integer that is greater than the value of `a`)

`floor(a: number)`

number

Round to floor (the largest integer that is smaller than the value of `a`)

`greatest(a: number, ...numbers: number[])`

number

Returns the largest value

`least(a: number, ...numbers: number[])`

number

Returns the smallest value

`log(a: number)`

number

Natural log

`sqrt(a: number)`

number

Square root

## 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 milliseconds

• `s` for seconds

• `m` for minutes

• `h` 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

`bin(period: Period)`

Timestamp

Rounds the value of `@timestamp` to the given time period and then truncates. For example, `bin(5m)` rounds the value of `@timestamp` to the nearest 5 minutes.

You can use this to group multiple log entries together in a query. The following example returns the count of exceptions per hour:

``````filter @message like /Exception/
| stats count(*) as exceptionCount by bin(1h)
| sort exceptionCount desc``````

The following time units and abbreviations are supported with the `bin` function. For all units and abbreviations that include more than one character, adding s to pluralize is supported. So both `hr` and `hrs` work to specify hours.

• `millisecond` `ms` `msec`

• `second` `s` `sec`

• `minute` `m` `min`

• `hour` `h` `hr`

• `day` `d`

• `week` `w`

• `month` `mo` `mon`

• `quarter` `q` `qtr`

• `year` `y` `yr`

`datefloor(timestamp: Timestamp, period: Period)`

Timestamp

Truncates the timestamp to the given period. For example, `datefloor(@timestamp, 1h)` truncates all values of `@timestamp` to the bottom of the hour.

`dateceil(timestamp: Timestamp, period: Period)`

Timestamp

Rounds up the timestamp to the given period and then truncates. For example, `dateceil(@timestamp, 1h)` truncates all values of `@timestamp` to the top of the hour.

`fromMillis(fieldName: number)`

Timestamp

Interprets the input field as the number of milliseconds since the Unix epoch and converts it to a timestamp.

`toMillis(fieldName: Timestamp)`

number

Converts the timestamp found in the named field into a number representing the milliseconds since the Unix epoch. For example, `toMillis(@timestamp)` converts the timestamp `2022-01-14T13:18:031.000-08:00` to `1642195111000`.

###### 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 as arguments for other functions.

Function Result type Description

`ispresent(fieldName: LogField)`

Boolean

Returns `true` if the field exists

`coalesce(fieldName: LogField, ...fieldNames: LogField[])`

LogField

Returns the first non-null value from the list

Use IP address string functions in the `filter` and `fields` commands and as arguments for other functions.

Function Result type Description

`isValidIp(fieldName: string)`

boolean

Returns `true` if the field is a valid IPv4 or IPv6 address.

`isValidIpV4(fieldName: string)`

boolean

Returns `true` if the field is a valid IPv4 address.

`isValidIpV6(fieldName: string)`

boolean

Returns `true` if the field is a valid IPv6 address.

`isIpInSubnet(fieldName: string, subnet: string)`

boolean

Returns `true` if the field is a valid IPv4 or IPv6 address within the specified v4 or v6 subnet. When you specify the subnet, use CIDR notation such as `192.0.2.0/24` or `2001:db8::/32`, where `192.0.2.0` or `2001:db8::` is the start of the CIDR block.

`isIpv4InSubnet(fieldName: string, subnet: string)`

boolean

Returns `true` if the field is a valid IPv4 address within the specified v4 subnet. When you specify the subnet, use CIDR notation such as `192.0.2.0/24` where `192.0.2.0` is the start of the CIDR block..

`isIpv6InSubnet(fieldName: string, subnet: string)`

boolean

Returns `true` if the field is a valid IPv6 address within the specified v6 subnet. When you specify the subnet, use CIDR notation such as `2001:db8::/32` where `2001:db8::` is the start of the CIDR block.

## String functions

String functions

Use string functions in the `fields` and `filter` commands and as arguments for other functions.

Function Result type Description

`isempty(fieldName: string)`

Number

Returns `1` if the field is missing or is an empty string.

`isblank(fieldName: string)`

Number

Returns `1` if the field is missing, an empty string, or contains only white space.

`concat(str: string, ...strings: string[])`

string

Concatenates the strings.

`ltrim(str: string)`

`ltrim(str: string, trimChars: string)`

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 `trimChars` from the left of `str`. For example, `ltrim("xyZxyfooxyZ","xyZ")` returns `"fooxyZ"`.

`rtrim(str: string)`

`rtrim(str: string, trimChars: string)`

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 `trimChars` from the right of `str`. For example, `rtrim("xyZfooxyxyZ","xyZ")` returns `"xyZfoo"`.

`trim(str: string)`

`trim(str: string, trimChars: string)`

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 `trimChars` from both sides of `str`. For example, `trim("xyZxyfooxyxyZ","xyZ")` returns `"foo"`.

`strlen(str: string)`

number

Returns the length of the string in Unicode code points.

`toupper(str: string)`

string

Converts the string to uppercase.

`tolower(str: string)`

string

Converts the string to lowercase.

`substr(str: string, startIndex: number)`

`substr(str: string, startIndex: number, length: number)`

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, `substr("xyZfooxyZ",3, 3)` returns `"foo"`.

`replace(fieldName: string, searchValue: string, replaceValue: string)`

string

Replaces all instances of `searchValue` in `fieldName: string` with `replaceValue`.

For example, the function `replace(logGroup,"smoke_test","Smoke")` searches for log events where the field `logGroup` contains the string value `smoke_test` and replaces the value with the string `Smoke`.

`strcontains(str: string, searchValue: string)`

number

Returns 1 if `str` contains `searchValue` and 0 otherwise.