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.
- Log in to the WebSphere Integrated
System Console as the administrator.
- In the navigation pane, click .
- Click the RTCGWServer that you want to trace - typically, all of
the servers in a cluster.
- In the General Properties section, click Diagnostic
Trace.
- 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.
- In the General Properties section,
click Change Log Detail Levels.
- 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:
- Click OK to save your changes.
- 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:
- In the WebSphere Integrated
System Console, open the Custom properties page for the server:
- Single server -- click
- Cluster -- click
- 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
.
- Click OK to save the new custom
property.
- Click Save in the "Messages"
box to save the new property to the master configuration.
- 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):
-
Copy the setTracePattern.py and the STGWCommon.py
scripts from stgw_server_root/config/adminscripts to the
deployment manager node: was_install_root/bin.
- Open a command window and navigate to was_install_root/bin.
- 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.
- To stop tracing and remove the pattern use
"remove"
as
the pattern:wsadmin -username username -password password -f setTracePattern.py "remove"
- 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.
- In the WebSphere Integrated
Solutions Console, expand the Sametime Gateway group and click Selective
Trace.
- 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.
- 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.