Splunk® Enterprise Search Reference 7.1.

1
transaction
Generated: 6/29/2018 12:19 pm

Copyright (c) 2018 Splunk Inc. All Rights Reserved

transaction
Description

The transaction command finds transactions based on events that meet various
constraints. Transactions are made up of the raw text (the _raw field) of each
member, the time and date fields of the earliest member, as well as the union of
all other fields of each member.

Additionally, the transaction command adds two fields to the raw events,
duration and eventcount. The values in the duration field show the difference
between the timestamps for the first and last events in the transaction. The
values in the eventcount field show the number of events in the transaction.

See About transactions in the Search Manual.

Syntax

transaction [<field-list>] [name=<transaction-name>] [<txn_definition-options>...]

[<memcontrol-options>...] [<rendering-options>...]

Required arguments

None.

Optional arguments

field-list
Syntax: <field> ...
Description: One field or more field names. The events are grouped into
transactions based on the values of this field. If a quoted list of fields is
specified, events are grouped together if they have the same value for
each of the fields.

memcontrol-options
Syntax: <maxopentxn> | <maxopenevents> | <keepevicted>
Description: These options control the memory usage for your
transactions. They are not required, but you can use 0 or more of the
options to define your transaction.

name
Syntax: name=<transaction-name>

1
 Description: Specify the stanza name of a transaction that is configured
in the transactiontypes.conf file. This runs the search using the settings
defined in this stanza of the configuration file. If you provide other
transaction definition options (such as maxspan) in this search, they
overrule the settings in the configuration file.

rendering-options
Syntax: <delim> | <mvlist> | <mvraw> | <nullstr>
Description: These options control the multivalue rendering for your
transactions. They are not required, but you can use 0 or more of the
options to define your transaction.

txn_definition-options
Syntax: <maxspan> | <maxpause> | <maxevents> | <startswith> |
<endswith> | <connected> | <unifyends> | <keeporphans>
Description: Specify the transaction definition options to define your
transactions. You can use multiple options to define your transaction.

Txn definition options

connected
Syntax: connected=<bool>
Description: Only relevant if a field or fields list is specified. If an event
contains fields required by the transaction, but none of these fields have
been instantiated in the transaction (added with a previous event), this
opens a new transaction (connected=true) or adds the event to the
transaction (connected=false).
Default: true

endswith
Syntax: endswith=<filter-string>
Description: A search or eval expression which, if satisfied by an event,
marks the end of a transaction.

keeporphans
Syntax: keeporphans=true | false
Description: Specify whether the transaction command should output the
results that are not part of any transactions. The results that are passed
through as "orphans" are distinguished from transaction events with a
_txn_orphan field, which has a value of 1 for orphan results.
Default: false

maxspan

2
 Syntax: maxspan=<int>[s | m | h | d]
Description: Specifies the maximum length of time in seconds, minutes,
hours, or days that the events can span. The events in the transaction
must span less than integer specified for maxspan. If the value is
negative, the maxspan constraint is disabled and there is no limit.
Default: -1 (no limit)

maxpause
Syntax: maxpause=<int>[s | m | h | d]
Description: Specifies the maximum length of time in seconds, minutes,
hours, or days for the pause between the events in a transaction. If value
is negative, the maxpause constraint is disabled and there is no limit.
Default: -1 (no limit)

maxevents
Syntax: maxevents=<int>
Description: The maximum number of events in a transaction. If the value
is negative this constraint is disabled.
Default: 1000

startswith
Syntax: startswith=<filter-string>
Description: A search or eval filtering expression which if satisfied by an
event marks the beginning of a new transaction.

unifyends
Syntax: unifyends= true | false
Description: Whether to force events that match startswith/endswith
constraint(s) to also match at least one of the fields used to unify events
into a transaction.
Default: false

Filter string options

<filter-string>
Syntax: <search-expression> | (<quoted-search-expression>) |
eval(<eval-expression>)
Description: A search or eval filtering expression which if satisfied by an
event marks the end of a transaction.

<search-expression>
Description: A valid search expression that does not contain quotes.

3
<quoted-search-expression>
Description: A valid search expression that contains quotes.

<eval-expression>
Description: A valid eval expression that evaluates to a Boolean.

Memory constraint options

If you have Splunk Cloud, Splunk Support administers the settings in the
limits.conf file on your behalf.

keepevicted
Syntax: keepevicted=<bool>
Description: Whether to output evicted transactions. Evicted transactions
can be distinguished from non-evicted transactions by checking the value
of the 'closed_txn' field. The 'closed_txn' field is set to '0', or false, for
evicted transactions and '1', or true for non-evicted, or closed,
transactions. The 'closed_txn' field is set to '1' if one of the following
conditions is met: maxevents, maxpause, maxspan, startswith. For
startswith, because the transaction command sees events in reverse
time order, it closes a transaction when it satisfies the start condition. If
none of these conditions is specified, all transactions are output even
though all transactions will have 'closed_txn' set to '0'. A transaction can
also be evicted when the memory limitations are reached.
Default: false or 0

maxopenevents
Syntax: maxopenevents=<int>
Description: Specifies the maximum number of events (which are) part of
open transactions before transaction eviction starts happening, using LRU
policy.
Default: The default value for this argument is read from the transactions
stanza in the limits.conf file.

maxopentxn
Syntax: maxopentxn=<int>
Description: Specifies the maximum number of not yet closed
transactions to keep in the open pool before starting to evict transactions,
using LRU policy.
Default: The default value for this argument is read from the transactions
stanza in the limits.conf file.

4
Multivalue rendering options

delim
Syntax: delim=<string>
Description: Specify a character to separate multiple values. When used
in conjunction with mvraw=t, represents a string used to delimit the values
of _raw.
Default: " " (whitespace)

mvlist
Syntax: mvlist= true | false | <field-list>
Description: Flag that controls how multivalued fields are processed.
When set to mvlist=true, the multivalued fields in the transaction are a list
of the original events ordered in arrival order. When set to mvlist=false,
the multivalued fields in the transaction are a set of unique field values
ordered alphabetically. If a comma or space delimited list of fields is
provided, only those fields are rendered as lists.
Default: false

mvraw
Syntax: mvraw=<bool>
Description: Used to specify whether the _raw field of the transaction
search result should be a multivalued field.
Default: false

nullstr
Syntax: nullstr=<string>
Description: A string value to use when rendering missing field values as
part of multivalued fields in a transaction. This option applies only to fields
that are rendered as lists.
Default: NULL

Usage

If there are more than 5 events in a transaction, the remaining events are
collapsed. A message appears at the end of the transaction which gives you the
option to show all of the events in the transaction.

Specifying multiple fields

The Splunk software does not necessarily interpret the transaction defined by
multiple fields as a conjunction (field1 AND field2 AND field3) or a disjunction
(field1 OR field2 OR field3) of those fields. If there is a transitive relationship

5
between the fields in the fields list and if the related events appear in the correct
sequence, each with a different timestamp, transaction command will try to use
it. For example, if you searched for

... | transaction host cookie

You might see the following events grouped into a transaction:

event=1 host=a
event=2 host=a cookie=b
event=3 cookie=b

Descending time order required

The transaction command requires that the incoming events be in descending

time order. Some commands, such as eval, might change the order or time
labeling of events. If one of these commands precedes the transaction
command, your search returns an error unless you include a sort command in
your search. The sort command must occur immediately before the transaction
command to reorder the search results in descending time order.

Basic Examples

1. Transactions with the same host, time range, and pause

Group search results that that have the same host and cookie value, occur within
30 seconds, and do not have a pause of more than 5 seconds between the
events.

... | transaction host cookie maxspan=30s maxpause=5s

2. Transactions with the same "from" value, time range, and pause

Group search results that have the same value of "from", with a maximum span
of 30 seconds, and a pause between events no greater than 5 seconds into a
transaction.

... | transaction from maxspan=30s maxpause=5s

3. Transactions with the same field values

You have events that include an alert_level. You want to create transactions
where the level is equal. Using the streamstats command, you can remember

6
the value of the alert level for the current and previous event. Using the
transaction command, you can create a new transaction if the alert level is
different. Output specific fields to table.

... | streamstats window=2 current=t latest(alert_level) AS last

earliest(alert_level) AS first | transaction endswith=eval(first!=last)
| table _time duration first last alert_level eventcount

Extended Examples

1. Transactions of Web access events based on IP address

This example uses the sample data from the Search Tutorial but should work
with any format of Apache web access log. To try this example on your own
Splunk instance, you must download the sample data and follow the instructions
to get the tutorial data into Splunk. Use the time range Yesterday when you
run the search.
Define a transaction based on Web access events that share the same IP
address. The first and last events in the transaction should be no more than thirty
seconds apart and each event should not be longer than five seconds apart.

sourcetype=access_* | transaction clientip maxspan=30s maxpause=5s

This produces the following events list. The clientip for each event in the
transaction is highlighted.

This search groups events together based on the IP addresses accessing the
server and the time constraints. The search results might have multiple values for
some fields, such as host and source. For example, requests from a single IP

7
could come from multiple hosts if multiple people are shopping from the same
office. For more information, read the topic About transactions in the Knowledge
Manager Manual.

2. Transaction of Web access events based on host and client IP

This example uses the sample data from the Search Tutorial but should work
with any format of Apache web access log. To try this example on your own
Splunk instance, you must download the sample data and follow the instructions
to get the tutorial data into Splunk. Use the time range Yesterday when you
run the search.
Define a transaction based on Web access events that have a unique
combination of host and clientip values. The first and last events in the
transaction should be no more than thirty seconds apart and each event should
not be longer than five seconds apart.

sourcetype=access_* | transaction clientip host maxspan=30s maxpause=5s

This search produces the following events list.

Each of these events have a distinct combination of the IP address (clientip)

values and host values within the limits of the time constraints specified in the
search.

3. Purchase transactions based on IP address and time range

This example uses the sample data from the Search Tutorial but should work
with any format of Apache web access log. To try this example on your own
Splunk instance, you must download the sample data and follow the instructions

8
to get the tutorial data into Splunk. Use the time range Yesterday when you
run the search.
This search defines a purchase transaction as 3 events from one IP address
which occur in a 10 minute span of time.

sourcetype=access_* action=purchase | transaction clientip maxspan=10m

maxevents=3

This search defines a purchase event based on Web access events that have
the action=purchase value. These results are then piped into the transaction
command. This search identifies purchase transactions by events that share the
same clientip, where each session lasts no longer than 10 minutes, and
includes no more than 3 events.

This search produces the following events list:

4. Email transactions based on maxevents and endswith

This example uses sample email data. You should be able to run this search on
any email data by replacing the sourcetype=cisco:esa with the sourcetype
value and the mailfrom field with email address field name in your data. For
example, the email might be To, From, or Cc).
This example defines an email transaction as a group of up to 10 events. Each
event contains the same value for the mid (message ID), icid (incoming
connection ID), and dcid (delivery connection ID). The last event in the
transaction contains a Message done string.

sourcetype="cisco:esa" | transaction mid dcid icid maxevents=10

endswith="Message done"

This search produces the following list of events:

9
By default, only the first 5 events in a transaction are shown. The first transaction
contains 7 events and the last event is hidden. The second and third transactions
show the Message done string in the last event in the transaction.

5. Email transactions based on maxevents, maxspan, and mvlist

This example uses sample email data. You should be able to run this search on
any email data by replacing the sourcetype=cisco:esa with the sourcetype
value and the mailfrom field with email address field name in your data. For
example, the email might be To, From, or Cc).
This example defines an email transaction as a group of up to 10 events. Each
event contains the same value for the mid (message ID), icid (incoming
connection ID), and dcid (delivery connection ID). The first and last events in the
transaction should be no more than thirty seconds apart.

sourcetype="cisco:esa" | transaction mid dcid icid maxevents=10

maxspan=30s mvlist=true

By default, the values of multivalue fields are suppressed in search results with
the default setting for mvlist, which is false. Specifying mvlist=true in this
search displays all of the values of the selected fields. This produces the
following events list:

10
Here you can see that each transaction has a duration that is less than thirty
seconds. Also, if there is more than one value for a field, each of the values is
listed.

6. Transactions with the same session ID and IP address

This example uses the sample data from the Search Tutorial but should work
with any format of Apache web access log. To try this example on your own
Splunk instance, you must download the sample data and follow the instructions
to get the tutorial data into Splunk. Use the time range All time when you run
the search.
Define a transaction as a group of events that have the same session ID,
JSESSIONID, and come from the same IP address, clientip, and where the first
event contains the string, "view", and the last event contains the string,
"purchase".

sourcetype=access_* | transaction JSESSIONID clientip startswith="view"

endswith="purchase" | where duration>0

The search defines the first event in the transaction as events that include the
string, "view", using the startswith="view" argument. The endswith="purchase"
argument does the same for the last event in the transaction.

This example then pipes the transactions into the where command and the
duration field to filter out all of the transactions that took less than a second to
complete. The where filter cannot be applied before the transaction command
because the duration field is added by the transaction command.

11
You might be curious about why the transactions took a long time, so viewing
these events might help you to troubleshoot. You won't see it in this data, but
some transactions may take a long time because the user is updating and
removing items from his shopping cart before he completes the purchase.
Additionally, this search is run over all events. There is no filtering before the
transaction command. Anytime you can filter the search before the first pipe,
the faster the search runs.

See also

stats, concurrency

Answers

Have questions? Visit Splunk Answers and see what questions and answers the
Splunk community has using the transaction command.

12