[DOCS] EQL: Document maxspan keyword (#58931) (#59223)

docs/reference/eql/limitations.asciidoc

@@ -42,6 +42,4 @@ queries that contain:
 ** {eql-ref}/pipes.html#unique[`unique`]
 ** {eql-ref}/pipes.html#unique-count[`unique_count`]
 
-* {eql-ref}/sequences.html[State and timespan-related sequence keywords]:
-** `with maxspan`
-** `until`
+* The `until` {eql-ref}/sequences.html[sequence keyword]

docs/reference/eql/search.asciidoc

@@ -257,7 +257,28 @@ the https://en.wikipedia.org/wiki/Unix_time[Unix epoch], in ascending order.
 ----
 // TESTRESPONSE[s/"took": 60/"took": $body.took/]
 
-You can further constrain matching event sequences using the `by` keyword.
+You can use the <<eql-with-maxspan-keywords,`with maxspan` keywords>> to
+constrain a sequence to a specified timespan.
+
+The following EQL search request adds `with maxspan=1h` to the previous query.
+This ensures all events in a matching sequence occur within one hour (`1h`) of
+the first event's timestamp.
+
+[source,console]
+----
+GET /sec_logs/_eql/search
+{
+  "query": """
+    sequence with maxspan=1h
+      [ file where file.name == "cmd.exe" ]
+      [ process where stringContains(process.name, "regsvr32") ]
+  """
+}
+----
+// TEST[s/search/search\?filter_path\=\-\*\.sequences\.events\.\*fields/]
+
+You can further constrain matching event sequences using the
+<<eql-by-keyword,`by` keyword>>.
 
 The following EQL search request adds `by agent.id` to each event item. This
 ensures events matching the sequence share the same `agent.id` field value.
@@ -267,7 +288,7 @@ ensures events matching the sequence share the same `agent.id` field value.
 GET /sec_logs/_eql/search
 {
   "query": """
-    sequence
+    sequence with maxspan=1h
       [ file where file.name == "cmd.exe" ] by agent.id
       [ process where stringContains(process.name, "regsvr32") ] by agent.id
   """
@@ -283,7 +304,7 @@ prior one.
 GET /sec_logs/_eql/search
 {
   "query": """
-    sequence by agent.id
+    sequence by agent.id with maxspan=1h
       [ file where file.name == "cmd.exe" ]
       [ process where stringContains(process.name, "regsvr32") ]
   """

docs/reference/eql/syntax.asciidoc

@@ -229,7 +229,7 @@ The `process.args_count` field is a <<number,`long`>> integer field containing a
 count of process arguments.
 
 A user might expect the following EQL query to only match events with a
-`process.args_count` value of `4`. 
+`process.args_count` value of `4`.
 
 [source,eql]
 ----
@@ -389,7 +389,7 @@ sequence
 .*Example*
 [%collapsible]
 ====
-The following EQL query matches this series of ordered events:
+The following EQL sequence query matches this series of ordered events:
 
 . Start with an event with:
 +
@@ -407,6 +407,43 @@ sequence
 ----
 ====
 
+[discrete]
+[[eql-with-maxspan-keywords]]
+==== `with maxspan` keywords
+
+You can use the `with maxspan` keywords to constrain a sequence to a specified
+timespan. All events in a matching sequence must occur within this duration,
+starting at the first event's timestamp.
+
+The `maxspan` keyword accepts <<time-units,time value>> arguments.
+
+[source,eql]
+----
+sequence with maxspan=30s
+  [ event_category_1 where condition_1 ] by field_baz
+  [ event_category_2 where condition_2 ] by field_bar
+  ...
+----
+
+.*Example*
+[%collapsible]
+====
+The following sequence query uses a `maxspan` value of `15m` (15 minutes).
+Events in a matching sequence must occur within 15 minutes of the first event's
+timestamp.
+
+[source,eql]
+----
+sequence with maxspan=15m
+  [ file where file.extension == "exe" ]
+  [ process where true ]
+----
+====
+
+[discrete]
+[[eql-by-keyword]]
+==== `by` keyword
+
 You can use the `by` keyword with sequences to only match events that share the
 same field values. If a field value should be shared across all events, you
 can use `sequence by`.
@@ -422,7 +459,8 @@ sequence by field_foo
 .*Example*
 [%collapsible]
 ====
-The following sequence uses the `by` keyword to constrain matching events to:
+The following sequence query uses the `by` keyword to constrain matching events
+to:
 
 * Events with the same `user.name` value
 * `file` events with a `file.path` value equal to the following `process`
@@ -447,6 +485,34 @@ sequence by user.name
 ----
 ====
 
+You can combine the `sequence by` and `with maxspan` keywords to constrain a 
+sequence by both field values and a timespan.
+
+[source,eql]
+----
+sequence by field_foo with maxspan=30s
+  [ event_category_1 where condition_1 ] by field_baz
+  [ event_category_2 where condition_2 ] by field_bar
+  ...
+----
+
+.*Example*
+[%collapsible]
+====
+The following sequence query uses the `sequence by` keyword and `with maxspan`
+keywords to match only a sequence of events that:
+
+* Share the same `user.name` field values
+* Occur within `15m` (15 minutes) of the first matching event
+
+[source,eql]
+----
+sequence by user.name with maxspan=15m
+  [ file where file.extension == "exe" ] by file.path
+  [ process where true ] by process.path
+----
+====
+
 [discrete]
 [[eql-functions]]
 === Functions