Grammar Subset

Filter ::= LogicalAndFilter

LogicalAndFilter ::=
  LogicalOrFilter ('AND'? LogicalOrFilter)*

LogicalOrFilter ::=
  UnaryFilter ('OR' UnaryFilter)*

UnaryFilter ::=
  'NOT'* PrimaryFilter

PrimaryFilter ::=
  FieldName '=' EqualityPattern |
  FieldName 'like' LikePattern |
  FieldName '!=' EqualityPattern |
  FieldName '<' Number |
  FieldName '<=' Number |
  FieldName '>' Number |
  FieldName '>=' Number |
  FreeTextPattern |
  'true' |
  'false' |
  '(' Filter ')'

FieldName ::= UnquotedFieldName | QuotedString

A Filter (filter expression) can be a step in a pipeline. Filter is a less general kind of expression compared to an expression. Neither is a subset of the other, but Filter is particularly quirky.

Implicit AND is supported in the Filter production so be aware that this:

foo < 42 + 3

means:

(foo < 42) AND "*+*" AND "*3*"

LogicalOrFilter1 LogicalOrFilter2 is shorthand for LogicalOrFilter1 AND LogicalOrFilter2.

LogicalOrFilter1 AND LogicalOrFilter2 is shorthand for LogicalOrFilter1 | LogicalOrFilter2.

UnaryFilter1 OR UnaryFilter2 is shorthand for case { UnaryFilter1; UnaryFilter2 }.

However, UnaryFilter1 and UnaryFilter2 cannot be a Regex with named groups.

FreeTextPattern ::=
  UnquotedPattern | QuotedString | Regex | QueryParameter

LikePattern ::=
  UnquotedPattern | QuotedString | QueryParameter

EqualityPattern ::=
  AnchoredPattern | Regex | QueryParameter

AnchoredPattern ::=
  UnquotedPattern | QuotedString

When UnquotedPattern or QuotedString are used as patterns, the asterisk character (*) is a wildcard, meaning that it matches anything. The wildcard cannot be escaped. Regular expressions can be used to search for *.

Patterns are sensitive to case. For example, MyClass matches MyClass, but not myclass. Regular expressions can be used to disable case sensitivity in matches using the i flag.

QueryParameter ::=
  '?' QueryParameterName 
  | '?{' QueryParameterName '=' QueryParameterDefaultValue '}'

QueryParameterName ::= UnquotedPattern 
| QuotedString

QueryParameterDefaultValue ::= UnquotedPattern 
| QuotedString

A query can be parameterized so that some patterns can be specified later. This is useful, for example, in dashboard widgets: see some ???.

Arguments to queries are never interpreted as regular expressions. Consider, for example, this query:

class = ?my_class

This query has one query parameter my_class. If the value for my_class is set to /MyClass/, it is equivalent to:

class = "/MyClass/"

Not to:

class = /MyClass/

UnquotedPattern

UnquotedFieldName

An UnquotedPattern is a non-empty sequence of characters.

An UnquotedFieldName is a non-empty sequence of characters.

The exact characters supported is beyond the scope of this document — see Appendix C, Character Table for a table of which characters are supported in the character set ISO/IEC 8859-1. LogScale accepts the full Unicode character set, but not all details are included here. We recommend limiting to Unicode identifiers for UnquotedPattern and UnquotedFieldName.

The reserved character / is also supported in UnquotedPattern. However, an UnquotedPattern cannot start with / (one slash) and cannot end with // (two slashes). See Slashes for more information on slashes.

QuotedString

A QuotedString is a sequence of characters surrounded by ". A QuotedString cannot span multiple lines, but \n can be used to include the newline character. \" can be used to include " in the string. \\ can be used to include the character \, and we recommend not including any other sequences of \ in quoted strings.

Regex

A Regex is a sequence of characters surrounded by /.

A Regex cannot span multiple lines, but \n can be used to include the newline character.

\/ can be used to include \ in the regular expression. Other characters can also be preceeded by \ in regular expressions.

For more information, see Regular Expression Syntax Patterns.

By default, regular expressions are not anchored, see Anchored Patterns.

A regular expression can be followed by flags. The supported flags are d, m, and i.

Number

Numbers in LogScale are decimals with optional floating point or scientific notation.

FunctionCall ::= FunctionName '(' FunctionArguments? ')'

FunctionArguments ::=
    NamedFunctionArgument (',' FunctionArguments)? |
    UnnamedFunctionArgument (',' FunctionArguments)?

NamedFunctionArgument ::=
    FieldName '=' Expression

UnnamedFunctionArgument ::=
    Expression

One occurrence of UnnamedFunctionArgument at most is supported in FunctionArguments.

Expression ::=
  Expression ComparisonOperator AdditiveExpression |
  AdditiveExpression

From v1.192 the expression syntax has been updated to support expression attributes:

Expression ::=
  ComparativeExpression ExpressionAttribute*

ExpressionAttribute ::=
  Identifier ':' ComparativeExpression

ComparativeExpression ::=
  Expression ComparisonOperator AdditiveExpression |
  AdditiveExpression

ComparisonOperator ::=
  '==' | '!=' | '>=' | '<=' | '>' | '<'

From v1.192, a modified format of this syntax is available to support the link operator:

ComparisonOperator ::=
  '==' | '!=' | '>=' | '<=' | '>' | '<' | '<=>'

AdditiveExpression ::=
  AdditiveExpression AdditiveOperator MultiplicativeExpression |
  MultiplicativeExpression

AdditiveOperator ::=
  '+' | '-'

MultiplicativeExpression ::=
  MultiplicativeExpression MultiplicativeOperator UnaryExpression |
  UnaryExpression

MultiplicativeOperator ::=
  '*' | '/' | '%'

UnaryExpression ::=
  UnaryOperator? PrimaryExpression

UnaryOperator ::=
  '-' | '!'

PrimaryExpression ::=
  '(' Expression ')' |
  Subquery |
  FunctionCall |
  ArrayExpression |
  QueryParameter |
  BareWord |
  QuotedString

Subquery ::= '{' Pipeline '}'

From v1.192, a modified format of this syntax is available to support an identifier within the subquery clause:

Subquery ::= ( Identifier ':' )? '{' Pipeline '}'

Where Identifier is a regular expression matching /[a-z][a-z0-9_]*/i.

An Expression is similar to an expression from general purpose languages, such as Java or C. It is used as an argument to functions or the right-hand side of := (Eval Shorthand).

BareWord ::=
  FieldName |
  UnquotedPattern

Caveat: UnquotedPattern is only used if it starts with a character that cannot start a FieldName. For example, */*/*https://www.example.com/ is a BareWord, but https:*/*/*https://www.example.com/ isn't.

EvalFunctionShorthand ::=
 FieldName ':=' FunctionCall

Shorthand for adding as=FieldName to argument list of FunctionCall.

EvalShorthand ::=
  FieldName ':=' Expression

Shorthand for:

eval(FieldName = Expression)

Note that eval() does not support ArrayExpression and Subquery expressions.

FieldShorthand ::= FieldName '=~' FunctionCall

Shorthand for adding field=FieldName to argument list of FunctionCall.

Case ::=
  'case' '{' Pipeline (';' Pipeline)* '}'

Runs each pipeline in sequence until one matches an event.

Match ::=
  FieldName 'match' '{' MatchPipeline (';' MatchPipeline)* '}'

MatchPipeline ::=
  MatchGuard => Pipeline

MatchGuard ::=
  '*'
  Regex |
  FunctionCall |
  QueryParameter |
  AnchoredPattern

Match evaluates the first Pipeline whose MatchGuard matches the current event. Match is not a shorthand for Case.

A MatchGuard is evaluated as follows:

If MatchGuard is on the form '*', the current event is matched.

Surprisingly enough, this is equivalent to *, not MyField = *. In other words, not a field existence test.

Otherwise, if MatchGuard is on the form Regex, the current event is matched if this matches: FieldName = Regex.

Otherwise, if MatchGuard is on the form FunctionCall, the current event is matched if this matches: FieldName =~ FunctionCall.

Otherwise, if MatchGuard is on the form AnchoredPattern, the current event is matched if this matches: FieldName=~ AnchoredPattern.

StatsShorthand ::= ArrayExpression

[ e1 , e2 , … , e3 ] is shorthand for stats([ e1 , e2 , … , e3 ]).