SIP Monitor and Trace Filter Configuration Objects

The Oracle® Enterprise Session Border Controller (ESBC) provides configuration objects you can set on the ESBC to customize filters for SIP Monitor and Trace. The system can monitor and filter specific SIP session data and display it to the GUI. The filter objects you can configure include:

Filters	Description
filter-config	Use to create custom filters for SIP Monitor and Trace. You can configure session agents (SA) and realms to use such filters, or set sip-monitoring to use the filters on a global basis. For more information, see Creating Custom Filters .
sip-monitoring	Use to configure SIP Monitor and Trace features. Note: You must configure the sip-monitoring object to enable filtering. You must also configure a session agent or realm, or you must set filtering on a global basis for Monitor and Trace to occur.
match-any-filter	Enable to have the system perform cumulative filter matching.
state	Use to enable and disable SIP Monitor and Trace. For more information, see Enabling Disabling SIP Monitoring & Tracing .
short-session-duration	Use to specify the maximum session duration (in seconds) to be considered a short session.
monitoring-filters	Use to specify the name of the custom filter to use on a global basis. This value is based on the filter created in “filter-config.” You can also specify an asterisk (*) as a value for this attribute, which monitors all session data on the ESBC. For more information, see Using Filters to Monitor on a Global-Basis .
ladder-diagram-rows	Specify the maximum number of rows to display in a SIP-session ladder diagram, with a range of 15 to 500. This size helps determine the maximum number of records that the system can monitor and display with SMT on the WebGUI. If you decrease the number of messages per record, you also decrease SMT's memory utilization. When you save and activate the sip-monitoring element, the system clears and re-sizes the applicable buffers.
interesting-events	Use to configure the following attributes: type - Sets the interesting events to monitor (short-session, local-rejection) trigger-threshold - Sets the number of interesting events that must occur within the time set by the trigger-window value. If the number of events reaches the trigger-threshold during the trigger-window time, monitoring is started. trigger-timeout - Sets the amount of time, in seconds, that the trigger is active monitoring starts. If no interesting events occur in the time frame set for this value, monitoring never starts. For example, if trigger-timeout is set to 40, and no interesting events occur in 40 seconds, then monitoring never starts. Note: Interesting Events are always enabled on a global-basis on the ESBC. For more information, see Configuring Interesting Events .
trigger-window	Use to specify the amount of time, in seconds, for the window of time that the trigger-threshold value must reach before monitoring begins. For example, if type is set to short-session, trigger-threshold is set to 2, and trigger-window is set to 60, monitoring begins when the ESBC discovers 2 short-session events in a 60 second window. For more information, see Configuring a Trigger Window .

Create Custom Filters

You can create single or multiple, custom session filters on the Oracle® Enterprise Session Border Controller (ESBC) for Monitor and Trace purposes. These filters allow the system to filter incoming and outgoing session data with specific information and then displayed it on the GUI. You can use the custom filters during monitoring on a global basis, or when monitoring session agents and realms.

Use the filter-config object to create custom filters by way of Configure terminal, session-router, filter-config.

The following table lists and describes the attributes that you can configure for each filter.

Filter	Description
filter-config	Use to create a custom filters to be used for Monitor and Trace on the ESBC.
name	Name of the custom filter. Note: You specify this filter name when configuring global monitoring, SA monitoring, or realm monitoring.
address	IP address to filter. Depending on the value you specify for this attribute, filtering matches the IP address or IP address and netmask, in the message header. For example: 1.1.1.1 is <IP address> 1.1.1.1/24 is <IP address>/<Netmask>
user	Phone number or user-part to filter. Depending on the value you specify for this attribute, filtering matches the phone number string or the user-part with the following header information if it exists in the message:   From URI, To URI, Request URI, P-Preferred URI, P-Asserted Identity, P-Associated URI, P-Called Party URI.

You can define a single or multiple filters with specific names and then specify the filter names to use for global monitoring, session agent monitoring, and realm monitoring.

Creating a Custom Filter

Use the following procedure to create a custom filter on the Net-Net ESD.

To configure a filter(s):

In Superuser mode, type configure terminal and press Enter.
```
ACMEPACKET# configure terminal
```
Type session-router and press Enter to access the session router-related objects.
```
ACMEPACKET(configure)# session-router
ACMEPACKET(session-router)#
```
Type filter-config and press Enter to access the filter configuration-related attributes.
```
ACMEPACKET(session-router)# filter-config
ACMEPACKET(filter-config)#
```
name—Enter a name to assign to this filter. Valid values are alpha-numeric characters. Default is blank.
```
ACMEPACKET(filter-config)# name FILTER1
```
Note:
You can use this filter name when configuring monitoring on a global-basis, or when monitoring session-agents and/or realms.

address—Enter the IP address to apply to this filter. You can specify netmask if required. IP Address must be entered in dotted decimal format (0.0.0.0). Default is 0.0.0.0.
```
ACMEPACKET(filter-config)# address 1.1.1.1	(filters on IP address)
ACMEPACKET(filter-config)# address 1.1.1.1/24 (filters on IP address and netmask)
```
user—Enter a phone number or user-part to apply to this filter. Valid values are numeric characters. Default is blank.
```
ACMEPACKET(filter-config)# user 5551212
```
You must specify either the phone number OR user part for the user attribute. If you want both the phone number AND user part to be filtered, you must create separate filters to set each value.
Enter done to save the filter.
```
ACMEPACKET(filter-config)# done
```
Enter exit to exit the filter configuration.
```
ACMEPACKET(filter-config)# exit
```
Enter exit to exit the session-router configuration.
```
ACMEPACKET(session-router)# exit
```
Enter exit to exit the configure mode.
```
ACMEPACKET(configure)# exit
```
Enter save-config to save the filter configuration.
```
ACMEPACKET# save-config
```
Enter activate-config to activate the filter configuration.
```
ACMEPACKET# activate-config
```

Multiple Custom Filter Examples

The following examples show three custom filters (FILTER1, FILTER2, and FILTER3) created for SIP Monitor and Trace on the Net-Net ESD.

Filter 1

ACMEPACKET(filter-config)# name FILTER1
ACMEPACKET(filter-config)# address 1.1.1.1
ACMEPACKET(filter-config)# user 5551212

Filter 2

ACMEPACKET(filter-config)# name FILTER2
ACMEPACKET(filter-config)# address 3.3.3.3/24
ACMEPACKET(filter-config)# user 1781

Filter 3

ACMEPACKET(filter-config)# name FILTER3
ACMEPACKET(filter-config)# user sip

You can specify the Net-Net ESD monitoring process to use FILTER1, FILTER2, and/or FILTER3 for global monitoring, or for monitoring SAs and/or realms. However, before you apply the custom filters, you can enable/disable SIP monitoring on the Net-Net ESD.

To enable/disable SIP monitoring, see Enabling Disabling SIP Monitoring & Tracing. To use a custom filter(s) on a global basis, see Using Filters to Monitor on a Global-Basis. To use a custom filter(s) when monitoring SAs, see Using Filters when Monitoring Session Agents. To use a custom filter(s) when monitoring realms, see Using Filters when Monitoring Realms.

Enable and Disable SIP Monitor and Trace

You can enable or disable the Oracle® Enterprise Session Border Controller (ESBC) to perform SIP monitoring using the state parameter at the path Configure terminal, session-router, sip-monitoring.

Use the following procedure to enable and disable SIP monitoring on the ESBC.

Note:

You must enable the sip-monitoring object for monitoring and filtering to occur on the ESBC. With sip-monitoring enabled, you can configure a filter on a global basis, as well as for a session agent or a realm. You can also initiate dynamic filter commands.

To enable and disable sip-monitoring:

Access the sip-monitoring configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-monitoring
ORACLE(sip-monitoring)#

Press Enter to access the SIP monitoring-related attributes.

state—Enter whether or not to enable the sip monitoring on the ESBC. Default is enabled. Valid values: enabled | disabled. Default: enabled.
Type done to save the setting.
```
ACMEPACKET(sip-monitoring)# done
```
Type exit to exit the sip-monitoring configuration.
```
ACMEPACKET(sip-monitoring)# exit
```
Type exit to exit the session-router configuration.
```
ACMEPACKET(session-router)# exit
```
Type exit to exit the configure mode.
```
ACMEPACKET(configure)# exit
```
Type save-config to save the filters.
```
ACMEPACKET# save-config
```
Type activate-config to activate the filters in the current configuration.
```
ACMEPACKET# activate-config
```

Configure global filters, or assign filters to a session agent and realm. For more information, see the following:

With sip-monitoring enabled, you can also initiate dynamic filter commands if required. For more information about dynamic filter commands, see Dynamic Filter Commands.

Configure Filters to Monitor on a Global-Basis

The Oracle® Enterprise Session Border Controller (ESBC) allows you to filter SIP session data on a global-basis using the monitoring-filters object at the path Configure terminal, session-router, sip-monitoring, monitoring-filters. You can apply a single or multiple custom filter for global monitoring. For more information about creating a custom filter, see Creating a Custom Filter.

Note:

For SIP Monitor and Trace to trigger interesting-events, you must configure a filter value for the monitoring-filters object.

To configure filtering on a global basis:

Access the sip-monitoring configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-monitoring
ORACLE(sip-monitoring)#

Type select, and press Enter to select the sip-monitoring objects.
```
ACMEPACKET(sip-monitoring)# select
ACMEPACKET(sip-monitoring)#
```
monitoring-filters—Enter one or more custom filter names you want to use when monitoring on a global-basis. You can enter multiple filter names in a comma-separated list with no spaces, if required. To add to an existing filter list, use the “+” before the filter name you are adding. Use a “-” to remove filter names. Enter an * (asterisk) to filter all session data.
```
ACMEPACKET(sip-monitoring)# monitoring-filters FILTER1,FILTER2
ACMEPACKET(sip-monitoring)# monitoring-filters FILTER1,FILTER2 +FILTER3
ACMEPACKET(sip-monitoring)# monitoring-filters FILTER1,FILTER2 -FILTER3
ACMEPACKET(sip-monitoring)# monitoring-filters *
```
Note:
If you enter the * with a filter name, the filter name is ignored and the ESBC uses the * to filter all session data.
Type done to save the configuration.
```
ACMEPACKET(sip-monitoring)# done
```
Type exit to exit the sip-monitoring configuration.
```
ACMEPACKET(sip-monitoring)# exit
```
Type done to save the sip-monitoring configuration.
```
ACMEPACKET(session-router)# done
```
Type exit to exit the session-router configuration.
```
ACMEPACKET(session-router)# exit
```
Type exit to exit the configure mode.
```
ACMEPACKET(configure)# exit
```
Type save-config to save the configuration.
```
ACMEPACKET# save-config
```
Type activate-config to activate the configuration.
```
ACMEPACKET# activate-config
```

Configure Filters for Monitoring Session Agents

You can configure the Oracle® Enterprise Session Border Controller (ESBC) to perform filtering of SIP session data for Session Agent (SA) configurations. You must specify the hostname of the SA and the filter to use to perform the filtering, at the path Configure terminal, session-router, session-agent. For more information about creating a custom filter, see Creating a Custom Filter.

To configure filtering for a Session Agent:

Access the session-agent configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# session-agent
ORACLE(session-agent)

Type select, and press Enter.
```
ACMEPACKET(session-agent)# select
ACMEPACKET(session-agent)#
```
hostname—Specify the hostname of the session agent to which you want to apply the custom filter.
```
ACMEPACKET(session-agent)# hostname SA1
```
monitoring-filters—Enter the custom filter name you want to use when monitoring on a global-basis. You can enter multiple filter names in a comma-separated list with no spaces, if required. To add to an existing filter list, use the “+” before the filter name you are adding. Use a “-” to remove filter names. Enter an * (asterisk) to filter all SIP session data.
```
ACMEPACKET(session-agent)# monitoring-filters FILTER1,FILTER2
ACMEPACKET(session-agent)# monitoring-filters FILTER1,FILTER2 +FILTER3
ACMEPACKET(session-agent)# monitoring-filters FILTER1,FILTER2 -FILTER3
ACMEPACKET(session-agent)# monitoring-filters *
```
Note:
If you enter the * with a filter name, the filter name is ignored and the ESBC uses the * to filter all session data.
Type done to save the configuration.
```
ACMEPACKET(session-agent)# done
```
Type exit to exit the session-agent configuration.
```
ACMEPACKET(session-agent)# exit
```
Type done to save the configuration.
```
ACMEPACKET(session-router)# done
```
Type exit to exit the session-router configuration.
```
ACMEPACKET(session-router)# exit
```
Type exit to exit the configure mode.
```
ACMEPACKET(configure)# exit
```
Type save-config to save the configuration.
```
ACMEPACKET# save-config
```
Type activate-config to activate the configuration.
```
ACMEPACKET# activate-config
```

Configure Filters for Monitoring Realms

You can configure the Oracle® Enterprise Session Border Controller (ESBC) to perform filtering of SIP session data for realm configurations. You must specify the realm identifier and the filter to use to perform the filtering, at the path Configure terminal, media-manager, realm-config. For more information about creating a custom filter, see Creating a Custom Filter.

To configure filtering for a realm:

Access the realm-config configuration element.

ORACLE# configure terminal
ORACLE(configure)# media-manager
ORACLE(media-manager)# realm-config
ORACLE(realm-config)#

Type select, and press Enter.
```
ACMEPACKET(realm-config)# select
ACMEPACKET(realm-config)#
```
identifier—Specify the identifier of the realm to which you want to apply the custom filter(s).
```
ACMEPACKET(realm-config)# identifier REALM1
```
monitoring-filters—Enter the custom filter nameyou want to use when monitoring on a global-basis. You can enter multiple filter names in a comma-separated list with no spaces, if required. To add to an existing filter list, use the “+” before the filter name you are adding. Use a “-” to remove filter names. Enter an * (asterisk) to filter all SIP session data.
```
ACMEPACKET(realm-config)# monitoring-filters FILTER1,FILTER2
ACMEPACKET(realm-configg)# monitoring-filters FILTER1,FILTER2 +FILTER3
ACMEPACKET(realm-config)# monitoring-filters FILTER1,FILTER2 -FILTER3
ACMEPACKET(realm-config)# monitoring-filters *
```
Note:
If you enter the * with a filter name, the filter name is ignored and the ESBC uses the * to filter all session data.
Type done to save the configuration.
```
ACMEPACKET(realm-config)# done
```
Type exit to exit the realm-config configuration.
```
ACMEPACKET(realm-config)# exit
```
Type done to save the configuration.
```
ACMEPACKET(media-manager)# done
```
Type exit to exit the media-manager configuration.
```
ACMEPACKET(media-manager)# exit
```
Type exit to exit the configure mode.
```
ACMEPACKET(configure)# exit
```
Type save-config to save the configuration.
```
ACMEPACKET# save-config
```
Type activate-config to activate the configuration.
```
ACMEPACKET# activate-config
```

Global SA and Realm Filter Examples

The following are examples of global, session agent, and realm filters configured on the Oracle® Enterprise Session Border Controller. These examples assume that FILTER1, FILTER2, and FILTER3 have been pre-configured as custom filters.

Global Filter

ACMEPACKET(sip-monitoring)# monitoring-filters FILTER1,FILTER3

This filter captures the SIP session data based on the filter settings in FILTER1 and FILTER3 only, for all sessions on the Net-Net ESD.

Session Agent Filters

ACMEPACKET(session-agent)# hostname SA1
ACMEPACKET(session-agent)# monitoring-filters FILTER2
ACMEPACKET(session-agent)# hostname SA2 
ACMEPACKET(session-agent)# monitoring-filters FILTER2,FILTER3

These filters capture the SIP session data for SA1 only, based on the filter settings in FILTER2, and the SIP session data for SA2 only, based on the filter settings in FILTER2 and FILTER3.

Realm Filters

ACMEPACKET(realm-config)# identifier REALM1
ACMEPACKET(realm-config)# monitoring-filters *
ACMEPACKET(realm-config)# identifier REALM2 
ACMEPACKET(realm-config)# monitoring-filters FILTER1

These filters capture all SIP session data for REALM1, and the SIP session data for REALM2 only, based on the filter settings in FILTER1.

Note:

If you leave a monitoring-filter field blank, no monitoring takes place for that object.

Interesting Events

Interesting events on the Oracle® Enterprise Session Border Controller (ESBC) are used the purpose of troubleshooting SIP sessions in your network. You can specify the type of interesting event you want to filter using the object, interesting-events at the path, Configure terminal, session-router, sip-monitoring, interesting-events.

The ESBC can monitor the following types of interesting events:

short-session events
local-rejection events

You can use the following trigger attributes to specify time provisioning for the interesting events:

trigger-threshold
trigger-timeout

Note:

You can also set a trigger-window object to support these trigger attributes. For more information, see Configuring a Trigger Window.

The following table identifies the attributes you can set for the interesting-events object.

Filter	Description
interesting-events	Use to configure trigger attributes that apply to the filters you set on the ESBC. Note: Interesting Events are always enabled on a global-basis on the ESBC.
type	Use to set the interesting events to monitor, for example, short-session and local-rejection.
trigger-threshold	Use to set the number of interesting events that must occur within the time set by the trigger-window value. If the number of events reaches the trigger-threshold during the trigger-window time, monitoring is started.
trigger-timeout	Use to sets the amount of time, in seconds, that the trigger is active once monitoring has started. If no interesting events occur in the time frame set for this value, monitoring never starts. For example, if trigger-timeout is set to 40, and no interesting events occur in 40 seconds, then monitoring never starts.

The ESBC considers short session and local rejection as interesting events. A session is viewed as a short session if the length of time, in seconds, is equal to or below the short-session-duration value configured at the path Configure terminal, session-router, session-router-config, short-session-duration. A local rejection can occur when sessions are locally rejected at the ESBC for any reason. For example, Session Agent (SA) unavailable, no route found, and SIP signaling error.

If a short session or local rejection event occurs, the ESBC uses the values configured for the trigger attributes to determine when to start filtering the SIP session data.

If a short session event occurs when the ESBC is not monitoring, the event information is taken from the last BYE that occurred in the session In such a situation, only some parts of the call flow may display in the GUI. If a local rejection event occurs when the ESBC is not monitoring, it displays only the information in the last rejected transaction.

Interesting Events Configuration

To configure interesting events:

In Superuser mode, type configure terminal and press Enter.
```
ACMEPACKET# configure terminal
```
Type session-router and press Enter to access the session router-related objects.
```
ACMEPACKET(configure)# session-router
ACMEPACKET(session-router)#
```
Type session-router again and press Enter to access the session router configuration-related attributes.
```
ACMEPACKET(session-router)# session-router
ACMEPACKET(session-router-config)#
```
short-session-duration—Enter the maximum session duration, in seconds, to be considered a short session. Default is 0 (disabled). Valid values are 0 to 999999999.
```
ACMEPACKET(session-router-config)# short-session-duration 30
```

Enter done to save the filters.

ACMEPACKET(session-router-config)# done
ACMEPACKET(session-router-config)#

Enter exit to exit the interesting-events configuration.

ACMEPACKET(session-router-config)# exit
ACMEPACKET(session-router)#

Type sip-monitoring and press Enter to access the SIP monitoring-related attributes.
```
ACMEPACKET(session-router-config)# sip-monitoring
ACMEPACKET(sip-monitoring)#
```

Type select and press Enter.

ACMEPACKET(sip-monitoring)# select
ACMEPACKET(sip-monitoring)#

Type interesting-events and press Enter to access the interesting events-related attributes.
```
ACMEPACKET(sip-monitoring)# interesting-events
ACMEPACKET(interesting-events)#
```
type—Enter the type of interesting event you for which you want to filter. Default is blank and disables this filter. Valid values are:
- short-session
- local-rejection
```
ACMEPACKET(interesting-events)# type short-session
```
  trigger-threshold — (optional) Enter the number of interesting events that must occur within the time set by the trigger window value. If the number of events reaches the trigger-threshold during the trigger-window time, monitoring is started.Default is 0 (disabled). Valid values are 0 to 999999999.
```
ACMEPACKET(interesting-events)# trigger-threshold 50
```
  trigger-timeout —Sets the amount of time, in seconds, that the trigger is active once monitoring has started. If no interesting events occur in the time frame set for this value, monitoring never starts. Default is 0 (trigger always on). Valid values are 0 to 999999999.
```
ACMEPACKET(interesting-events)# trigger-timeout 30
```
Enter done to save the filters.
```
ACMEPACKET(interesting-events)# done
```
Enter exit to exit the interesting-events configuration.
```
ACMEPACKET(interesting-events)# exit
```
Enter exit to exit the sip-monitoring configuration.
```
ACMEPACKET(sip-monitoring)# exit
```
Enter done to save the configuration.
```
ACMEPACKET(session-router)# done
```
Enter exit to exit the session-router configuration.
```
ACMEPACKET(session-router)# exit
```
Enter exit to exit the configure mode.
```
ACMEPACKET(configure)# exit
```
Enter save-config to save the filters.
```
ACMEPACKET# save-config
```
Enter activate-config to activate the filters in the current configuration.
```
ACMEPACKET# activate-config
```

Configuring a Trigger Window

The trigger-window attribute specifies the amount of time, in seconds, for the window of time that the trigger-threshold value must reach before monitoring begins. For example, if “interesting-event” type is set to short-session, “trigger-threshold” is set to 2, and trigger-window is set to 60, monitoring begins when the Net-Net ESD has discovered 2 short-session events in a 60 second window.

Use the following procedure to configure a trigger window.

To configure a trigger window:

In Superuser mode, type configure terminal and press Enter.
```
ACMEPACKET# configure terminal
```
Type session-router and press Enter to access the session router-related objects.
```
ACMEPACKET(configure)# session-router
ACMEPACKET(session-router)#
```
Type sip-monitoring and press Enter to access the SIP monitoring-related attributes.
```
ACMEPACKET(session-router)# sip-monitoring
ACMEPACKET(sip-monitoring)#
```
Type select and press Enter.
```
ACMEPACKET(sip-monitoring)# select
ACMEPACKET(sip-monitoring)#
```
trigger-window—Enter the amount of time, in seconds, for the window of time that the trigger-threshold value must reach before monitoring begins. Default is 30. Valid values are 0 to 999999999. Zero (0) disables this the trigger-window parameter.
```
ACMEPACKET(sip-monitoring)# trigger-window 50
```
Enter done to save the filters.
```
ACMEPACKET(sip-monitoring)# done
```
Enter exit to exit the sip-monitoring configuration.
```
ACMEPACKET(sip-monitoring)# exit
```
Enter done to save the configuration.
```
ACMEPACKET(session-router)# done
```
Enter exit to exit the session-router configuration.
```
ACMEPACKET(session-router)# exit
```
Enter exit to exit the configure mode.
```
ACMEPACKET(configure)# exit
```
Enter save-config to save the filters.
```
ACMEPACKET# save-config
```
Enter activate-config to activate the filters in the current configuration.
```
ACMEPACKET# activate-config
```

Example

The following is an example filter configuration, filtering interesting events with a trigger window on the Oracle® Enterprise Session Border Controller. These parameters perform filtering on a global basis.

Monitoring Enabled on a Global Basis

ACMEPACKET(sip-monitoring)# state enabled

Short-Session Configured

ACMEPACKET(interesting-events)# type short-session
ACMEPACKET(interesting-events)# trigger-threshold 2
ACMEPACKET(interesting-events)# trigger-timeout 60

Local-Rejection Configured

ACMEPACKET(interesting-events)# type local-rejection
ACMEPACKET(interesting-events)# trigger-threshold 1
ACMEPACKET(interesting-events)# trigger-timeout 0

Trigger-Window Configured

ACMEPACKET(sip-monitoring)# trigger-window 120

The configuration above has global SIP monitoring enabled and is set to capture interesting events that are short-session and local-rejection events.

Per the triggers for the short-session configuration, if 2 (trigger-threshold) short-session events occur in a window of 120 seconds (trigger-window), then monitoring is started. If no short-session events occur after 60 seconds (trigger-timeout), no monitoring is started.

Per the triggers for the local-rejection configuration, if more that 1 (trigger-threshold) local-rejection event occurs in a window of 120 seconds (trigger-window), then monitoring is started. The value of 0 (trigger-timeout) indicates that monitoring is always enabled for this event.