Configuring XCT with wsadmin scripting

You can configure Cross-Component Trace (XCT) using wsadmin scripting. Use the examples in this topic as a guide to build your own wsadmin scripts.

About this task

XCT annotates the logs so that log entries that are related to a request that is serviced by more than one thread, process, or even server are identified as belonging to the same unit of work. You can configure XCT using the administrative console, or using wsadmin scripting. The examples in this topic show how to configure XCT using wsadmin. If you complete this task using the deployment manager, then you might need to synchronize the node agent on the target node and restart the server before configuration changes take effect.

Table 1. Variable Names . The table applies to all examples in this topic. All examples use the Jython scripting language.
Variable	Description
`myCell`	The name of the cell
`myNode`	The host name of the node
`myServer`	The name of the server

Procedure

Use the AdminConfig object to configure XCT.

Changes you make using the AdminConfig object take effect the next time you start the server.
1. Enable XCT for the server.
  By default, XCT is disabled for the server. The following example shows how to enable XCT for the server when your server is using High Performance Extensible Logging (HPEL) log and trace mode. Specify RASLoggingService instead of HighPerformanceExtensibleLogging when your server is using basic log and trace mode. Specify false instead of true to disable XCT.
```
# get rid of existing property if already present
configId = AdminConfig.getid("/Cell:myCell/Node:myNode
 /Server:myServer/HighPerformanceExtensibleLogging:
 /Property:com.ibm.websphere.logging.enableCorrelation")if (len(configId) > 0):
    AdminConfig.remove(configId) 
# add new property
LoggingService = AdminConfig.getid("/Cell:myCell/Node:myNode
/Server:myServer/HighPerformanceExtensibleLogging:/")
AdminConfig.create("Property", LoggingService, [["name", "com.ibm.websphere.logging.enableCorrelation"],["value", "true"]])

AdminConfig.save()
```
2. Change the log setting for XCT .
  By default, the XCT log setting includes request IDs in log and trace files. The following example shows how to make XCT both include request IDs in log and trace files and log XCT log records. Specify REQUEST ID instead of LOG to make XCT only include request IDs in log and trace files. Specify DATA_SNAPSHOT instead of LOG to make XCT include request IDs in log and trace files, log XCT log records, and capture data snapshots. Specify RASLoggingService instead of HighPerformanceExtensibleLogging when your server is using basic log and trace mode.
```
# get rid of existing property if already present
configId = AdminConfig.getid("/Cell:myCell/Node:myNode
/Server:myServer/HighPerformanceExtensibleLogging:/Property:com.ibm.websphere
 .logging.correlationLevel") if (len(configId) > 0): AdminConfig.remove(configId)
# add new property
LoggingService = AdminConfig.getid("/Cell:myCell/Node:myNode
Server:myServer/HighPerformanceExtensibleLogging:/")
AdminConfig.create("Property", LoggingService, [["name", "com.ibm.websphere.logging.correlationLevel"],["value", "LOG"]])

AdminConfig.save()
```
  Best practices:
  - Enable XCT to include request IDs in log and trace files when you want to see which log and trace entries, in all threads and application server processes, are related to the same request. Request IDs are only recorded when using HPEL log and trace mode and can be seen or used for filtering using the logViewer command.
  - Enable XCT to create correlation log records when you want to log how requests branch between threads and processes, and see extra information about each request. Enabling XCT to create correlation log records might have a significant performance impact on your system, so is best suited to test and development environments.
  - Enable XCT to capture data snapshots when you want to store entire request and response bodies to the file system. Enabling XCT to capture data snapshots might have a significant performance impact on your system, so is best suited to test and development environments. XCT captures data snapshots for message requests and responses handled by the SIBus.
  Avoid trouble: Data snapshots are captured and written to the $SERVER_LOG_ROOT/snapdata directory. The application server does not automatically clean up files from this directory. You will need to delete the files from this directory periodically when data snapshot capturing is enabled. Data snapshots store entire request and response contents and may include sensitive information. This option might not be appropriate for use in production environments.
Use the AdminControl object to configure XCT.
Changes you make using the AdminControl object take effect immediately.
1. Enable XCT for the server.
  By default, XCT is disabled for the server. The following example shows how to enable XCT for the server when your server is using HPEL log and trace mode. Ensure the server is running and specify RasLoggingService instead of HPELControlService when your server is using basic log and trace mode. Specify false instead of true to disable XCT.
```
LoggingMBean = AdminControl.queryNames('cell=myCell,node=myNode,
type=HPELControlService,process=myServer,*')
AdminControl.setAttribute(LoggingMBean, "correlationEnabled", "true")
```
2. Change the log setting for XCT .
  By default, the XCT log setting includes request IDs in log and trace files. The following example shows how to make XCT both include request IDs in log and trace files and log XCT log records. Specify REQUEST ID instead of LOG to make XCT only include request IDs in log and trace files. Specify DATA_SNAPSHOT instead of LOG to make XCT include request IDs in log and trace files, log XCT log records, and capture data snapshots. Ensure the server is running and specify RasLoggingService instead of HPELControlService when your server is using basic log and trace mode.
```
LoggingMBean = AdminControl.queryNames('cell=myCell,node=myNode,type=HPELControlService,process=myServer,*')
AdminControl.setAttribute(LoggingMBean, "xctLevel", "LOG")
```
  Best practices:
  - Enable XCT to include request IDs in log and trace files when you want to see which log and trace entries, in all threads and application server processes, are related to the same request. Request IDs are only recorded when using HPEL log and trace mode and can be seen or used for filtering using the logViewer command.
  - Enable XCT to create correlation log records when you want to log how requests branch between threads and processes, and see extra information about each request. Enabling XCT to create correlation log records might have a significant performance impact on your system, so is best suited to test and development environments.
  - Enable XCT to capture data snapshots when you want to store entire request and response bodies to the file system. Enabling XCT to capture data snapshots might have a significant performance impact on your system, so is best suited to test and development environments. XCT captures data snapshots for message requests and responses handled by the SIBus.
  Avoid trouble: Data snapshots are captured and written to the $SERVER_LOG_ROOT/snapdata directory. The application server does not automatically clean up files from this directory. You will need to delete the files from this directory periodically when data snapshot capturing is enabled. Data snapshots store entire request and response contents and may include sensitive information. This option might not be appropriate for use in production environments.

Results

XCT is now configured. If you made changes with the AdminConfig command, restart the server to make the changes take effect.