Using Selection Filters with the Siebel ARM Query Tool

This topic is part of Analyzing Siebel ARM Files Using the Siebel ARM Query Tool. It describes how to use selection filters with the Siebel ARM Query Tool to constrain the data that the tool retrieves.

Siebel ARM files contain one or more segments. Each segment has a header and a body section. The header section contains metadata describing the data contained in the body section. For example, the metadata describes the time range when the data in the body section was collected and the amount of data in the body section.

You can use selection filters to filter the metadata and the actual performance data.

The following table describes the filters that you can use for the metadata in Siebel ARM files
The following table describes the filters that you can use for data in Siebel ARM files

Note the following points when you formulate queries:

String filter searches are case insensitive and accept wild cards. For example, the following query retrieves Siebel ARM records associated with the users johndoe, JOHNDOE, and JoHnDoE:
```
> sarmquery –select user=JohnDoe 
```
String filters also accept leading and trailing wild cards. For example, each of the following queries retrieves records associated with the same users, and possibly others:
```
> sarmquery –select user="*doe" 
> sarmquery –select user="john*" 
> sarmquery –select user="*hndo*" 
```
Note: Wild cards can only be leading or trailing. Wild cards in the middle of a pattern do not retrieve results. For example, the pattern jo*ndoe does not retrieve johndoe.
You can combine selection filters to retrieve records that match multiple conditions. For example, the following selection filter retrieves all script execution records that executed for at least 5 seconds:
```
> sarmquery –select area=script –select resp=5000 
```

All of the options listed in the following table must be preceded by the option -select.

Flag	Description
component=componentname	Selects headers from Siebel ARM files that were generated by the named component.
fillfactor=percent Or: fillfactor=minpct,maxpct	Use this flag to specify a percentage value; the Siebel ARM Query Tool retrieves headers that are percent full. Alternatively, you can specify two arguments, a minimum percentage minpct and a maximum percentage maxpct to retrieve a range of values. Generally, headers have a capacity to hold a certain number of Siebel ARM records. The percentage value is the ratio of actual number of records to that capacity.
host=hostname	Selects headers from Siebel ARM files generated on the named host.
procid=integer	Selects headers from Siebel ARM files generated by a process whose ID (process ID) is inter.
segcapacity=nrecs Or: segcapacity=min,max	Selects headers whose capacity to hold Siebel ARM records matches the number of records specified by nrecs. Alternatively, you can specify two arguments, a minimum number of records and a maximum number of records, to retrieve a range of values.
segduration=nsecs Or: segduration=min,max	Selects headers whose duration matches the number of seconds specified. A header duration is the number of seconds the file segment was in memory before it was flushed. Alternatively, you can specify two arguments, min and max, to retrieve a range of values.
segid=min Or: segid=min,max	Specify a single argument to retrieve the headers with an internal segment ID of at least min. Alternatively, you can specify two arguments, min and max, to retrieve a range of values.
segsize=size Or: segsize=min,max	A segment size is the size of the header and body in bytes. Specify a single argument of size to retrieve all headers whose segment size is size bytes. Alternatively, you can specify two arguments, min and max, to retrieve a range of values.
server=servername	Retrieve headers from Siebel ARM files generated on the specified Siebel Server servername.
sourcetype=value	Retrieves headers from Siebel ARM files generated by the specified type of server or process. Specify one of the following parameters in place of value to retrieve the headers: `app` Retrieves headers generated by Siebel Servers. `cli` Retrieves headers generated by other client programs such as the Siebel Mobile Web Client.
threshold=min Or: threshold=min,max	A threshold is a value represented in milliseconds. In the Siebel ARM framework, any performance record whose total response time duration is less that the threshold amount is discarded. The threshold setting at the time the Siebel ARM file was generated is saved in the header. Specify a single argument to retrieve all headers that contain Siebel ARM records whose threshold was least min milliseconds. Alternatively, you can specify two arguments, min and max, to retrieve a range of values.
starttime=start	Specify a start time to retrieve headers that contain Siebel ARM records that ended after the specified start time. Note: Time filters are compared against the generation start time for Siebel ARM records. You can specify the start time in the following ways: String in the format YYYY-MM-DD hh:mm:ss. For example: > sarmquery -select starttime="2014-02-13 17:05:00" A number interpreted in Universal Time Coordinated (UTC). For example: sarmquery -select starttime=1108083900 A negative number to indicate the number of seconds from the current time. For example, this command retrieves headers that contain data generated less than 300 seconds ago: > sarmquery -select starttime=-300
endtime=end	Specify an end time to retrieve headers that contain Siebel ARM records that were generated before the specified time end. Note: Time filters are compared against the generation end time for Siebel ARM records. You can specify the end time in the following ways: String in the format YYYY-MM-DD hh:mm:ss. For example: > sarmquery -select endtime="2014-02-13 17:05:00" A number interpreted in Universal Time Coordinated (UTC). For example: > sarmquery -select endtime=1108083900 A negative number to indicate the number of seconds from the current time. For example, this command retrieves headers that contain data generated less than 300 seconds ago: > sarmquery -select endtime=-300 A positive number to indicate the number of seconds after the start time. For example, this command retrieves headers that contain data generated more than 600 seconds after the start time: > sarmquery -select starttime=+600

Flag

Description

component=componentname

Selects headers from Siebel ARM files that were generated by the named component.

fillfactor=percent

Or:

fillfactor=minpct,maxpct

Use this flag to specify a percentage value; the Siebel ARM Query Tool retrieves headers that are percent full.

Alternatively, you can specify two arguments, a minimum percentage minpct and a maximum percentage maxpct to retrieve a range of values.

Generally, headers have a capacity to hold a certain number of Siebel ARM records. The percentage value is the ratio of actual number of records to that capacity.

host=hostname

Selects headers from Siebel ARM files generated on the named host.

procid=integer

Selects headers from Siebel ARM files generated by a process whose ID (process ID) is inter.

segcapacity=nrecs

Or:

segcapacity=min,max

Selects headers whose capacity to hold Siebel ARM records matches the number of records specified by nrecs.

Alternatively, you can specify two arguments, a minimum number of records and a maximum number of records, to retrieve a range of values.

segduration=nsecs

Or:

segduration=min,max

Selects headers whose duration matches the number of seconds specified. A header duration is the number of seconds the file segment was in memory before it was flushed.

Alternatively, you can specify two arguments, min and max, to retrieve a range of values.

segid=min

Or:

segid=min,max

Specify a single argument to retrieve the headers with an internal segment ID of at least min.

Alternatively, you can specify two arguments, min and max, to retrieve a range of values.

segsize=size

Or:

segsize=min,max

A segment size is the size of the header and body in bytes. Specify a single argument of size to retrieve all headers whose segment size is size bytes.

Alternatively, you can specify two arguments, min and max, to retrieve a range of values.

server=servername

Retrieve headers from Siebel ARM files generated on the specified Siebel Server servername.

sourcetype=value

Retrieves headers from Siebel ARM files generated by the specified type of server or process. Specify one of the following parameters in place of value to retrieve the headers:

app

Retrieves headers generated by Siebel Servers.

cli

Retrieves headers generated by other client programs such as the Siebel Mobile Web Client.

threshold=min

Or:

threshold=min,max

A threshold is a value represented in milliseconds. In the Siebel ARM framework, any performance record whose total response time duration is less that the threshold amount is discarded. The threshold setting at the time the Siebel ARM file was generated is saved in the header.

Specify a single argument to retrieve all headers that contain Siebel ARM records whose threshold was least min milliseconds.

Alternatively, you can specify two arguments, min and max, to retrieve a range of values.

starttime=start

Specify a start time to retrieve headers that contain Siebel ARM records that ended after the specified start time.

Note: Time filters are compared against the generation start time for Siebel ARM records.

You can specify the start time in the following ways:

String in the format YYYY-MM-DD hh:mm:ss. For example:

> sarmquery -select starttime="2014-02-13 17:05:00"

A number interpreted in Universal Time Coordinated (UTC). For example:

sarmquery -select starttime=1108083900

A negative number to indicate the number of seconds from the current time. For example, this command retrieves headers that contain data generated less than 300 seconds ago:

> sarmquery -select starttime=-300

endtime=end

Specify an end time to retrieve headers that contain Siebel ARM records that were generated before the specified time end.

Note: Time filters are compared against the generation end time for Siebel ARM records.

You can specify the end time in the following ways:

String in the format YYYY-MM-DD hh:mm:ss. For example:

> sarmquery -select endtime="2014-02-13 17:05:00"

A number interpreted in Universal Time Coordinated (UTC). For example:

> sarmquery -select endtime=1108083900

A negative number to indicate the number of seconds from the current time. For example, this command retrieves headers that contain data generated less than 300 seconds ago:

> sarmquery -select endtime=-300

A positive number to indicate the number of seconds after the start time. For example, this command retrieves headers that contain data generated more than 600 seconds after the start time:

> sarmquery -select starttime=+600

The following table describes the filter options that you can use when you formulate a query to retrieve Siebel ARM data. All of the options must be preceded by the option -select.

Flag	Description
foreign	Use this flag to retrieve records whose parent records are from a different process. This is frequently the case for Siebel ARM data generated from batch mode components.
orphan	Select records that are not root records and whose parent record was not found in the input Siebel ARM file(s).
level=level Or: level=min,max	Specify one argument to retrieve records whose Application Program Interface (API) level is at least equal to level. Alternatively, specify two arguments to retrieve a range of values between the minimum and maximum level specified. The API level indicates the importance of a Siebel ARM record as follows: level = 1 Equivalent to `SARMLevel=1` and indicates high level information. level = 2 Equivalent to `SARMLevel=2` and indicates detailed performance information. level = 3 Equivalent to `SARMLevel=3` and indicates debug or internal performance information.
parentid=ID	Selects Siebel ARM records whose parent ID is ID.
rootid=ID	Selects Siebel ARM records whose root ID (also known as request ID in interactive mode components) is ID.
sarmid=sarmid Or: sarmid=procid.sarmid Or: sarmid=segid.procid.sarmid	Retrieves Siebel ARM records primary ID where: sarmid is a number uniquely identifying this performance record within a process or component, procid is the process ID (same as `-select procid=`procid), and segid is the segment ID (same as `-select segid=`segid`,`segid)
sessionid=sessid	All session based component performance data contain an attribute known as the session ID. All performance data from all processes that have the same session ID are assumed to belong to a single session of a single user. The Siebel ARM Query Tool does a case-insensitive search using sessid. Wild cards are acceptable.
taskid=taskid	Selects all records that associated with task taskid.
threadid=threadid	Selects all records that were created by the thread whose operating system thread ID is threadid.
user=username	Selects all records that were created by user named username, which is typically the login name. The search is case-insensitive and wild cards are acceptable.
area=area area=areacode subarea=sub subarea=subcode pararea=parea pararea=pareacode parsubarea=psarea parsubarea=pscode	Two filters, `area` and `subarea`, identify each Siebel ARM record. The area and subarea are logical sections of the Siebel Server. For example, the Siebel Web Engine (SWE) area creates Web pages. Siebel ARM records associated with the SWE describe Web page creation performance. Similarly, the database connector (DBC) area represents the connection to the enterprise database. Siebel ARM records associated with DBC indicate the performance of database queries. For example, the following command retrieves all Siebel ARM records associated with database queries: > sarmquery –select area=DBC You can retrieve a complete list of areas, subareas, and descriptions from the Siebel ARM Query Tool. For example, the following command saves the complete list to the file map.csv: > sarmquery –output map=map.csv If you know the numeric area or subarea codes, then you can use them directly in this command. Otherwise, you can use the string form of the symbol. When using the string form, you do not need to use the entire text string. You can use a partial text string, provided that it uniquely identifies the area or subarea. The filters `pararea` and `parsubarea` are similar to area and subarea except that they select Siebel ARM records whose parent area and subarea (respectively) are parea and psarea. For example, the following command retrieves all Siebel ARM records whose parent area is SWE: > sarmquery –select pararea=swe
children=0	Use this flag to retrieve Siebel ARM records that have no child records.
children=count Or: children=min,max	Specify one argument to retrieve Siebel ARM records that have child records equal to at least count. Specify two arguments to retrieve the records that have child records between min and max.
cputime=ms Or: cputime=min,max	Specify one argument to retrieve Siebel ARM records that spent at least ms milliseconds on the CPU. Specify two arguments to retrieve the Siebel ARM records that spent between min and max milliseconds on the CPU.
depth=depth Or: depth=min,max	Specify one integer argument to retrieve Siebel ARM records that are no more than depth from the root node. Specify two arguments to retrieve a range of records.
descendants=count Or: descendants=min,max	Specify one integer argument to retrieve Siebel ARM records that have at least count descendants. Specify two arguments to retrieve a range of values.
instance=string detail=string int1=int	Use these filters to retrieve Siebel ARM records where the filter is as follows: `instance` Retrieves Siebel ARM records where instance metadata equals string. Instance metadata typically contains the names of things, such as the view names, screen names, user name, workflow name and script name. `detail` Retrieves Siebel ARM records where the detail metadata equals string. Detail metadata typically contains identification information. For example, it might contain a database row ID or the name of a business component method. `int1` Retrieves Siebel ARM records where int1 filter equals int. The `int1` metadata typically contains counter values, task IDs or other unspecified information. Note: The values that the preceding metadata fields reference depend on the associated area or subarea.
memusage=excl Or: memusage=min,max	Specify one argument to retrieve all Siebel ARM records where memory allocated or deallocated was larger than excl bytes. Specify two arguments to retrieve a range of Siebel ARM records that record the memory allocation or deallocation events within the specified range. For example, the following command retrieves all Siebel ARM records where the associated event recorded a memory allocation of 1 MB (or larger) or a deallocation of 1 MB or larger > sarmquery –select memusage=1000000
pctcpu=percent Or: pctcpu=min,max	Specify a single argument to retrieve Siebel ARM records that indicate a CPU consumption of the percentage percent. Specify two arguments to retrieve a range between min and max percent.
resptime=ms Or: resptime=min,max	Specify one argument to retrieve Siebel ARM records where the inclusive wall clock time consumed is ms milliseconds. Specify two arguments to retrieve a range between min and max. An inclusive wall clock time is the time spent in a specific part of the architecture and includes the time spent in all of its descendants. For example, the response time of a SWE area would be the time spent in constructing a Web page, including the time to evaluate business component events and database access.
selftime=ms Or: selftime=min,max	With one argument, select Siebel ARM records where the exclusive time consumed is ms milliseconds. With two arguments, min and max specify a range. An exclusive time is time spent in an area, and only in that area, excluding the time spent in its descendants. Hence, the self time of a SCRIPT area would be the time spent in the scripting engine, and not including time spent in the database, object manager, workflow, and so on.
starttime=start Or: endtime=end	The semantics and syntax are similar to the time filters described for headers, except that the filters select Siebel ARM records based on the time stamps.
tree=all parent=parent tree=ancestor tree=children tree=descendent	These are a specialized set of selection filters that do not just operate on a single record basis but on record sets. In most cases, they serve to replace a performance record with an entire set. In order to understand these operators, it is important to realize that Siebel ARM records form a tree of an execution thread with parent and children nodes: `tree=all` Replaces a selected record by all records in its tree. `tree=parent` Replaces a selected record by its parent. The selected record is not included. `tree=ancestor` Replaces a selected record by all Siebel ARM records leading from the selected record to the root of the tree. The selected record is also included in the set. `tree=children` Replaces a selected record by its immediate children. The selected record is not included. `tree=descendent` Replaces a selected record by all of its descendents. The selected record is also included in the set.