Question & Answer
Question
How do I enable the trace facility on an IBM Content Manager OnDemand server?
Answer
The Content Manager OnDemand server trace facility provides IBM Support with detailed diagnostic information to assist in troubleshooting.
Trace has an impact on Content Manager OnDemand server performance and should be enabled only under the direction of IBM Support. Due to the verbose nature of trace, you should limit the length of time and the number of components that you trace as much as possible while still gathering the required trace data.
Trace has an impact on Content Manager OnDemand server performance and should be enabled only under the direction of IBM Support. Due to the verbose nature of trace, you should limit the length of time and the number of components that you trace as much as possible while still gathering the required trace data.
Trace occurs in two parts: startup trace and runtime trace. Startup trace occurs between the time the server is started (by using the ARSSOCKD program or the STRTCPSVR command) and when the database connections are established. Since Content Manager OnDemand does not have access to the database until the database connections exist, the values in the trace.settings file are used to initialize trace and generate trace output during startup. Once the database connections are available, the runtime trace values, which are set by using the OnDemand Administrator client, are read from the database and used for runtime trace.
The trace.settings file specifies the file name of the trace file, sets the startup trace values, and can optionally specify whether trace appends to existing trace files or creates new ones. Without it, server trace is not possible. The OnDemand Administrator client can turn runtime trace on/off and change the trace settings but cannot initialize trace or affect startup trace.
To enable Content Manager OnDemand server trace:
To enable Content Manager OnDemand server trace:
1. Locate your trace.settings file. This file contains the TRACE_LEVELS and TRACE_FILE parameters, and optionally the APPEND parameter, which are used by the trace facility. The location of this file depends on your Content Manager OnDemand platform. For example:
- On an AIX V10.5 system, it is located in the /opt/IBM/ondemand/V10.5/config directory.
- On a Linux or zLinux V10.5 system, it is located in the /opt/ibm/ondemand/V10.5/config directory.
- On a Windows V10.5 system, it is located by default in C:\Program Files\IBM\OnDemand\V10.5\config.
- On an IBM i system, a sample trace.settings file is located in IFS in the /QIBM/ProdData/OnDemand/config directory. Copy this file into the directory of your choice, such as /QIBM/UserData/OnDemand/config.
- On z/OS, IBM Support will assist you with creating the trace.settings file.
If you are running multiple instances and need a unique trace.settings file for each instance, you can copy the trace.settings file to an instance-specific directory or copy it to a new file with an instance-specific name, which you can then specify in Step 3.
2. Edit the trace.settings file to set the trace parameters. An example of the possible entries in the trace.settings file is shown here:
[TRACE]
TRACE_LEVELS=ALL=3
TRACE_FILE=ARCHIVE.trc
APPEND=1
[TRACE]
TRACE_LEVELS=ALL=3
TRACE_FILE=ARCHIVE.trc
APPEND=1
IBM Support will guide you with regard to setting the TRACE_LEVELS parameter, including which component to trace and which trace level to enable.
Make sure the TRACE_FILE parameter contains a valid file name. The path name is optional. If you omit the path name, the trace facility uses the path you have specified with the ARS_TMP parameter in the ARS.CFG file, or the directory specified in the Temporary File Path field on the Instance tab of the instance's properties in the OnDemand Configurator for Windows. If you include the path name, make sure the path exists. If it does not exist, the server will start but the trace file will not be created.
The trace file that is created is in a binary format and is not human-readable. For this reason, it is recommended that you use a file extension of .trc to distinguish it from other log and text files which are human-readable by default.
The APPEND parameter is optional. If you specify APPEND=0, the trace facility creates a new trace file each time the server is started and renames the existing trace file to include current date and time. Specifying APPEND=1 causes the trace facility to reuse the existing trace file each time the server is started and append new trace output to the end of the file. The default is 0.
3. On all platforms except Windows, edit your Content Manager OnDemand server ARS.CFG file, adding the ARS_TRACE_SETTINGS parameter, and referencing the full path to your trace.settings file. For example, on an AIX V10.5 system, add:
ARS_TRACE_SETTINGS=/opt/IBM/ondemand/V10.5/config/trace.settings
On Windows, the configuration settings are stored in the registry. You can update them by using the OnDemand Configurator. Navigate to the instance's properties, click the Instance tab, check the Enable Trace checkbox, and use the Browse button to identify the location of the trace.settings file.
ARS_TRACE_SETTINGS=/opt/IBM/ondemand/V10.5/config/trace.settings
On Windows, the configuration settings are stored in the registry. You can update them by using the OnDemand Configurator. Navigate to the instance's properties, click the Instance tab, check the Enable Trace checkbox, and use the Browse button to identify the location of the trace.settings file.
Important note: Adding the ARS_TRACE_SETTINGS parameter to the ARS.CFG file or checking the Enable Trace checkbox enables startup trace. Similarly, removing or commenting out the ARS_TRACE_SETTINGS parameter in the ARS.CFG file or unchecking the Enable Trace checkbox disables startup trace and prevents runtime trace.
IBM Support might also ask you to add or update the ARS_SRVR_UPDATE_TRACE parameter in the ARS.CFG file. This parameter is optional. Setting ARS_SRVR_UPDATE_TRACE=0 specifies that the trace facility will use the TRACE_LEVELS values in the trace.settings file for both the startup trace parameters and for the runtime trace parameters instead of using the settings written to the database for the runtime parameters that were specified by using the OnDemand Administrator client. Setting ARS_SRVR_UPDATE_TRACE=1 specifies that the trace facility will use the TRACE_LEVELS values in the trace.settings file only for the startup trace parameters and use what the OnDemand Administrator client wrote to the database for the runtime trace parameters. The default is 1.
4. Enable trace by using the OnDemand Administrator client.
Perform the following steps:
a. Launch the OnDemand Administrator client, log on to your Content Manager OnDemand server, right-click the Content Manager OnDemand server in the left panel, select Trace Parameters, and check Activate System Trace.
Important note: Checking the Activate System Trace checkbox enables runtime trace. Similarly, unchecking the Activate System Trace checkbox disables runtime trace.
b. In the same dialog box under Trace Parameters, enter the component and trace level. IBM Support will guide you with regard to which component to trace and which trace level settings to enable. For example, to trace Error, Warning, Information, and Flow messages for all components, you will be asked to enter ALL=15 for the trace level and click Update. Be careful not to enter TRACE_LEVELS=ALL=15, which is the format of the trace.settings file entry. Simply enter ALL=15.
5. If you modified the trace.settings or ARS.CFG files, then you must restart your Content Manager OnDemand server for the changes to take effect. The startup trace facility begins as soon as you restart the server and uses the trace levels set in the trace.settings file. Once the server is initialized, the runtime trace levels are used unless ARS_SRVR_UPDATE_TRACE=0 is specified in the ARS.CFG file.
6. Re-create the problem that you are being asked to trace. On all platforms except Windows, the trace file is written to the directory specified by the ARS_TMP parameter in the ARS.CFG file or to the path specified on the TRACE_FILE parameter if one is specified. On Windows, the trace file is written to the directory specified in the Temporary File Path field on the Instance tab of the instance's properties in the OnDemand Configurator or to the path specified on the TRACE_FILE parameter if one is specified. The name of the trace file is specified by the TRACE_FILE parameter found in the trace.settings file.
6. Re-create the problem that you are being asked to trace. On all platforms except Windows, the trace file is written to the directory specified by the ARS_TMP parameter in the ARS.CFG file or to the path specified on the TRACE_FILE parameter if one is specified. On Windows, the trace file is written to the directory specified in the Temporary File Path field on the Instance tab of the instance's properties in the OnDemand Configurator or to the path specified on the TRACE_FILE parameter if one is specified. The name of the trace file is specified by the TRACE_FILE parameter found in the trace.settings file.
7. Disable the trace facility. To disable Content Manager OnDemand startup trace, remove or comment out the ARS_TRACE_SETTINGS parameter (all platforms except Windows) or uncheck the Enable Trace checkbox (on Windows) from step 3 and restart your Content Manager OnDemand server. To disable Content Manager OnDemand runtime trace, uncheck Activate System Trace from step 4a by using the OnDemand Administrator client.
8. Send the trace file to IBM Support. Care must be taken when transmitting the file to IBM Support via FTP. The format type must be set to BINARY, otherwise the trace file might become corrupted during the transmission.
Related Information
[{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSEPCD","label":"Content Manager OnDemand for Multiplatforms"},"ARM Category":[{"code":"a8m0z0000001gP1AAI","label":"technote"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"},{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSB2EG","label":"Content Manager OnDemand for i"},"ARM Category":[{"code":"a8m0z0000001gP1AAI","label":"technote"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"},{"Type":"MASTER","Line of Business":{"code":"LOB45","label":"Automation"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSQHWE","label":"Content Manager OnDemand for z\/OS"},"ARM Category":[{"code":"a8m0z0000001gP1AAI","label":"technote"}],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Versions"}]
Was this topic helpful?
Document Information
Modified date:
15 March 2022
UID
swg21330810