REST filters

When you open a dashboard or a report, the AppMon Server and the Client provide a set of filters that let you specify which data to show. The following table describes the filter types.

Filter Pattern Example
Timeframe tf: type [? { from:to | offset:unit } ] tf:Last15Min tf:OffsetTimeframe?15:SECONDS
Business Transaction bt: name [? groupKey=groupValue [@]] old syntax: bt: name [? group ] bt:Transaction?user=demouser@equals bt:Transactions grouped by user?demouser
Webrequest wr: [uri ] [? query ] wr:/frontend/menu.do?action=home
Tagged Webrequest tw: <tagid> ? tagvalue[@<MatchType>] tw:PC?name@starts tw:AN?agent1
Application ap:applicationname ap:fooapp
Incident if:type [? condition] if:SEVERITY?severe if:STATE?InProgress
Agent ag:mode ? condition ag:AgentGroups?Production ag:AgentsByPattern?AppSrv@contains:mainmachine@ends ag:AgentsById?348938458 ag:Agents?AppSrv@mainmachine ag:IncludeCorrelatingAgents?false
DC RUM dc:type ? pattern[@<MatchType>] dc:cliname?testuser dc:eventtype?X@matches
Visit vi:id ? visitid[:visitid2:visitid3] vi:id?1:2:3
Host hf:type ? condition hf:Host?mainmachine hf:GroupOrLabel?hostgroup1

Timeframe filter

Filtering supports the predefined filtering timeframes as well as custom timeframes that define exact points in time for reports. The number of required parameters depends on the chosen filter.

Simple timeframe

AppMon supports a list of simple strings representing the most commonly used timeframes, as shown in the following table.

Filter Description
tf:Last72h last 72 hours
tf:Last7d last 7 days
tf:Last30d last 30 days
tf:Last90d last 90 days
tf:Last180d last 180 days
tf:Last365d last 365 days
tf:Today today
Filter Description
tf:Yesterday yesterday
tf:ThisWeek this week
tf:ThisMonth this month
tf:ThisYear this year
tf:LastWeek last week
tf:LastMonth last month
tf:LastYear last year

Custom timeframe

Custom timeframes are defined by the FROM and TO parameters. The parameter values are the number of milliseconds since the standard base time (January 1, 1970, 00:00:00 GMT), also known as the epoch. See Java date function and the online conversion tool from epoch to ms.

Filter Example
tf:CustomTimeframe?<FROM>:<TO> tf:CustomTimeframe?1426339613000:1426339620000

Offset timeframe

Offset timeframes are defined by the time offset and the unit of the time offset. Offset time is the period from a point in the past to the current time. For example, if the filter is tf:OffsetTimeframe?10:MINUTES, only the data of the last 10 minutes is considered by the filter.

Filter Example
tf:OffsetTimeframe?<OFFSET_TIME>:<UNIT> tf:OffsetTimeframe?15:SECONDS tf:OffsetTimeframe?7:MINUTES tf:OffsetTimeframe?3:DAYS

<UNIT> can have the following values:

  • MILLISECONDS
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS

Note

All strings must match exactly.

Business Transaction filter

The following syntax allows you to filter by Business Transactions and their groupings. The Business Transaction name is mandatory whereas the other fields are optional. If a groupKey and groupValue are specified optionally, a MatchType can be specified to control the matching behavior. The groupKey is the name of the grouping measure used to split the business transaction results.

bt: name [? groupKey=groupValue [@<MatchType>]]

MatchType can be one of the following:

Match Description
starts Matches every string that starts with the specified value.
ends Matches every string that ends with the specified value.
contains Matches every string that contains the specified value.
equals Matches only strings that equal the specified value.
matches allows to specify wildcard *
regex Allows for a regex match.

Old Syntax (still supported, but deprecated):

bt:name[?group]

Note

While it is possible to specify multiple filters using the old syntax, all filters have to match. If the result includes multiple grouping values, the new syntax must be used.

Webrequest filter

This filter allows you to specify the URI of a request using the following pattern:

wr:uri[?query]

For example:

wr:/frontend/booking.php?cmd=execute)

Tagged webrequest filter

The format for this filtering is:

tw:<tagid>?<tagvalue>[@<MatchType>]

The MatchType can be starts, ends, contains, or matches. If the MatchType is not specified, it is the default value contains.

Webrequest Filter Tag IDs

Key Description
ID Represents the unique request ID (serial number). This string should be unique for one web request or a set of web requests that together make up a step/transaction execution. The syntax is: ID=<Id>
PC The Page Context contains information about which document in the currently processed page is loaded. If it is a named frame, then the value starts with the frame name. A period follows the frame name and the page-unique document number is appended. If embedded documents are cached, this number must not be progressive. The following syntax is recommended, though not required: PC=<FrameName>.<DocId>
VU This indicates the unique number of the Virtual User who sends the request. The syntax is: VU=<Id>
NA This represents the timer Name of the request. It can be the timer or transaction name in the load test script that is used to identify the response-time measure, the document/page title, or any other human-readable URL encoded identifier for that document. The syntax is: NA=<timername>
SI The Source ID can be used to identify the product that triggered the request.
GR The Geographic Region is used only for the Enterprise Synthetic Monitoring solution. It contains arbitrary text.
AN The Agent Name is the logical name of the Agent from which the request originated. This is used by Enterprise Synthetic Monitoring.
SN The Script Name groups a set of requests that make up a multi-step transaction, for example making a purchase in a shopping website.
TE The Test Name is the name of the entire load test. It uniquely identifies a test run.

Webrequest Filter Examples

Example Description
filter=tw:PC?Page1@starts Matches requests where the Page Context value starts with the string Page1.
filter=tw:SN?LoadScript Matches requests where the Script Name contains LoadScript.

Multiple different tag-patterns can be combined by specifying multiple tw filters. Only requests that match all filters (Boolean AND condition) are selected. However, only the last condition is used if the same tag-id is used multiple times.

Application filter

This filter allows you to specify the applications to filter by. For example, ap:app1 shows only data for the application app1. You can include more than one application in the filter by using the following syntax:

filter=ap:app1&filter=ap:app2&filter=ap:app3&filter=ap:appX

This example displays data from the applications app1, app2, app3, and appX,

The filter does not check whether the specified application exists.

Incident filter

Multiple filter conditions can be combined. For example, you can apply filters for both SEVERITY and STATE, and you can apply multiple filters for SEVERITY to display data for any of the specified severity levels.

Incident Filter Types

Filter Description Values Example
RULE Specify the name of the Incident rule. You can specify multiple rules as separate filter elements in the URL. Encode special characters as HTTP URI Query Parameters. For example, use the plus sign ( + ) to specify blank spaces. if:RULE?Server+Offline
SEVERITY Filter by Incident severity. informational warning severe if:SEVERITY?severe
STATE Filter by Incident state. Created InProgress Confirmed if:STATE?Created

To combine filters, separate the filters with an ampersand (&), without spaces between the filters.

Example: Combined Filters This example filter displays data with a severity of either severe or warning, and a state of InProgress.

filter=if:SEVERITY?severe&filter=if:SEVERITY?warning&filter=if:STATE?InProgress

Note

All strings must match exactly.

Agent filter

Different types of Agent filters are available, but only one Agent filter type can be used in a request. If multiple filter-strings with different types are specified in one request, only the last type applies. You can filter on multiple values for the filter types Agent Group, Agent Name/Host, and Agent ID. You can include only one filter of the type Agent Pattern.

Agent Group

Specify the Agent Group(s) to filter on.

The following example displays data for both specified Agent Groups:

filter=ag:AgentGroups?Production&filter=ag:AgentGroups?Test

Agent name/host

The format for this filter type is <AgentName>@<AgentHost>. You must specify both the name and the host.

It filters AppMon Agents by their name and location. The following example displays data from Agent1 (installed on host1) and Agent2 (installed on host2):

filter=ag:Agents?agent1@host1&filter=ag:Agents?agent2@host2

Agent pattern

The format for this filter type is <AgentNamePattern>[:<AgentHostPattern>], where both elements are of form <pattern>[@<MatchType>]. The MatchType can be starts, ends, contains, or matches. If MatchType is not specified, the default value contains is used.

Examples

  • filter=ag:AgentsByPattern?SR_Agent@starts matches any Agent that has a name starting with SR_Agent.
  • filter=ag:AgentsByPattern?SR_Agent@contains:xfs01@matches matches any Agent that has a name containing SR_Agent and runs on the machine xfs01.

Only one pattern filter can be specified. If multiple patterns are specified, only the last pattern is used to filter the data.

Agent ID

This filter type specifies AppMon Agents by their ID. The ID is assigned whenever the AppMon Agent connects to the AppMon Collector. You can find the ID in the Agent Overview dashlet or in the Agent log files.

Specify the Agent IDs to filter on. Both decimal and hexadecimal values can be specified, hexadecimal values must be prefixed with 0x. You can select multiple Agents by including multiple filter-elements.

Example: Agent ID Filters

Example Description
filter=ag:AgentsById?826587 Filter on one Agent.
filter=ag:AgentsById?826587&filter=ag:AgentsById?0xabcdef123 Filter on two Agents.

Note

All strings are case-sensitive.

Include correlating agents

This can be set in addition to any of the preceding AppMon Agent filters. If no Agent filter is set except this one, it acts as if no Agent filter is set, but still overrides the dashboard's Agent filters. It specifies whether to include AppMon Agents of applications which communicate directly or indirectly with applications of selected AppMon Agents.

The syntax for this filter is IncludeCorrelatingAgents?state, where state has to be one of either true or false. The default behavior, if this filter is not specified, is to include correlating Agents.

Example: Usage of the IncludeCorrelatingAgents Filter

Example Description
filter=ag:AgentsById?826587&filter=ag:IncludeCorrelatingAgents?false Filter by one Agent and do not include correlating Agents.
filter=ag:AgentsById?826587&filter=ag:IncludeCorrelatingAgents?true Filter by one Agent and include correlating Agents (default behavior).

DC RUM filter

Other than interval, all Data Center Real User Monitoring (DC RUM) filter items are text patterns in the format dc:<type>?<pattern>[@<Matchtype>]. The MatchType can be any one of starts, ends, contains, or matches. If MatchType is not specified, the default value contains is used.

To filter for a value that was not set, leave the pattern empty. For example, dc:userdefparam1?@matches filters for all PurePaths that do not have any userdefparam1 data.

You can filter the interval by using the format dc:interval?<INTERVAL_START>:<INTERVAL_END>. The <INTERVAL_START> is exclusive and the <INTERVAL_END> is inclusive, so only PurePaths with an interval that is greater than the <INTERVAL_START> and less than or equal to the <INTERVAL_END> match. For example, if your filter is dc:interval?1:3, the PurePaths with an interval of 2 or 3 match, but the paths with other intervals (including 1) do not.

Note

To filter according to the interval filter, you have to adapt the timeframe filter. By default, only the PurePaths of the last 30 minutes are shown. PurePaths that match the interval filter may not be shown because they are older than 30 minutes. Consider using a CustomTimeframe. See Timeframe Filter for more information.

DC RUM Filter Types

Filter Example
interval dc:interval?1332885600000:1332921300000
srvip dc:srvip?192.168.1.2@matches
cliip dc:cliip?10::10.1.2.3
incliip dc:incliip?244.17@starts
cliname dc:cliname?herbert@contains
softwareservice dc:softwareservice?easyTravel@matches
apptype dc:apptype?2@matches
operation dc:operation@wildcard See below for further details on the wildcard filter.
eventtype dc:eventType?P@matches
status dc:status?o@matches
slowtype dc:slowtype?S@matches

You can set multiple patterns, with either the same or different types. All patterns must match (Boolean AND matching).

Combined Filter Example

filter=dc:interval?1332885600000:1332921300000&filter=dc:eventType?P@matches&filter=dc:operation?*myhost.com*login.do*@wildcard&filter=dc:softwareservice?KONAKART-HTTPS@matches&filter=dc:apptype?2@matches&filter=dc:serverip?192.168.2.103@matches

Note

All string matching is case-sensitive. The filter names such as eventtype, interval, and method are case-insensitive.

Visit filter

To filter the requested data by one or more specific visits, you must provide the visit IDs. Any number of visits can be requested, separated by a colon (:).

Example Description
filter=vi:id?43 Filter on one visit with the id 43.
filter=vi:id?33:12:85 Filter on three visits with the ids 33, 12, and 85.

Host filter

There are two types of host filters available. However, only one filter type can be used per request. If filters of different types are used in a single request, only the last filter type used applies. You can define multiple filter values for the available types Host and GroupOrLabel.

Host

With the host filter of type host, you can filter by specific hosts. The format of this filter is hf:Host?<hostname>.

The following example displays data of host1 and host2.

filter=hf:Host?host1&filter=hf:Host?host2

Host group or label

This type allows to filter by host groups and labels. Use it to filter for any combination of host groups and labels. The format of this filter is hf:GroupOrLabel?<hostgrouporlabel>.

The following example displays data hosts that belong to host group group1, or have the label label1 set.

filter=hf:GroupOrLabel?group1&filter=hf:GroupOrLabel?label1

CAS UEM filter

All filter items for CAS UEM dimensions must have the format ca:<type>?<pattern>[@<Matchtype>]. The MatchType can be startsendscontains, or matches. If no Matchtype is specified, the default value contains is used.

Note

You must encode the given CAS UEM filter value even if it is already encoded. For example, if the value of a CAS UEM dimension received by AppMon Server is click%20on%20"Search", you need to provide click%2520on%2520%22Search%22 as the filter value to match the dimensions with this value.

CAS UEM Filter Types

Filter Example
app ca:app?easyTravelApp@matches
ostype ca:ostype?Windows@matches
osversion ca:osversion?Windows+Vista@matches
cliip
cliname ca:cliname?herbert@contains
clitype ca:clitype?M@matches
uaname ca:uaname?click@contains
pagetitle ca:pagetitle?Startpage@starts
browser ca:browser?firefox@contains
browserver ca:browserver?23.1@matches
srcurl ca:srcurl?source.com@contains
dsturl ca:dsturl?www.destination.de@contains
devicename ca:devicename?iPhone@contains
devicemanufacturer ca:devicemanufacturer?Apple@matches

Wildcard filter for CAS UEM dimensions and DC-RUM dimension operation

You can use wildcards for all CAS UEM dimensions and for the DC-RUM dimension operation. The pattern is:

filter=dc:operation?<QUERY_STRING>@wildcard

Where <QUERY_STRING> is the filter string. It can include following wildcards.

Valid Filter Wildcards

Note

  • The <QUERY_STRING> of the DC RUM operation dimension must be UTF-8 encoded.
  • If you need to use one of the special characters (~() ?) as a string character, escape the character by preceding it with a backslash (\).

Complex filters for DC-RUM and CAS UEM dimensions

Besides filtering possibilities for DC RUM and CAS UEM dimensions, you can also apply more complex filters. For example, you may want to filter all PurePaths that have DC RUM dimensions with either event type P or X. The approach using the filter dc:eventType?P@matches&amp;dc:eventType?X@matches would not work, because the event type filter matching X overrides the event type filter that matches P. In this situation, use the complex filter as in the following example:

filter=co:or@starts&filter=co:and@starts&filter=dc:eventType?P@matches&filter=co:and@ends&filter=co:and@starts&filter=dc:eventType?X@matches&filter=co:and@ends&filter=co:or@ends

Complex Filter Elements

Filter Description
co:or@starts Starts a new OR filtering group. You can include an arbitrary number of AND filtering groups to the OR group. At least one of the enclosed and filtering groups must match so the path of the dimension displays.
co:or@ends Ends the OR filtering group. Each co:or@starts must be ended by a corresponding co:or@ends.
co:and@starts Starts a new AND filtering group. You can include an arbitrary number of DC RUM filters in an AND filtering group. The syntax for defining the DC RUM filters is the same as using the filters without an AND filter. For example, filter=co:and@starts&amp;filter=dc:eventType?P@matches&amp;filter=dc:cliname?user@starts&amp;filter=co:and@ends.
co:and@ends Ends the AND filtering group. Each co:and@starts must be ended by a corresponding co:and@ends.

In the example, both dc:eventType?P@matches and dc:eventType?X@matches are added to its own AND filtering group. Because only one of the AND filtering groups enclosed by the OR filtering group must match, dimensions with either event type P or event type X match.

You can also combine a simple DC RUM filter with a complex filter, as in the following example:

filter=dc:cliname?user@starts&filter=co:or@starts&filter=co:and@starts&filter=dc:eventType?X@matches&filter=co:and@ends&filter=co:and@starts&filter=dc:eventType?P@matches&filter=co:and@ends&filter=co:or@ends

The example means that a matching dimension must have a client name starting with user and have either event type P or event type X. For example, the following expression:

filter=co:or@starts
    &filter=co:and@starts
        &filter=dc:eventtype?P@matches
        &filter=dc:apptype?5@matches
    &filter=co:and@ends
    &filter=co:and@starts
        &filter=dc:eventtype?X@matches
        &filter=dc:apptype?6@matches
        &filter=co:or@starts
            &filter=co:and@starts
                &filter=dc:cliname?peter@matches
            &filter=co:and@ends
            &filter=co:and@starts
                &filter=dc:cliname?samuel@matches
            &filter=co:and@ends
        &filter=co:or@ends
    &filter=co:and@ends
&filter=co:or@ends

is equal to:

(eventtype = P & apptype = 5) | ( eventtype = X & apptype = 6 & ( cliname = peter | cliname = samuel ))

Note

You cannot add DC RUM conditions to the OR filtering group without wrapping them in an AND filtering group. Even if you distinguish between only two properties (for example, the client names peter and samuel), you must use the AND condition to wrap them:

filter=co:or@starts&filter=co:and@starts&filter=dc:cliname?peter@matches&filter=co:and@ends
&filter=co:and@starts&filter=dc:cliname?samuel@matches&filter=co:and@ends&filter=co:or@ends

Note

All string matching is case-sensitive.