Troubleshooting the SIP container session repository on Liberty

When you troubleshoot the SIP container session repository, you might need the SIP session details to dump to a specified trace file.

About this task

You can use the SIP session memory dump utility to help debug problems that are related to SIP container sessions. The SIP container provides the SipContainerMBean method to perform several serviceability type operations on the SIP container, including the initiation of a server quiesce through the command line. This task describes how you can use the SipContainerMBean method to dump SIP application session and SIP session information that is contained in the in-memory session repository for SIP containers. By configuring the SIPContainerMBean method to use various trace methods, you can specify the SIP session details to dump to the specified trace file.

When the session dump methods are started, the requested information about the sessions prints by default into the console.log file. You can also send the information to a predefined source specified on the setDumpMethod method.

You can run the dumping utility in two modes, succinct and verbose. When you use the succinct session dump methods, only the session IDs are printed for every dump method execution. If you want to use the verbose session dump methods, the following actions occur:

Transaction user details, along with the SIP session details, if they exist, print for every dump method execution.
The only attributes that dump to the trace file are those attributes that the JSR 289 specification permits for exposure.
The verbose methods print the following information in the trace file: appName, callID, dialog state, creation time, attribute names.

The trace printouts occur per SIP application; therefore, the sorting of all the SIP session data structures occurs before printing. The SIPContainerMBean dump facility runs in a low-priority thread so that the tracing does not affect the call processing latency of the overall system for a production server.

The dump distinguishes between a transaction user that has a SIP session versus a transaction user that has no SipSession object. Also included in the dump, in a delineated fashion, are SIP sessions that no longer exist, that are no longer valid, or that exist at the time of the trace snapshot.

On Liberty, you can invoke the SIPContainerMBean dumping methods in two ways:

By running the server dump command
By implementing a Java™ Management Extensions (JMX) client that establishes a connection to the JMX connector to invoke the methods

The following succinct SipContainerMBean methods are used to dump SIP session IDs.

Table 1. Succinct SipContainerMBean methods used to dump SIP session information
Method	Description
dumpAllSASIds()	Prints a number of all SIP application sessions and the SIP application session IDs.
dumpAllTUSipSessionIds()	Prints a number of transaction users and the SIP session IDs within the transaction user (TU), if one exists.

The following verbose SipContainerMBean methods are used to dump SIP session details.

Table 2. Verbose SipContainerMBean methods used to dump SIP session information
Method	Description
dumpAllSASDetails()	Prints a number of all SIP application sessions and the SIP application session ID details.
dumpAllTUSipSessionDetails()	Prints a number of transaction users and details of the SIP session IDs within the transaction user (TU), if one exists.
dumpSASDetails(String sasId)	Prints the details of the SIP application session that is specified by the `sasId` parameter.
dumpSipSessionDetails(String sessionId)	Prints the details of the SIP session that is specified by the `sessionId` parameter.

Note: Use the following information to help parse print output:

For all print output, the first line provides an application name and a number of records.
The delimiter between the output is a TAB.
The delimiter between session attributes is a ; (semi-colon).

Procedure

Invoke the SIPContainerMBean methods with the server dump command.
1. In the server.xml file, specify the dumping utility mode on a sipIntrospect element.
  - For succinct mode, specify the following code:
```
<sipContainer>
     <sipIntrospect method="SUCCINCT"/>
</sipContainer>
```
  - For verbose mode, specify the following code:
```
<sipContainer>
     <sipIntrospect method="VERBOSE"/>
</sipContainer>
```
2. Open a command line and change to the wlp/bin directory.
3. To generate the SIP sessions and SIP application sessions dump, run the following command, where server_name is the Liberty server:
```
server dump server_name
```
  If you do not specify a server name, defaultServer is used.
  You can optionally specify the name of the server dump package file on the archive parameter:
```
server dump server_name --archive=package_file_name.dump.zip
```
  After you run the command, the server dump package file is generated and contains the following files:
  - SipContainerIntrospector.txt, which includes the requested level of trace information about the SIP application sessions and SIP sessions
  - Other artifactIntrospector.txt files, which provide the server status information
  SipContainerIntrospector.txt includes the following information, where dump.ids.test.app1 is the application name, 2 is the number of sessions, and the local.##### lines are the SAS_ids:
```
The description of this introspector:
SIP state details

Succinct dumping

dump.ids.test.app1		 2
local.1347524282775_8
local.1347524282775_7

--- End of Dump ---
```

Invoke a specific dumping utility method through JMX connectors.

For more information, see Connecting to Liberty by using JMX and Developing a JMX Java client for Liberty.

The following Java code example invokes the dumpAllSASIds method.

    System.setProperty("javax.net.ssl.trustStore", "..\\wlp\\usr\\servers\\SIPServer\\resources\\security\\key.p12");
    System.setProperty("javax.net.ssl.trustStorePassword", "Liberty");

    //If the type of the trustStore is not jks, which is default, 
    //set the type by using the following line.
    System.setProperty("javax.net.ssl.trustStoreType", "PKCS12");
   
   try {	   
      HashMap<String, Object> environment = new HashMap<String, Object>();
      environment.put("jmx.remote.protocol.provider.pkgs", "com.ibm.ws.jmx.connector.client");
      environment.put("com.ibm.ws.jmx.connector.client.disableURLHostnameVerification", Boolean.TRUE);
      environment.put(JMXConnector.CREDENTIALS, new String[] { "theUser", "thePassword" });
      environment.put(ConnectorSettings.DISABLE_HOSTNAME_VERIFICATION, true); 

      JMXServiceURL url = new JMXServiceURL("service:jmx:rest://localhost:9443/IBMJMXConnectorREST");
      JMXConnector connector = JMXConnectorFactory.newJMXConnector(url, environment);
      connector.connect();
      MBeanServerConnection connection = connector.getMBeanServerConnection();
      
      // test dumping utility
      connection.invoke(new ObjectName("WebSphere:name=com.ibm.ws.sip.container.SipContainerMBean"), "dumpAllSASIds", null, null);

Through 19.0.0.2, the following Java code example invokes the dumpAllSASIds method.

    System.setProperty("javax.net.ssl.trustStore", "..\\wlp\\usr\\servers\\SIPServer\\resources\\security\\key.jks");
    System.setProperty("javax.net.ssl.trustStorePassword", "Liberty");

    //If the type of the trustStore is not jks, which is default, 
    //set the type by using the following line.
    System.setProperty("javax.net.ssl.trustStoreType", "jks");
   
   try {	   
      HashMap<String, Object> environment = new HashMap<String, Object>();
      environment.put("jmx.remote.protocol.provider.pkgs", "com.ibm.ws.jmx.connector.client");
      environment.put("com.ibm.ws.jmx.connector.client.disableURLHostnameVerification", Boolean.TRUE);
      environment.put(JMXConnector.CREDENTIALS, new String[] { "theUser", "thePassword" });
      environment.put(ConnectorSettings.DISABLE_HOSTNAME_VERIFICATION, true); 

      JMXServiceURL url = new JMXServiceURL("service:jmx:rest://localhost:9443/IBMJMXConnectorREST");
      JMXConnector connector = JMXConnectorFactory.newJMXConnector(url, environment);
      connector.connect();
      MBeanServerConnection connection = connector.getMBeanServerConnection();
      
      // test dumping utility
      connection.invoke(new ObjectName("WebSphere:name=com.ibm.ws.sip.container.SipContainerMBean"), "dumpAllSASIds", null, null);

Succinct SipContainerMBean methods have the following print formats.

Table 3. Succinct SipContainerMBean method print formats
Method	Print format
dumpAllSASIds()	Each line represents a SIP application session ID, in the format `[SAS_ID]`. For example: `local.1347524282775_8`
dumpAllTUSipSessionIds()	Each line represents the transaction ID, whether the transaction has a SIP session, and the session ID if it exists, in the format `[TU_ID] [hasSIPSession] [SipSessionId]` For example: `local.1349965420866_1_0 true local.1349965420866_1_0_1`

Verbose SipContainerMBean methods have the following print formats.

Table 4. Verbose SipContainerMBean method print formats
Method	Description
dumpAllSASDetails()	Each line represents the SIP application session ID, the creation time, and the SIP session attributes, in the format `[SAS_ID] [CreationTime] [attributes]` For example: `local.1348147884986_2 Sep 20,2012 16:31 DumpSasDetailsAttr;`
dumpAllTUSipSessionDetails()	Each line represents the transaction ID, whether the transaction has a SIP session, and the session details if it exists, in the format `[TU_ID] [hasSIPSession] [SipSessionId] [Call-Id] [DialogState] [hasOutgoingTransaction] [initialMethod] [SAS_ID] [CreationTime] [attributes]` For example: `local.1349965420866_1_0 true local.1349965420866_1_0_1 8-8548@9.148.57.128 2 false INVITE local.1349965420866_1 Jan 24,2013 14:41 TestSSAttr1; TestSSAttr2;`
dumpSASDetails(String sasId)	Only one line is printed, in the format `[TU_ID] [hasSIPSession] [SipSessionId]` For example: `local.1349965420866_1_0 true local.1349965420866_1_0_1` If the requested session does not exist, the following error message is printed: ERROR: Requested session <local.1349965420866_1_0_1> does not exist.
dumpSipSessionDetails(String sessionId)	Only one line is printed, in the format `[SipSessionId] [Call-Id] [DialogState] [hasOutgoingTransaction] [initialMethod] [SAS_ID] [CreationTime] [attributes]` For example: `local.1349965420866_1_0_1 8-8548@9.148.57.128 2 false INVITE local.1349965420866_1 Jan 24,2013 14:41 TestSSAttr1; TestSSAttr2;` If the requested session does not exist, the following error message is printed: ERROR: Requested session <local.1349965420866_1_0_1> does not exist.