Setting a diagnostic trace for specific user names and domains

In Sametime® Gateway, you can perform diagnostic traces only for specific user names and domains. You can use this method of diagnostic trace when your Gateway is a production system that handles a high number of transactions per second, and server-wide diagnostic traces might adversely impact server performance.

About this task

This type of selective tracing works in parallel with the usual server-wide diagnostic trace. One method does not impact the other. The user names and domains pattern by which the diagnostic trace is produced is given as a regular expression. If the transaction's context does not match the set pattern, no diagnostic trace is produced. As with other diagnostic traces, you can perform selective tracing without having to restart your Gateway server.

Traces are printed to the log file profile_root/logs/trace.log. For additional information about default paths, see Directory conventions.

Procedure

Enable a diagnostic trace on a WebSphere® Application Server.
1. Log in to the WebSphere Integrated System Console as the administrator.
2. In the navigation pane, click Troubleshooting > Logs and trace.
3. Click the RTCGWServer that you want to trace - typically, all of the servers in a cluster.
4. In the General Properties section, click Diagnostic Trace.
5. Select one of the following tabs:
  Configuration -- Selected by default. Changes you make here are saved after the server is restarted.
  Runtime -- Displays only if the server is running. Changes you make here are not saved, but apply until the server is restarted.
  Tip: If you make changes on this tab, and then decide you want to preserve your changes after a server restart, select Save runtime changes to configuration as well.
6. In the General Properties section, click Change Log Detail Levels.
7. Add the following setting to the text that displays in the text area:
```
: com.ibm.rtc.gateway.tracing.StgwLogger=all:
```
  For example, if the default log trace level *=info displays in the text area, then the resulting trace level would display:
```
*=info: com.ibm.rtc.gateway.tracing.StgwLogger=all:
```
8. Click OK to save your changes.
9. Click Save in the "Messages" box to save the change the master configuration.
Create a custom property that defines the user names and domains pattern:
1. In the WebSphere Integrated System Console, open the Custom properties page for the server:
  - Single server -- click Servers > Server Types > WebSphere application servers > server_name > Server Infrastructure > Administration > Custom Properties
  - Cluster -- click System administration > Cell > Custom Properties
2. Click New and enter the following information for a trace pattern filter custom property:
  - Name - tracing.filter.pattern
  - Value - A regular expression
  For example, the following regular expression example would include the mail address: user1@domain10.com, as well as user2@domain2.com, user20@domain2.com, and user212@domain2.com.
```
(@E )?user1@domain10.com|(@E )?user2.*@domain2.com
```
  In this example:
  - (@E )? - is a required prefix that must appear before the user name.
  - user1@domain10.com - is the user's email address.
  - | - denotes an OR logical condition.
  - user2.*@domain2.com - matches any email address that begins with user2, then contains any number of characters, and ends with @domain2.com.
3. Click OK to save the new custom property.
4. Click Save in the "Messages" box to save the new property to the master configuration.
5. Restart the Sametime Gateway server; in a clustered environment, restart the cluster. If you do not want to restart the environment for these settings to take effect, continue to Step 3.
Optional: Complete these steps to apply the pattern in run time without restarting the server.
You are still required to enter the described custom property in order to persist the trace across server restarts. If in a cluster, the following steps need to be executed once on the Sametime Gateway deployment manager only (there's no need to execute on each cluster member directly), or on the stand-alone server (if not in a cluster):
1. Copy the setTracePattern.py and the STGWCommon.py scripts from stgw_server_root/config/adminscripts to the deployment manager node: was_install_root/bin.
2. Open a command window and navigate to was_install_root/bin.
3. Run the following command:
```
wsadmin -lang jython -username username -password password -f setTracePattern.py "pattern"
```
  Where:
  - username and password are the name and password of the administrative user ID that you used to log in to the WebSphere Integrated Solutions Console.
  - pattern is the regular expression you created, enclosed in quotation marks.
  For example, using the pattern created in Step 2, you would type the following command:
```
wsadmin -lang jython -username username -password password -f setTracePattern.py "(@E\s{1})?user1@domain10.com|(@E\s{1})?user2.*@domain2.com"
```
  Tip: The pattern created in Step 2 included a space character. However, if you enter the pattern by using the shell command line, use the characters \s{1} instead of a space. Other than this difference, the custom property pattern and the command line pattern should be identical.
  Note: Any pattern will be lowercase, because the tracing filter is not case sensitive.
4. To stop tracing and remove the pattern use "remove" as the pattern:
```
wsadmin -username username -password password -f setTracePattern.py "remove"
```
5. The script has completed when the final line displays OK: successfully set pattern on all servers.
Optional: Set a runtime diagnostic trace from the WebSphere Application Server administrative console to apply selective trace during run time. When the server is restarted, these settings are recycled. Follow these steps to set up the runtime diagnostic trace.
1. In the WebSphere Integrated Solutions Console, expand the Sametime Gateway group and click Selective Trace.
2. Type the pattern in the User name pattern field and click Add. The added pattern appears in the table. Repeat this step until all of your patterns are added.
3. Click Apply to save your new patterns.
  All of the patterns (not just selected patterns) are applied to the trace. You do not need to restart the Gateway server or clustered servers.