# Transactions Advanced Options

> Chapter 14 of the Courseiva SPLUNK-CORE-CERTIFIED-POWER-USER curriculum — https://courseiva.com/learn/splunk-core-certified-power-user/transactions-advanced-options

**Official objective:** 4.2 — Apply advanced transaction options such as maxspan, maxpause, and keepevicted.

## Introduction

Transactions Advanced Options. They solve a fundamental headache: when you use the basic `transaction` command, Splunk groups events that share a common field, but it stops too early or runs too long, giving you false picture of what happened. For the SPLK-1003 exam, mastering `maxspan`, `maxpause`, and `keepevicted` is the difference between passing and failing the transaction questions — they are the most frequently tested advanced transaction parameters.

## The Backyard Barbecue Host Analogy

Have you ever hosted a barbecue where guests arrive, eat, chat, and leave at different times? You want to group each guest's actions—arrival, eating a burger, having dessert, leaving—into a single story per person, not a jumbled mess of everyone's moves.

So you make a rule: any actions from the same person within 30 minutes of each other count as one visit. That's like the basic `transaction` command. But what if your friend Bob leaves to grab more ice and comes back 45 minutes later? Your 30-minute rule splits Bob's visit into two transactions, even though it was one trip. Not great.

Now imagine you get smarter. You add a **maxpause** — you say, 'I'll wait up to 2 hours between Bob's actions before I split them.' That lets Bob get ice without breaking his story. But then you realise the whole barbecue only lasts 4 hours. So you add a **maxspan** — nothing can be longer than 4 hours total, even if Bob somehow hung around all day. Finally, you keep a log of the people you kicked out because they didn't finish within the time limits—that's **keepevicted**. You don't discard their data; you keep it for a separate review. In Splunk, these options turn a blunt tool into a scalpel for connecting related events.

## Core explanation

In Splunk, a **transaction** is a way of grouping related events together into a single logical unit. Think of it like stitching together separate snapshots to make a movie. By default, when you write something like `... | transaction user_id`, Splunk finds events that share the same `user_id` field and bundles them together. But the default behaviour has a critical limitation: it uses a **default 120-second pause** (no event arrives for 120 seconds) to decide when to close a transaction. This works poorly for slow processes.

The three advanced options — `maxspan`, `maxpause`, and `keepevicted` — give you precise control over how transactions start, continue, and end. Let's break them down.

**maxspan** defines the absolute maximum total time a single transaction can cover, from its very first event to its very last event. If `maxspan=10m`, any transaction that starts and has not ended after 10 minutes is forcibly closed at the 10-minute mark. This prevents a single transaction from running forever if events trickle in slowly. For example, if you are tracking a user's shopping cart session, you know a real session never lasts longer than 1 hour — setting `maxspan=1h` cuts off any transaction that tries to exceed that.

**maxpause** sets the maximum allowed time gap between consecutive events inside one transaction. If `maxpause=5m`, Splunk waits 5 minutes after the last event. If no new event arrives in that window, it closes the transaction. If a new event arrives before the pause expires, the clock resets. This is brilliant for grouping events that should be close together but could have occasional gaps. For example, a user clicking through pages on a website might pause for 3 minutes to read an article. A `maxpause=10m` would keep them in the same session.

**keepevicted** changes what happens to events that get kicked out of a transaction because of the time limits above. Without `keepevicted`, those orphaned events are discarded — they vanish from your result set. With `keepevicted=true`, Splunk outputs them as single-event transactions (a transaction containing just that one event). This is crucial for auditing. If you want to know which events were broken off (evicted), you can see them instead of wondering where data went.

Here is how they work together in a real Splunk search:

```
sourcetype=access_combined
| transaction clientip maxspan=30m maxpause=5m keepevicted=true
```

This tells Splunk: group events by `clientip`. Let any single transaction last at most 30 minutes. Wait up to 5 minutes between events before closing. And show me the events that got cut off as their own tiny transactions.

Why do you need these options? Without them:
- A long-running process like a file download that pauses for 3 minutes would split into multiple transactions (bad).
- A transaction that never finishes (e.g., a zombie session) would grow forever, consuming memory (bad).
- Lost events would simply disappear — you would never know they were excluded (very bad).

In older Splunk versions, users had to chain multiple commands or use complex `eval` logic to approximate this behaviour. The `transaction` command with advanced options replaced all that workarounds. It is now the standard way to group events into meaningful sessions.

The important detail: these options only work inside the `transaction` command. They are not available in `stats` or `eventstats`. You must write `... | transaction [field] [options]`.

Finally, a nuance for the exam: `maxspan` is always measured from the timestamp of the *first* event. `maxpause` resets on each new event. `keepevicted` does not change the transaction logic itself — it only changes the output behaviour. Memorise that.

## Real-world context

Imagine you work in IT support for an online retail company. Your boss says, 'Find every customer session where someone looked at a product, added it to the cart, and then abandoned the cart without checking out.' Your company's web server logs every page click, API call, and button press. Each event has a `session_id` field.

Without transactions, you would have thousands of individual events — clicks on product pages, AJAX calls to update the cart, abandonment events. You need to group them by session. Here is the step-by-step scenario:

1. You write a search: `sourcetype=web_log | transaction session_id`. But you immediately notice problems. Some customers spend 5 minutes reading reviews, and Splunk's default 120-second pause splits their session into two. You miss the abandonment because the second 'session' never shows the cart action.

2. You add `maxpause=10m`. Now, a customer who pauses for 5 minutes to read stays in the same transaction. You see the full journey: browse, add to cart, hesitate, leave. The transactions now correctly capture the 15-minute sessions.

3. But now another problem emerges: a few sessions are 3 hours long. These are likely bots or users who left a tab open. They consume memory and distort averages. You add `maxspan=1h`. Any session longer than 60 minutes is forcibly closed. This keeps your result set clean.

4. Finally, your boss asks, 'How many sessions did we cut off? I want to see the data from those cut-off sessions.' Without `keepevicted`, those truncated events are gone. You add `keepevicted=true`. Now, every bot session that exceeded 1 hour shows up as a separate 1-event transaction. You can count them, analyse them, or filter them.

Here is the actual search you use:

```
sourcetype=web_log
| transaction session_id maxspan=1h maxpause=10m keepevicted=true
| search duration>0
| stats count by status
```

- You first group all events into transactions using the advanced time options.
- `keepevicted=true` ensures no event is silently dropped.
- You then filter to only completed transactions (duration > 0) and count how many resulted in checkout vs abandonment.

This is exactly what senior Splunk administrators do daily. They do not just write `transaction` — they tune `maxspan` and `maxpause` based on business knowledge. For example, if you know a customer never spends more than 2 minutes on a checkout page, you set `maxpause=2m` to close transactions quickly. If you are tracking a multi-step API call that takes 10 seconds between steps, you set `maxpause=30s` to avoid splitting mid-call.

The key lesson: `maxspan` and `maxpause` are not random numbers. They come from understanding the process you are monitoring. A banking transfer might take seconds (`maxpause=1m`). A customer service ticket might take days (`maxspan=48h`). Always calibrate these values.

## Exam focus

The SPLK-1003 exam tests `maxspan`, `maxpause`, and `keepevicted` in very specific, repeatable ways. Here is exactly what you will see and how to handle it.

**Question Type 1: Direct Syntax Knowledge**
The exam will ask: 'Which transaction option ensures a transaction automatically closes after 10 minutes, regardless of new events?' The correct answer is `maxspan`. The trap: `maxpause` also involves time, but it is about gaps *between* events, not total duration. Another trap: they might offer `maxevents` (real option) but `maxevents` limits the number of events, not time. Remember: `maxspan` = total duration ceiling.

**Question Type 2: The Effect of `keepevicted`**
They will ask something like: 'What does the `keepevicted=true` option do when used with `maxspan`?' The correct answer: 'It outputs events that were evicted from a transaction as single-event transactions instead of discarding them.' The trap: they might say 'It prevents transactions from closing' or 'It changes the pause time.' No. `keepevicted` changes *output*, not *grouping logic*.

**Question Type 3: Combining Options**
A scenario question: 'A user's events arrive at timestamps 0:00, 0:05, 0:08, 0:20, and 0:25. Given `maxspan=15m` and `maxpause=3m`, which events form a transaction?' Correct answer: Only events at 0:00, 0:05, and 0:08. The gap from 0:08 to 0:20 is 12 minutes, which exceeds `maxpause=3m`, so the transaction closes at 0:11 (last event + 3m pause). Then 0:20 and 0:25 are a second transaction (gap of 5 minutes exceeds 3m, but wait — actually the gap from 0:20 to 0:25 is 5 minutes, which exceeds `maxpause=3m`, so they split into two separate single-event transactions, or are evicted if `keepevicted` is off). This kind of time-line reasoning appears every exam.

**Question Type 4: Default Behaviour**
They might ask: 'If you do not specify `maxpause`, what does Splunk use?' The default is 120 seconds. Know this number. They may also ask about `maxspan`: it has no default — you must set it explicitly, or transactions can run indefinitely.

**Key definitions to memorise:**
- `maxspan`: max total time from first to last event in a transaction
- `maxpause`: max allowed gap between consecutive events
- `keepevicted`: when true, retains evicted events as single-event transactions; when false (default), evicted events are discarded
- `maxevents`: max number of events in one transaction (different from time options)

**Common trap patterns:**
- Confusing `maxpause` with `maxspan` in scenario questions. Always ask: 'Is this about the total window or the gap between events?'
- Thinking `keepevicted` affects how transactions are formed. It does not — it only affects what appears in the output.
- Assuming `maxevents` is a time option. It is a count option.
- Forgetting that `maxspan` is measured from the *first* event's timestamp, not from when you start the search.

The exam loves comparing these three options side by side. Practise writing the command: `... | transaction field maxspan=5m maxpause=1m keepevicted=true`. Then mentally trace which events group together.

## Step by step

1. **Identify the Common Identifier** — Determine which field groups events together. This is typically `session_id`, `user_id`, or `transaction_id`. Without this common field, Splunk cannot link events into a transaction.
2. **Set the maxpause Value** — Choose a value slightly longer than the longest expected gap between consecutive events. For example, if users pause 2 minutes between page clicks, set `maxpause=3m`. This prevents legitimate sessions from splitting.
3. **Set the maxspan Value** — Choose a value equal to the maximum realistic total duration of the process you are tracking. For a web session, 1 hour is common. For an API call, 5 seconds. This prevents runaway transactions.
4. **Decide on keepevicted** — Ask: 'Do I need to see the events that got cut off?' If you are debugging why sessions are incomplete, set `keepevicted=true`. If you only want clean, complete sessions, leave it `false` (default).
5. **Write the Transaction Command** — Combine the field and all three options: `... | transaction session_id maxspan=30m maxpause=5m keepevicted=true`. Test with a small time range first to verify group logic.
6. **Verify with stats** — Run `stats count by _time` on the transaction result to check if transactions are being closed too early or too late. Adjust `maxpause` and `maxspan` iteratively based on real data patterns.

## Comparisons

### maxspan vs maxpause

**maxspan:**
- Sets total time limit for whole transaction
- Measured from first event timestamp
- Transaction closes forcibly at limit regardless of new events

**maxpause:**
- Sets max gap between consecutive events
- Resets each time a new event arrives
- Transaction closes only when no event arrives within pause window

### keepevicted=true vs keepevicted=false (default)

**keepevicted=true:**
- Evicted events appear as single-event transactions
- Increases total transaction count
- Useful for debugging or auditing incomplete sessions

**keepevicted=false (default):**
- Evicted events are discarded entirely
- Result set only contains complete transactions
- Best for clean data analysis without noise

### transaction with options vs stats with time bins

**transaction with options:**
- Groups events into logical sessions
- Preserves full event details
- Supports maxspan and maxpause for flexible grouping

**stats with time bins:**
- Aggregates events into fixed time buckets
- Loses individual event context
- Cannot model variable-length sessions with gaps

### maxevents vs maxspan

**maxevents:**
- Limits by count of events (e.g., max 10 events)
- Closes transaction when event count is reached
- Ignores timestamps

**maxspan:**
- Limits by elapsed time (e.g., max 30 minutes)
- Closes transaction when time window expires
- Ignores event count

## Diagram

_Flowchart showing how advanced transaction options (maxpause, maxspan, keevevicted) control the grouping and output of events._

```mermaid
flowchart TD
    A[Raw Events] --> B{Does field match?}
    B -- Yes --> C[Group into pending transaction]
    B -- No --> D[Create new transaction]
    C --> E{Time gap > maxpause?}
    E -- Yes --> F[Close current transaction]
    E -- No --> G[Add event to transaction]
    F --> H{Total time > maxspan?}
    H -- Yes --> I[Force close transaction]
    H -- No --> J[Transaction continues]
    I --> K{keepevicted=true?}
    K -- Yes --> L[Output evicted as single-event transaction]
    K -- No --> M[Discard evicted events]
    L --> N[Final output: normal + single-event transactions]
    M --> N
```

## Common misconceptions

- **Misconception:** `maxpause` sets the total maximum time a transaction can last. **Reality:** `maxpause` sets the maximum allowed gap between consecutive events within a transaction. The total duration is controlled by `maxspan`. (Both options involve time, and beginners often confuse 'pause' (gap) with 'span' (total window).)
- **Misconception:** If you don't set `maxspan`, transactions can never close. **Reality:** Transactions close when the `maxpause` timer expires after the last event. `maxspan` only sets an upper limit; without it, a transaction can still close via `maxpause`. (New users think a transaction needs an explicit end time. But the pause timer is the default ending mechanism.)
- **Misconception:** `keepevicted=true` prevents eviction from happening. **Reality:** `keepevicted` does not prevent eviction; it only changes what happens to already-evicted events — it outputs them as single-event transactions instead of discarding them. (The word 'keep' suggests preservation, so users think it stops the eviction process itself. It only preserves the output.)
- **Misconception:** `maxevents` is an advanced time option like `maxpause`. **Reality:** `maxevents` limits the count of events in a transaction, not time. It is a separate type of limit. (Both options start with 'max', leading users to group them together mentally, but one limits count and the other limits time.)
- **Misconception:** `maxspan` resets every time a new event is added to the transaction. **Reality:** `maxspan` is measured from the timestamp of the *first* event in the transaction. It does not reset on subsequent events. (Beginners assume all time-based options reset like `maxpause`, but `maxspan` is a fixed window from the start.)
- **Misconception:** If you use `keepevicted=true`, the transaction count will always be higher than without it. **Reality:** It will be higher only if events were evicted. If no events are evicted (e.g., all transactions fit within `maxspan` and `maxpause`), the count is the same. (Learners assume `keepevicted` always adds extra transactions, but it only adds them when eviction actually occurs.)

## Key takeaways

- `maxspan` defines an absolute time limit for the entire transaction from first event to last event.
- `maxpause` defines how long Splunk waits between events before closing a transaction; a new event resets the pause timer.
- `keepevicted=true` outputs evicted events as standalone transactions instead of dropping them entirely.
- Without `maxpause`, Splunk defaults to a 120-second pause timeout between events.
- `maxspan` has no default — if not set, a transaction can theoretically run forever as long as events keep arriving.
- `maxevents` limits transaction size by event count, not time — it is a completely separate option from `maxspan` and `maxpause`.
- All three options (`maxspan`, `maxpause`, `keepevicted`) are exclusive to the `transaction` command — they do not work in `stats` or `eventstats`.
- Eviction happens when a transaction is closed due to a time limit — `keepevicted` controls whether those events appear in results.

## FAQ

**What is the difference between maxspan and maxpause?**

`maxspan` limits the total time from the first event to the last event of a transaction. `maxpause` limits the gap *between* consecutive events. They serve different purposes: `maxspan` stops long-running transactions; `maxpause` stops idle ones.

**Do I always need to set both maxspan and maxpause?**

No. You can set one, both, or neither. If you set neither, Splunk uses a default `maxpause` of 120 seconds and no `maxspan`. But for precision, setting both is best practise.

**What happens to events evicted by maxspan or maxpause?**

By default, they are discarded (not shown in results). If you add `keepevicted=true`, they appear as single-event transactions separate from the main transaction.

**Can I use maxspan and maxpause with any field?**

Yes, as long as the field exists in your events and has matching values across related events. `maxspan` and `maxpause` are independent of the field you choose.

**What is the default maxpause value?**

Splunk's default `maxpause` is 120 seconds. Knowing this number is important for the SPLK-1003 exam.

**Does keepevicted=true change how transactions are grouped?**

No. It only changes the output — evicted events are included as separate transactions. The grouping logic (when to start/stop a transaction) is unchanged.

## Check your understanding

1. **Which transaction option would you use to ensure a transaction automatically closes 10 minutes after the first event, regardless of new events arriving?**

   Answer: `maxspan=10m` — it sets an absolute time limit from the first event to the last event.

2. **What is the default value of `maxpause` if not specified in a `transaction` command?**

   Answer: 120 seconds (2 minutes).

3. **If you set `maxpause=5m` and events arrive at 0:00, 0:04, and 0:10, which events are in the same transaction?**

   Answer: Only the events at 0:00 and 0:04. The gap from 0:04 to 0:10 is 6 minutes, which exceeds `maxpause=5m`, so the transaction closes after 0:04.

4. **What does the `keepevicted=true` option do?**

   Answer: It outputs events that were evicted from a transaction (due to maxspan or maxpause) as single-event transactions instead of discarding them.

5. **Can `maxspan` and `maxpause` be used with the `stats` command?**

   Answer: No, these options are exclusive to the `transaction` command. `stats` uses different syntax (e.g., `bin` or `timechart`).

---

Interactive version with quiz and diagrams: https://courseiva.com/learn/splunk-core-certified-power-user/transactions-advanced-options