Documentation > Splunk > Search Reference > transaction

Search Reference

 


Introduction
Search Reference Overview
Search Commands and Functions
Search Command Reference
Internal Search Commands
Search in the CLI

transaction

Contents

transaction

Synopsis

Groups events into transactions.

Syntax

transaction [<field-list>] [name=<transaction-name>] [<txn_definition-opt>]* [<memcontrol-opt>]* [<rendering-opt>]*

Required arguments

txn_definition-opt
Syntax: <maxspan> | <maxpause> | <maxevents> | <startswith> | <endswith> | <connected> | <unifyends> | <keeporphans>
Description: Transaction definition options.
memcontrol-opt
Syntax: <maxopentxn> | <maxopenevents> | <keepevicted>
Description: Memory constraint options.
rendering-opt
Syntax: <delim> | <mvlist> | <mvraw> | <nullstr>
Description: Multivalue rendering options.

Optional arguments

field-list
Syntax: <string>, ...
Description: One field or a list of 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.
name
Syntax: name=<transaction-name>
Description: The name of a stanza from transactiontypes.conf to be used for finding transactions. If other arguments (e.g., maxspan) are provided, they overrule the value specified in the transaction definition.

Transaction definition options

connected=<bool>
Description: Relevant if fields is not empty. Controls whether an event that is not inconsistent and not consistent with the fields of a transaction, opens a new transaction (connected=t) or is added to the transaction. An event can be not inconsistent and not consistent if it contains fields required by the transaction but none of these fields has been instantiated in the transaction (by a previous event addition).
endswith=<filter-string>
Description: A search or eval filtering expression which if satisfied by an event marks the end of a transaction.
keeporphans=<bool>
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. Defaults to false|f.
maxspan=<int>(s|m|h|d)?
Description: The maxspan constraint requires the transaction's events to span less than maxspan. If value is negative, disable the maxspan constraint. By default, maxspan=-1 (no limit).
maxpause=<int>(s|m|h|d)?
Description: The maxpause constraint requires there be no pause between a transaction's events of greater than maxpause. If value is negative, disable the maxpause constraint. By default, maxpause=-1 (no limit).
maxevents=<int>
Description: The maximum number of events in a transaction. If the value is negative this constraint is disabled. By default, maxevents=1000.
startswith=<filter-string>
Description: A search or eval filtering expression which if satisfied by an event marks the beginning of a new transaction.
unifyends=<bool>
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. By default, unifyends=f.

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.
<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

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, which is set to '0' for evicted transactions and '1' for closed ones. 'closed_txn' is set to '1' if one of the following conditions is hit: maxevents, maxpause, maxspan, startswith (for this last one, because transaction 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 will be output even though all transactions will have 'closed_txn' set to '0'. A transaction can also be evicted when the memory limitations are reached.
maxopenevents=<int>
Description: Specifies the maximum number of events (which are) part of open transactions before transaction eviction starts happening, using LRU policy. The default value of this field is read from the transactions stanza in limits.conf.
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. The default value of this field is read from the transactions stanza in limits.conf.

Multivalue rendering options

delim=<string>
Description: In conjunction with mvraw=t, a string used to delimit the values of _raw. By default, delim=" ".
mvlist=<bool> | <field-list>
Description: Flag controlling whether the multivalued fields of the transaction are (mvlist=t) a list of the original events ordered in arrival order or (mvlist=f) a set of unique field values ordered lexigraphically. If a comma/space delimited list of fields is provided only those fields are rendered as lists. By default, mvlist=f.
mvraw=<bool>
Description: Used to specify whether the _raw field of the transaction search result should be a multivalued field. By default, mvraw=f.
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. By defaults, nullstr="NULL".

Description

Given events as input, 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.

Splunk 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 between the fields in the fields list, the transaction command will 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

The transaction command produces two fields, duration and eventcount. The duration value is the difference between the timestamps for the first and last events in the transaction. The eventcount value is the number of events in the transaction.

Examples

Example 1

This example uses the sample dataset from the tutorial. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, Other > Yesterday.

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:

TransactionExample2.png


This search groups events together based on the IP addresses accessing the server and the time constraints. The search results may have multiple values for some fields, such as host and source. For example, requests from a single IP could come from multiple hosts if multiple people were shopping from the same office. For more information, read the topic "About transactions" in the Knowledge Manager manual.


Example 2

This example uses the sample dataset from the tutorial. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, Other > Yesterday.

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 produces the following events list:

TransactionExample1.png


In contrast to the transaction in Example 1, each of these events have a distinct combination of the IP address (clientip values) and host values within the limits of the time constraints. Thus, you should not see different values of host or clientip addresses among the events in a single transaction.


Example 3

This example uses the sample dataset from the tutorial. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, Other > Yesterday.

Define a purchase transaction as 3 events from one IP address which occur in a ten 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 three events.

This produces the following events list:

TransactionEx3 eventsList.png


This above results show the same IP address appearing from different host domains.


Example 4

This example uses generated email data (sourcetype=cisco_esa). You should be able to run this example on any email data by replacing the sourcetype=cisco_esa with your data's sourcetype value.

Define an email transaction as a group of up to 10 events each containing the same value for the mid (message ID), icid (incoming connection ID), and dcid (delivery connection ID) and with the last event in the transaction containing a "Message done" string.

sourcetype="cisco_esa" | transaction mid dcid icid maxevents=10 endswith="Message done"

This produces the following events list:

TransactionEx4 eventsList.png


Here, you can see that each transaction has no more than ten events. Also, the last event includes the string, "Message done" in the event line.


Example 5

This example uses generated email data (sourcetype=cisco_esa). You should be able to run this example on any email data by replacing the sourcetype=cisco_esa with your data's sourcetype value.

Define an email transaction as a group of up to 10 events each containing 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 five seconds apart and each transaction should have no more than ten events.

sourcetype="cisco_esa" | transaction mid dcid icid maxevents=10 maxspan=5s mvlist=t

By default, the values of multivalue fields are suppressed in search results (mvlist=f). Specifying mvlist=t in this search tells Splunk to display all the values of the selected fields. This produces the following events list:

TransactionEx5 eventsList.png


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


Example 6

This example uses the sample dataset from the tutorial. Download the data set from this topic in the tutorial and follow the instructions to upload it to Splunk. Then, run this search using the time range, All time.

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, "signon", and the last event contains the string, "purchase".

sourcetype=access_* | transaction JSESSIONID clientip startswith="*signon*" endswith="purchase" | where duration>0

The search defines the first event in the transaction as events that include the string, "signon", using the startswith="*signon*" 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 the transactions that took less than a second to complete:

TransactionEx6.png

You might be curious about why the transactions took a long time, so viewing these events may 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.

More examples

Example 1: 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

Example 2: 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

Answers

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

Retrieved from "http://docs.splunk.com/Documentation/Splunk/5.0.2/SearchReference/Transaction"

This documentation applies to the following versions of Splunk: 5.0 , 5.0.1 , 5.0.2 View the Article History for its revisions.


You must be logged into splunk.com in order to post comments. Log in now.

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!