Advanced Logging

Advanced Logging allows targeted logging by overriding log levels, so that only a specific SIP request and its related messages get logged. The system matches criteria that you configure to determine which requests to log. The system also logs all messages related to the request, such as any responses, in-dialog messages, media, timers, and so on. Advanced Logging supports multiple matching criteria for incoming requests and rate limiting. Advanced log files are smaller than debug files because the system logs only the specified number of matches in the specified period of time. Since the files are smaller, Advanced Logging uses fewer system resources than debug logging. To make searching easier, the system labels each log.

You can deploy advanced logging by way of configuration. You configure the sip-advanced-logging element and adv-log-conditions subelement on the session router according to the logging targets.

You can control when logging occurs by enabling or disabling individual advanced logging objects using the state parameter. This allows you to retain advanced logging configurations on the system and simply start and stop logging against those objects when needed.

By executing the notify sipd conditional-log disable command, you can disable the ability to trigger all of the configured sip-advanced-logging objects.

ORACLE#notify sipd conditional-log-disable

Any active sip-advance-logging instances continue to log because the command only disables the ability to trigger new instances. You can restore the ability to trigger new instances for all sip-advance-logging objects with the notify sipd conditional-log-enable command .

The system provides the following options for configuring the scope of advanced logging.

Request-only. Logs only the matched message.
Transaction. Logs only the request and the response.
Session. Logs the matched message and anything else related to the session.
Session and Media. Logs the matched message, anything related to the session, and media.

The system provides the following options for configuring the advanced logging criteria.

Received Session-Agent, by IP address or hostname.
Request Types, such as INVITE vs. SUBSCRIBE.
Received Realm Name.
Request URI. User and host. Limited to 2 condition entries, when using both types.
To header. User and host. Limited to 2 condition entries, when using both types.
From header. User and host. Limited to 2 condition entries, when using both types.
Call-id. Matches the Call-id header.
Rate Limiting. By specified number of matched requests over a specified period of time.
Scope of Logging. Options include Request Only, Transaction, All Relating to Session, All Relating to Session and Media.

When you enable a sip-adv-logging object, applicable events trigger this logging by the Sipd (SIP signaling) process, resulting in log messages from it. The Sipd process also propagates advanced logging to the Atcpd (TCP connections), Ebmd (bandwidth managment), Lrtd (local routing table), Radd (accounting), and Middle Box Control Daemon (MBCD) processes, resulting in additional log messages from them. In addition, Mbcd events, including asynchronous 2833, flowguard timer and latching events, can propagate conditional logging to Sipd, resulting in log messages from Sipd.

Behavior During High Availability Synchronization

When the system is synchronizing a thread at the same time that thread is performing advanced logging, this logging continues on the standby while the replication takes place. This logging on the standby, however, stops after replication is complete, with the exception of sip-sessions and media flows.

Threads associated with sip-sessions and flows continue to store their logging state after replication. The logging state is stored in either the session or flow. When a switchover happens while a thread is processing one of these sessions or flows, the system finds the stored logging state and continues logging even though the event was triggered on the other node of the HA pair.

Configure Advanced Logging - Command Line

You can enable advanced logging and set the log matching criteria from the command line by way of the AdvancedLogging.lua SPL-plugin. When adding log matching criteria, note that within in each set of criteria:

an AND relationship means that all conditions must match before the system generates the log.
an OR relationship means that only one set of conditions must match before the system generates the log.

Note:

The system does not require you to save and activate after performing this procedure.

Procedure

Use the spl start sip advanced-logging command to enable advanced logging.
Use the following commands to configure advanced logging.
- spl set sip advanced-logging add-criteria—Adds another set of matching criteria.
- spl set sip advanced-logging log-label <label string>—Any logs of requests that are matched will have the specified <label string> appended before each log message for easier searching.
- spl set sip advanced-logging rate-count <match count>—Sets the rate-limiting to log only <match count> number of matching requests per time window.
- spl set sip advanced-logging rate-time <time window>—Sets the rate-limiting time window in seconds.
- spl set sip advanced-logging in-agent <session-agent>—Adds to the current set of matching criteria that the request must come from the specified incoming session-agent hostname.
- spl set sip advanced-logging in-realm <realm-id>—Adds to the current set of matching criteria that the request must come from the specified incoming realm identifier.
- spl set sip advanced-logging request-type <method name>—Adds to the current set of matching criteria that the request must be of the specified request method type, for example, INVITE and REGISTER.
- spl set sip advanced-logging from-uri-host <FROM URI host portion>—Adds to the current set of matching criteria that the request FROM headerURI host portion must match the specified value exactly.
- spl set sip advanced-logging from-uri-user <FROM URI username portion>—Adds to the current set of matching criteria that the request FROM headerURI username portion must match the string and the specified value exactly.
- spl set sip advanced-logging to-uri-host <TO URI host portion>—Adds to the current set of matching criteria that the request TO headerURI host portion must match the string and the specified value exactly.
- spl set sip advanced-logging to-uri-user <TO URI username portion>—Adds to the current set of matching criteria that the request TO headerURI username portion must match the string and the specified value exactly.
- spl set sip advanced-logging request-uri-host <RURI host portion>—Adds to the current set of matching criteria that the request RURI headerURI host portion must match the string and the specified value exactly.
- spl set sip advanced-logging request-uri-user <RURI username portion>—Adds to the current set of matching criteria that the request RURI headerURI username portion must match the string and the specified value exactly.
- spl set sip advanced-logging header <header-type> <header-value>—Adds to the current set of matching criteria that the request must have a header of type <header-type> with a value of <header-value> with exact string matches.

Configuring Advanced Logging

From Configure mode, define sip-advanced-logging and advanced-log-condition. The criteria that you configure remaps the message logging and modifies the system configuration. You must save and activate the changes to the configuration.

When configuring multiple sip-advanced-logging configurations, note the following:

The system evaluates each configuration individually in an OR relationship.
The system evaluates all conditions and they must all match in an AND relationship.

Access the ifc-profile configuration element.

ORACLE# configure terminal
ORACLE(configure)# session-router
ORACLE(session-router)# sip-advanced-logging
ORACLE(sip-advanced-logging)#

Configure the following parameters.
- Name. Name to display on the log message for this set of criteria.
- State. Activates or deactivates this advanced logging object.
- Level. Type one: zero, none, emergency, critical, major, minor, warning, notice, info, trace, debug, or detail.
- Scope. Type one: request-only, transaction, session, or session-and-media.
- Matches-per-window. Type a number between 1 and 999999999 for how many matches to log per window of time.
- Window-size. Type a number between 1 and 999999999 seconds for the length of time the logging window is open.
- Type conditions.
  The system displays the adv-log-condition subelement.

Select the sip-advanced-logging > conditions object to edit, or create a new one.

ORACLE(sip-advanced-logging)# adv-log-condition
ORACLE(adv-log-condition)# select 
<name>:
1:  name=condition1

ORACLE(adv-log-condition)#

From the adv-log-condition prompt, configure the following:
- Match-type. Type one or more of the following sip objects with either the "and" or the "or" operator between objects: request-type, recv-agent, recv-realm, request-uri-user, request-uri-host, to-header-user, to-header-host, from-header-user, from-header-host, or call-id.
- Match-value. Type the incoming message text string that you want to match.
  
  For example, to match "To-header-user" to the value 1234@<companyname>.com, type "to-header-user" for Match type and type " 1234" for Match value.
Note:
The match-value parameter does not support regex expressions.
Type done (twice) to retain your sub-element and element configuration.
Exit, save, and activate.

Disable Advanced Logging - Command Line

Confirm that advanced logging is enabled by way of the AdvancedLogging.lua SPL-plugin.

You can disable advanced logging by way of the command line without affecting any sip-advanced-logging that is enabled by way of the Configure Mode.

From the AdvancedLogging.lua SPL-plugin, run the spl stop advanced-logging command.

Disable Advanced Logging - Configure Mode

Confirm that Advanced Logging is enabled in Configure Mode.

To disable Advanced Logging in Configure Mode, clear all of the settings for sip-advanced-logging and advanced-log-condition. Disabling Advanced Logging in Configure Mode does not affect Advanced Logging that is enabled from the command line.

From Configure Mode, go to session-router > sip-advanced-logging and clear the following information.
- Name
- Level
- Scope
- Matches-per-window
- Window-size
- Conditions
From Configure Mode, go to session-router > sip-advanced-logging > advanced-log-condition and clear the following information.
- Match-type
- Match-value
Exit, save, and activate.

Clear Advanced Logging Criteria - Command Line

Use this procedure to clear the advanced logging conditions that were configured from the command line. This procedure clears all conditions and returns the system to the default state, in which all requests are matched.

From the AdvancedLogging.lua SPL-plugin, run the spl set sip advanced-logging clear-matching command.

View Advanced Logging Status - Command Line

View the status of advanced logging to see its state, configuration criteria, and count data.

Procedure

From the AdvancedLogging.lua SPL-plugin, run the spl show sip advanced-logging command.
The system displays the following information.
- State
- Log Label
- Rate Limit
- Matching Criteria
- Match Count
- Logged Count