Log Insight Query Building: Constraints

In my first post about querying building in Log Insight, I talked about using the search bar. Now, I would like to highlight the use of constraints.

Overview

Constraints in Log Insight are a way of further refining the results of a query. You can think of a constraint like database constraints in that they look for particular patterns in particular locations of an event. Constraints are added by selecting the Add Constraint button just below the search bar. Any number of constraints can be specified. A constraint is made up of two to three components as described in the following three sections.

log-insight-search-bar

Field

The first component of a constraint is a field. A field is similar to a column specification in a database constraint. By default, the field is set to text, which would refer to any part of the event. The field can be changed using a drop-down menu. In addition to the text field, any defined field within Log Insight can be selected. There are multiple types of fields in Log Insight and they roughly correlate to columns in a database. I will be covering fields in a future post and will be focusing on the text field in this post.

log-insight-constraint-text

Operator

The second component of a constraint is the operator. The operator dictates how to use the field.

log-insight-constraint-operation

The operators available are determined by the field selected:

  • For text-only fields, text-only operators are available.
  • For numeric-only fields, numeric-only operators are available.
  • For fields that cannot be guaranteed to be text or numeric, both sets of operators are available.

A few other details to be aware of with operators are:

  • The starts with operator is equivalent to a glob query (glob queries were covered in my previous query building post).
  • For any field, a matches regex operator exists, which makes it possible to construct Java-based regular expression matches in Log Insight.
  • If the exists operator is specified then the constraint is complete and no other components can be specified. For all other operators, a third component must be specified.

Value(s)

The third component of a construct is a comma separated list of values where values are:

  • Keywords
  • Phrases
  • Globs
  • Regular expressions

Values separated by commas form logical OR queries. For example, if the values specified for a text contains constraint were error, warning  then results would be return if an event contained the keyword error OR the keyword warning.

log-insight-constraint-values

Match

In addition to the ability to specify more than one constraint, a match option is available when two or more constraints have been added.

log-insight-constraint-match

The match option has two values:

  • All, which is equivalent to a logical AND operation and would require that each constraint specified return a match. This is the default value.
  • Any, which is equivalent to a logical OR operation and would require that only one constraint specified return a match.

Search bar versus constructs

There are several differences between a search bar query and a constraint query. These differences include:

  • The search bar supports keyword, phrase, and glob queries where constraint queries can contain fields and/or regular expressions.
  • The search bar supports a space separated list of keywords and/or phrases where constraint queries support a comma separated list of values.
  • Search bar queries separated by space form logical AND queries where constraint queries separated by comma form logical OR queries.
  • The search bar requires double quotations for phrase queries, but since constraint queries support values instead of keywords, double quotations are not required around phrases.

Summary

Some of the key takeaways for query building using constraints are:

  • General
    • Case insensitive queries
    • Complete keyword matching (alpha-numeric, hyphen, and/or underscore)
    • Special character queries via regular expressions only
    • Globs (* and ?) can be used to enhance keyword queries
  • Constraints
    • Any number of constraints can be defined
    • Constraints require at least a field and an operator
    • Unless the exists operator has been specified then a constraint must contain one or more values
    • Comma separated values are logical OR queries
    • Multiple constraint form logical AND queries by default via the match option, but can be changed to logical OR queries
    • Values that contain phrases do not need to be enclosed in double quotations
    • Regular expressions can be used with constraints with the matches regex operator

© 2013 – 2015, Steve Flanders. All rights reserved.

Leave a Reply