sequence

The command adds a sequence-match count and sequence details to each linked group. Groups without a matching sequence remain in the results with a sequence-match count of zero. To return only groups with matching sequences, append a filter such as | where s1 > 0, where s1 is the sequence name.

A sequence supports at most four rule steps and at most four selected output fields.

Syntax

sequence name = <name> [<sequence_options>] <match_rules> select <output_fields>

Topics:

• Parameters
• Understand Sequence Matching
• Specify Match Counts
• Differentiate span and maxpause
• Examples

Parameters

The following table lists the parameters used with this command, along with their descriptions.

Understand Sequence Matching

Each bracketed condition is a rule step. A rule step can match one or more log records, depending on its count constraint.

For example:

[ username != null ]{3,}
then [ hostname = abc ]{1,}

This expression contains two rule steps. The first step requires at least three matching records, and the second step requires at least one matching record that occurs after them.

The matched timeline might therefore contain the records A1, A2, A3, B1. Time constraints are evaluated against these individual matched records, not only against the two rule steps.

Use the matching operators as follows:

• then requires the rule steps to occur in the specified order.

• between defines a sequence using a start boundary and an end boundary. The sequence details include the matched boundary records and the intermediate matched records used during sequence evaluation; this does not mean that every record between the boundaries is returned.

Specify Match Counts

The count constraint applies separately to each rule step:

For example, {3} requires exactly three matching records, {3,} requires at least three matching records, while {2,10} requires between 2 and 10 matching records.

Differentiate span and maxpause

Use span to limit the total elapsed time of the complete matched sequence. Use maxpause to limit the time between each pair of adjacent matched records.

Consider a sequence candidate with the following matched records:

For this candidate:

• span = 20minute succeeds because the full sequence lasts 14 minutes.

• maxpause = 5minute fails because the gap between A2 and A3 is 10 minutes.

You can use span and maxpause together when the complete sequence must finish within a specified time and no adjacent matched records can have a longer gap than allowed.

Examples

1. Use a single rule with one condition

   The following command evaluates each group for records whose target type is Cluster Database and adds the sequence results to the group:

   * | link Severity
     | sequence name = s1
         [ 'Target Type' = 'Cluster Database' ]{1,}
         select 'Target Type'

   If you omit the count constraint, the rule requires at least one matching record:

   * | link Severity
     | sequence name = s1
         [ 'Target Type' = 'Cluster Database' ]
         select 'Target Type'

   To return only groups with a matching sequence, append | where s1 > 0.

2. Return fields that differ from the matching fields

   The condition can use one field while select returns other fields from the matched records. The following command matches cluster database records and returns their targets:

   * | link Severity
     | sequence name = s1
         [ 'Target Type' = 'Cluster Database' ]{1,}
         select Target

3. Use multiple conditions in a rule

   A record must satisfy all the conditions in a rule to contribute to the rule match. The following command matches cluster database records that have a log source:

   * | link Severity
     | sequence name = s1
         [ 'Log Source' != null
           and 'Target Type' = 'Cluster Database' ]{1,}
         select 'Target Type', Target

   The following example also restricts matches by user and content size:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' != random
           and 'User Name' != null
           and 'Content Size' > 100 ]{1,}
         select 'User Name', 'Content Size', 'Event Target Type'

4. Control the number of matches for a rule

   Use {min,} to specify only a minimum:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' = rac_database ]{101,}
         select 'User Name'

   Use {1,max} to set a maximum while requiring at least one match:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' = rac_database
           and 'User Name' != null ]{1,100}
         select 'User Name'

   Use {min,max} to require a bounded number of matches:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' = rac_database
           and 'User Name' != null ]{101,500}
         select 'User Name'

   Counts are evaluated separately for each rule step.

5. Find ordered rules with then

   The following two-step sequence finds cluster database records followed by host records:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' = rac_database ]{1,}
         then [ 'Event Target Type' = host ]{1,}
         select 'Event Target Type'

   The following command defines a three-step sequence. Each rule has its own match count:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' = rac_database ]{1,}
         then [ 'Event Target Type' = host ]{1,10}
         then [ 'Event Target Type' = fusion_apps_j2ee_app ]{1,}
         select 'Event Target Type'

   The following command defines a four-step sequence:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' = rac_database
           and 'User Name' != random ]{1,}
         then [ 'Event Target Type' = host
                and 'Content Size' > 100 ]{1,}
         then [ 'Event Target Type' = fusion_apps_j2ee_app ]{1,}
         then [ 'Event Target Type' = rac_database
                and 'User Name' != random ]{1,}
         select 'Event Target Type', 'User Name', 'Content Size'

6. Use then with multiple conditions and separate output fields

   Each rule can contain multiple conditions, while select returns additional fields for analysis:

   * | link Severity
     | sequence name = s1
         [ 'Event Target Type' = rac_database
           and 'Content Size' > 100 ]{1,}
         then [ 'Event Target Type' = host ]{1,}
         then [ 'Event Target Type' = fusion_apps_j2ee_app ]{1,}
         select 'Event Target Type', 'User Name', 'Content Size'

7. Apply span to a single-rule sequence

   For a single rule, span limits the total time from the earliest matched record to the latest matched record. The following command requires at least two matching records within five minutes:

   * | link Severity
     | sequence name = s1 span = 5minute
         [ 'Event Target Type' != null
           and 'User Name' != null ]{2,}
         select 'Event Target Type', 'User Name'

8. Apply span to an ordered multi-rule sequence

   For multiple rules, span applies to the complete sequence. The following three-step sequence must fit within two days:

   * | link Severity
     | sequence name = s1 span = 2day
         [ 'Event Target Type' = rac_database
           and 'Content Size' > 100
           and 'User Name' != null ]{100,}
         then [ 'Event Target Type' = host ]{100,}
         then [ 'Event Target Type' = fusion_apps_j2ee_app ]{100,}
         select 'Event Target Type', 'Content Size', 'User Name'

9. Find records between two inclusive boundaries

   Use between when the pattern has a start boundary and an end boundary. The boundary records are included in the returned sequence details:

   * | link Severity
     | sequence name = s1
         between
           [ 'Event Target Type' = rac_database
             and 'Content Size' > 0
             and 'User Name' != null ]{1,}
         and
           [ 'Event Target Type' = fusion_apps_j2ee_app ]{1,}
         select 'Event Target Type', 'Content Size', 'User Name'

10. Use between with span

    When span is used with between, the time from the matched start boundary through the matched end boundary must be within the specified duration:

    * | link Severity
      | sequence name = s1 span = 2day
          between
            [ 'Event Target Type' = rac_database
              and 'Content Size' > 100
              and 'User Name' != null ]{100,}
          and
            [ 'Event Target Type' = fusion_apps_j2ee_app ]{100,}
          select 'Event Target Type', 'Content Size', 'User Name'

11. Apply maxpause to a single-rule sequence

    For a single rule, maxpause limits the time between adjacent records chained together to satisfy that rule. The following command allows no more than five minutes between adjacent matching records:

    * | link Severity
      | sequence name = s1 maxpause = 5minute
          [ 'Event Target Type' = rac_database
            and 'User Name' != null ]{100,}
          select 'Event Target Type', 'Content Size', 'User Name'

12. Use maxpause with then or between

    With then, maxpause applies within each rule match and across transitions between rules:

    * | link Severity
      | sequence name = s1 maxpause = 15hour
          [ 'Event Target Type' = rac_database
            and 'User Name' != null ]{1,}
          then [ 'Event Target Type' = host ]{1,}
          select 'Event Target Type', 'Content Size', 'User Name'

    The same behavior applies to a sequence defined by between:

    * | link Severity
      | sequence name = s1 maxpause = 17hour
          between
            [ 'Event Target Type' = rac_database
              and 'User Name' != null ]{1,}
          and
            [ 'Event Target Type' = fusion_apps_j2ee_app ]{1,}
          select 'Event Target Type', 'Content Size', 'User Name'

13. Use span and maxpause together

    Use both options when the complete sequence must fit within an overall time window and every adjacent gap must remain within a smaller limit.

    The following boundary-style sequence must finish within two days, with no adjacent gap exceeding 17 hours:

    * | link Severity
      | sequence name = s1 span = 2day maxpause = 17hour
          between
            [ 'Event Target Type' = rac_database
              and 'User Name' != null
              and 'Content Size' > 100 ]{100,}
          and
            [ 'Event Target Type' = fusion_apps_j2ee_app ]{100,}
          select 'Event Target Type', 'Content Size', 'User Name'

    The following ordered sequence applies the same two constraints:

    * | link Severity
      | sequence name = s1 span = 2day maxpause = 17hour
          [ 'Event Target Type' = rac_database
            and 'User Name' != null
            and 'Content Size' > 100 ]{100,}
          then [ 'Event Target Type' = host ]{100,}
          then [ 'Event Target Type' = fusion_apps_j2ee_app ]{100,}
          select 'Event Target Type', 'Content Size', 'User Name'

14. Use computed fields and subqueries in rules

    Rules can contain subquery operations such as where:

    * | link Severity
      | sequence name = s1
          [ Target != slc03qoo
            | where substr(Target, 0, 3) = slc ]
          select Target

    A sequence can also use a field computed earlier in the pipeline:

    * | eval color =
          if(Severity = debug
             or Severity = fine
             or Severity = finer
             or Severity = info,
             green,
             if(Severity = warn, yellow, red))
      | link Target
      | sequence name = s1
          between [ * | where color = red ]{3}
          and [ * | where color = yellow ]{1,}
          select color

    The start rule requires exactly three records where color is red; the end rule requires at least one record where color is yellow.

15. Use sequence output in downstream commands

    Sequence output fields, including the sequence count, can be used by commands later in the pipeline.

    The following command calculates the average and total number of sequence matches across the linked groups, including groups with zero matches:

    * | link Target
      | sequence name = 'My Field'
          [ Severity != null ]
          select Severity
      | eventstats
          avg('My Field'),
          sum('My Field')

    The following command compares the sequence results with results from three days earlier:

    * | link Target
      | sequence name = s1
          [ 'Target Type' = 'Cluster Database' ]
          select 'Target Type'
      | compare timeshift = -3d

    The field named by name contains the number of sequence matches in each linked group.