3.2 Configuring transaction Constraints: maxspan, maxpause, startswith, endswith

3.2 Configuring transaction Constraints: maxspan, maxpause, startswith, endswith

Quick Answer: The transaction command supports four critical constraint arguments to define transaction boundaries: maxspan sets the maximum total elapsed time between the first and last event in a transaction; maxpause sets the maximum allowable idle time between any two consecutive events; startswith defines the opening event condition; and endswith defines the closing event condition. Numeric values without units default to seconds, but time suffixes (s, m, h, d) can be appended. An event matching endswith is included as the final event in the transaction before it is closed.

---

1. The Need for Transaction Boundary Constraints

When grouping events by persistent identifiers—such as a static IP address, an employee username, or a long-lived device GUID—running an unconstrained | transaction username across a 30-day time window can cause severe analytical and architectural issues:

1. Unrealistic Megatransactions: Multiple unrelated user logins spanning weeks will be merged into a single multi-thousand-event transaction with a 700-hour duration.
2. Search Head Memory Exhaustion: The search head must maintain state for open transactions in RAM until the search concludes, risking memory limits and search degradation.
3. Distorted Latency Metrics: A user who logged in on Monday and logged in again on Friday would generate an artificial 4-day session duration.

To solve these challenges, Splunk provides two temporal constraints (maxspan, maxpause) and two event-matching boundary constraints (startswith, endswith).

+---------------------------------------------------------------------------------------------------+
|                              TRANSACTION CONSTRAINT TAXONOMY                                      |
+---------------------------------------------------------------------------------------------------+
|  maxspan:  |◄─────────────────────────── Total Elapsed Time ─────────────────────────────►|       |
|            |   Event 1 ───────> Event 2 ───────> Event 3 ───────> Event 4 ───────> Event 5   |       |
|  maxpause: |               |◄── Gap 1 ──►|   |◄── Gap 2 ──►|                                      |
|                                                                                                   |
|  startswith: Matches Event 1 (Opens transaction)                                                  |
|  endswith:   Matches Event 5 (Includes Event 5 and Closes transaction)                            |
+---------------------------------------------------------------------------------------------------+

---

2. Temporal Constraints: maxspan vs. maxpause

Understanding the exact mathematical difference between maxspan and maxpause is one of the most frequently tested topics on the Power User exam.

maxspan: Maximum Total Transaction Span

• Definition: Specifies the maximum allowable total time window between the first event ($T_0$) and the last event ($T_n$) in a single transaction.
• Syntax: maxspan=<integer>[s|m|h|d]
• Operational Behavior: If an event arrives with the same grouping field but its timestamp exceeds $T_0 + \text{maxspan}$, Splunk closes the current transaction at the previous event and begins a new transaction starting with the newly arrived event.
• Default Value: If omitted, there is no maximum total span limit (unbounded, constrained only by the search time range).

`-- Group events by clientip, ensuring no transaction exceeds 30 minutes total duration`
... | transaction clientip maxspan=30m

maxpause: Maximum Inter-Event Inactivity Gap

• Definition: Specifies the maximum allowable elapsed time between any two consecutive, adjacent events ($T_{i+1} - T_i$) within a transaction.
• Syntax: maxpause=<integer>[s|m|h|d]
• Operational Behavior: If the gap between two successive events with the same grouping ID exceeds maxpause, the idle pause triggers the completion of the current transaction. The subsequent event starts a new transaction.
• Default Value: If omitted, there is no inter-event pause limit (unbounded).

`-- Sessionize user activity, closing the session if the user is idle for more than 5 minutes`
... | transaction user maxpause=5m

Time Unit Parsing & The Default Seconds Trap

[!IMPORTANT] Critical Exam Rule: If you write | transaction user maxspan=15 maxpause=5, Splunk interprets 15 and 5 as 15 seconds and 5 seconds, NOT 15 minutes and 5 minutes! To specify minutes, you must explicitly append m (e.g., maxspan=15m maxpause=5m).

---

3. Timeline Scenarios: How Constraints Partition Events

Let's analyze how incoming events for a single user (user=alice) are partitioned under different combinations of maxspan and maxpause.

Raw Event Stream for user=alice:

• Event 1: 10:00:00
• Event 2: 10:04:00 (Gap from E1: 4 mins)
• Event 3: 10:12:00 (Gap from E2: 8 mins)
• Event 4: 10:15:00 (Gap from E3: 3 mins)
• Event 5: 10:25:00 (Gap from E4: 10 mins)
• Event 6: 10:28:00 (Gap from E5: 3 mins)

TIMELINE (Minutes past 10:00):
00      04              12   15                    25   28
E1──────E2──────────────E3───E4────────────────────E5───E6

Scenario A: | transaction user maxspan=20m

• Transaction 1 starts at E1 (10:00:00).
• E2 (10:04:00), E3 (10:12:00), and E4 (10:15:00) are included because $10:15 - 10:00 = 15\text{ mins} \le 20\text{ mins}$.
• E5 arrives at 10:25:00. Span from E1 is $25\text{ mins} > 20\text{ mins}$. E5 cannot join Transaction 1.
• Output:
  • Transaction 1: Events [E1, E2, E3, E4] | duration=15m (900s) | eventcount=4
  • Transaction 2: Events [E5, E6] | duration=3m (180s) | eventcount=2

Scenario B: | transaction user maxpause=5m

• Transaction 1 starts at E1 (10:00:00).
• E2 arrives at 10:04:00. Pause is 4 mins $\le 5\text{ mins}$. Joins Txn 1.
• E3 arrives at 10:12:00. Pause from E2 is 8 mins $> 5\text{ mins}$. Inactivity threshold breached! Txn 1 closes at E2. E3 starts Txn 2.
• E4 arrives at 10:15:00. Pause from E3 is 3 mins $\le 5\text{ mins}$. Joins Txn 2.
• E5 arrives at 10:25:00. Pause from E4 is 10 mins $> 5\text{ mins}$. Inactivity breached! Txn 2 closes at E4. E5 starts Txn 3.
• E6 arrives at 10:28:00. Pause from E5 is 3 mins $\le 5\text{ mins}$. Joins Txn 3.
• Output:
  • Transaction 1: Events [E1, E2] | duration=4m | eventcount=2
  • Transaction 2: Events [E3, E4] | duration=3m | eventcount=2
  • Transaction 3: Events [E5, E6] | duration=3m | eventcount=2

Scenario C: Combining Both | transaction user maxspan=20m maxpause=5m

• An event must satisfy both constraints. If either maxspan OR maxpause is exceeded, the transaction closes immediately.
• E1 and E2 form Txn 1 (E3 breaches maxpause).
• E3 and E4 form Txn 2 (E5 breaches maxpause).
• E5 and E6 form Txn 3.

---

4. Boundary Delimiters: startswith and endswith

In stateful processes (such as authentication handshakes, database transactions, or TCP connections), events are bounded by explicit initiation and termination markers.

Syntax & Supported Match Types:

... | transaction <fields> startswith=<match-expression> endswith=<match-expression>

Splunk supports three formats for startswith and endswith expressions:

`-- Real-world example: Tracking user session from login to logout or error`
index=web sourcetype=access_combined
| transaction user startswith="action=login" endswith=eval(action=="logout" OR status>=500) maxspan=4h

Exact Boundary Processing Rules:

1. Initiation (startswith):
   • When an event matches startswith, Splunk opens a new transaction.
   • If an existing transaction for that grouping key is already open, encountering a new startswith event immediately closes the prior transaction and starts a new one.
2. Termination (endswith):
   • When an event matches endswith, Splunk includes that matching event as the final event in the transaction and immediately marks the transaction as closed.
   • Any subsequent events with the same key will begin a fresh transaction.
3. Events Prior to startswith:
   • Events that arrive before the first startswith event for a given key will form an open, unstarted transaction (or be omitted depending on pipeline configuration).

+---------------------------------------------------------------------------------------------+
|                          BOUNDARY MATCHING STEP-BY-STEP FLOW                                |
+---------------------------------------------------------------------------------------------+
| Event 1: action=login      --> Matches startswith  --> Opens Txn A                          |
| Event 2: action=view_page  --> Regular event       --> Appended to Txn A                    |
| Event 3: action=login      --> Matches startswith  --> Closes Txn A; Opens Txn B            |
| Event 4: action=purchase   --> Regular event       --> Appended to Txn B                    |
| Event 5: action=logout     --> Matches endswith    --> Appended to Txn B; Closes Txn B      |
| Event 6: action=view_page  --> Regular event       --> Opens Txn C                          |
+---------------------------------------------------------------------------------------------+

---

5. Comprehensive transaction Parameter Comparison Matrix

The following reference matrix outlines all primary constraint arguments available in the transaction command:

---

6. Advanced Scenario Configurations

Scenario 1: Detecting Failed Login Bursts (Brute Force Detection)

index=auth sourcetype=secure_log action=failure
| transaction src_ip maxspan=5m maxpause=30s
| where eventcount >= 10
| table _time, src_ip, eventcount, duration

Analysis: Groups consecutive login failures from the same source IP within a 5-minute total window where failures occur with no more than 30 seconds between attempts. Filters for bursts of 10 or more failures.

Scenario 2: Tracking E-Commerce Cart Abandonment

index=web sourcetype=access_combined
| transaction JSESSIONID startswith=(uri="/cart/add") endswith=(uri="/checkout/success") maxspan=2h maxpause=15m
| search closed_txn=0
| table _time, JSESSIONID, duration, eventcount

Analysis: Initiates a transaction when an item is added to the cart and expects checkout success within 2 hours (and no 15-minute idle pause). Searching for closed_txn=0 instantly isolates abandoned carts.

---

7. Common Exam Traps & Pitfalls

• The Suffix Omission Error: Running maxspan=10 assuming it means 10 minutes. It means 10 seconds. Always write maxspan=10m.
• Inverted Constraints: Confusing maxspan with maxpause. Remember: maxspan is the total transaction lifespan; maxpause is the inter-event gap.
• endswith Inclusion: Exam questions frequently ask whether the event matching endswith is included in the closing transaction or starts the next one. Rule: The endswith event is included in the transaction it closes.
• Multiple startswith Invocations: If a user logs in, does not log out, and logs in again, the second login event closes the first transaction and opens a new one.