This query function may be used to select events in which the given field contains particular values. For instance, you might want to monitor events in which log messages contain error, warning, or other similar words in log entries, or perhaps particular numeric values in other fields.

Although this query function allows for only three parameters, it's very useful and versatile. For the first parameter, you would specify the field on which to filter data. The second parameter sets whether the search should be case-insensitive. The third parameter would be the string or multiple strings on which to match the contents of the field.

ParameterTypeRequiredDefaultDescription
field[a]stringrequired  The field on which to filter events.
ignoreCasestringrequiredfalse Allows for case-insensitive searching. (introduced in 1.100.0)
valuesArray of stringsrequired  The values on which to match the field. Only one match is required. Values can contain wildcards (i.e., *).

[a] The argument name field can be omitted.

Omitted Argument Names

The argument name for field can be omitted; the following forms of this function are equivalent:

logscale
in("field",values=["value"],ignoreCase=false)

and:

logscale
in(field="field",values=["value"],ignoreCase=false)

These examples show basic structure only; full examples are provided below.

in() Examples

Suppose you have a repository which is ingesting data from a few web servers. And suppose that you want to get a list of events in which the user received the HTTP code 404, for web pages Not Found. You could do that easily with this query:

logscale
status = 404

As this suggests, the field on which to check is status.

Suppose further that you want to get a list of events in which the user received the HTTP codes 422 and 200. Those codes represent respectively Unable to be processed, and Successful. You could get those events with the in() function like so:

logscale
in(status, values=["422","200"])

Using the status field for the first parameter; for the second parameter, the two statuses are listed, separated by commas, within an array — within square-brackets. Incidentally, if you wanted to include string values instead of numbers, each string value would have to be contained within double-quotes.

The screenshot in Figure 194, “in() Example” below shows how this would look in the LogScale interface.

in() Example

Figure 194. in() Example


There are a few other HTTP codes related to errors besides these two. You could list all of them in the array, or you could add the wildcard (i.e., *) like this:

logscale
in(status, values=["4*"])

This will return all events in which the status has a value starting with 4. Notice that even though only one value is given, you have to include the square-brackets. Also, notice that since the wildcard is used, the double-quotes is required.

Using the field parameter in addition to the =~ syntax:

logscale
in(field=loglevel, values=["ERROR", "WARN"])

Negating an in() filters:

logscale
!in(field=loglevel, values=["ERROR", "WARN"])

and

logscale
loglevel =~ !in(values=["ERROR", "WARN"])