Just a second...

Session filtering

Session filters enable you to query the set of connected client sessions on the Diffusion™ server based on their session properties.

To perform an action on a subset of the connected client sessions, you can create a query expression that filters the set of connected client sessions by the values of their session properties. Filter query expressions are parsed and evaluated by the Diffusion server .

The query expression used to filter the session is made up of one or more clauses chained together by boolean operators.

Creating a single search clause

Search clauses have the following form:
keyoperator 'value'
key
The key name of the session property to be tested. The key name is case sensitive. Not required with the HASROLES operator.
operator
The operator that defines the test to be performed. The operator is not case sensitive.
value
The test value to be compared to the session property value. This value is a string and must be contained in single or double quotation marks. Any special characters must be escaped with Java™ escaping. The value is case sensitive.
Table 1. Session filter search clause operators
Operator Description
IS Tests whether the session property value associated with the property key matches the test value.
EQ Equals. Tests whether the session property value associated with the property key matches the test value. Equivalent to 'IS'.
NE Not equal. Tests whether the session property value associated with the key is not equal to the test value.
IN Tests whether the value of a session property belongs to a set, which you provide after the operator.
HASROLES Tests whether a session has any one of a set of security roles, which you provide after the operator.
You can use the special 'all' clause to match all sessions. This does not take a key or a value so it is always simply:
all

The 'all' clause can be useful when creating a session metric collector.

Examples: single search clause

Filter by clients that connect with the principal Ellington:
$Principal IS 'Ellington'
Filter by clients that connect to the Diffusion server using WebSocket :
$Transport EQ 'WEBSOCKET'
Filter by clients that are not located in the United Kingdom:
$Country NE 'GB'
Filter by clients that have the user-defined property Location set to San Jose:
Location IS "San Jose"
Filter by clients that have the user-defined property Status set to Active:
Status EQ 'Active'
Filter by clients that do not have the user-defined property Tier set to Premium:
Tier NE 'Premium'
Filter by clients that are located in one of a set of countries:
$COUNTRY in ['UK', 'DE', 'FR']
Filter by clients that have either of the specified security roles:
hasRoles ["operator", "trading desk"]

Chaining multiple clauses

Chain individual clauses together using boolean operator or use the NOT operator to negate a search clause. Boolean operators are not case sensitive.

Table 2. Session filter boolean operators
Operator Description
AND Specifies that both joined search clauses must be true.
OR Specifies that at least one of the joined search clauses must be true.
NOT Specifies that the following search clause or set of search clauses must not be true.

Use parentheses to group sets of clauses and indicate the order of precedence for evaluation. If no order of precedence is explicitly defined, the AND operator takes precedence over the OR operator.

Examples: multiple search clauses

Filter by clients that connect with one of the principals Fitzgerald, Gillespie, or Hancock:
$Principal IS 'Fitzgerald' OR $Principal IS 'Gillespie' OR $Principal IS 'Hancock'
Filter by clients that connect to the Diffusion server using WebSocket and are located in France and have the user-defined property Status set to Active:
$Transport EQ 'WEBSOCKET' AND $Country IS 'FR' AND Status EQ 'Active'
Filter by clients that are located in the United States, but do not connect with either of the principals Monk or Peterson:
$Country EQ 'US' AND NOT ($Principal IS 'Monk' OR $Principal IS 'Peterson')
Filter by clients excluding those that have both the user-defined property Status set to Inactive and the user-defined property Tier set to Free:
NOT (Status IS 'Inactive' AND Tier IS 'Free')