Using Clarity Action Trace

Products

Clarity PPM On Premise Clarity PPM SaaS

Issue/Introduction

This article provides instructions on how to use Action Trace for Clarity

Action Tracing is beneficial for troubleshooting certain Clarity issues, including performance related issues (especially slow performance for a certain area/feature in the product).

Environment

Release 13.0 and higher.

Resolution

Steps for Clarity 15.1 and Higher (ALL SUPPORTED VERSIONS):

Enable Action Trace in Resource UI Properties (NEW AND CURRENT VERSIONS) - concise instruction for current versions

1. Update the resource's (user's) "Action Tracing" field to Trace Statements and Save

Screen shot of Action Tracing setting:

Please note that enabling Action tracing on multiple users simultaneously will overwrite the content/trace files.
After enabling Action Tracing on the resource, the user will need to logout and login and then you will find a file called: "app-trace.xml" in <Clarity Home>/logs/.
Tracing expires and reverts back to Trace Off after 5 days.
To gather the actual query results in addition to the SQL statements used in the actions, select: Trace Statements and Results - NOTE: DO NOT use this without explicit request from Support. Only Trace Statements should be used by default unless specifically indicated by Support

Steps for Releases Prior to 15.1 (OLD VERSIONS ONLY - IGNORE THIS IF NOT ON OLD VERSION):

SQLTrace activities are now referred to as 'Action Tracing'. The application will log entries for actions performed in the application when the configuration is set to capture the activities.
Stock configuration of Clarity System Administration (CSA) application provides an entry for the Clarity Administration (admin) user in which Action Trace can be easily turned on by simply changing the Category Priority level from FATAL to Trace or All.
If access is provided, <server>/niku/nu#action:security.logs can be entered from the browser URL.
- Click Logs > Edit Configuration.

The instructions provided here, will allow the Clarity Administrator to execute steps to create separate Action Trace Log files for specific end-users.

Log into Clarity System Administration application (CSA)
Navigate to the Server > Logs > Edit Configuration page (default configuration shown)
Be sure the option 'Detect Log Configuration Changes Automatically' is checked so that when you are updating the page to enable and disable the Action Trace it is effective immediately
Scroll down the page to the 'Appenders' Section : Here you will create a new appender file that will store the Action Trace details
Copy the existing Appender named 'XML' (this pre-existing entry is used for the 'admin' trace)
Edit the newly-created 'XML - copy' Appender line item for a specific user (myuser) - File name = ../logs/trace_myuser.xml > Click 'SAVE' button located at the top or bottom of the page
Now that a separate Appender File name has been created, we can create an entry to turn on Action trace for this user. Scroll up the page to the 'Categories' section.
Click 'ADD CATEGORY' button : this will create a new line item at the end of the Categories list with 'com.niku' as the Category Name
Update this line item with the following details as shown: Other Name, Appender, Priority, Additive

NOTE: Be sure to enter the User Name using the same case-sensitive characters as defined in the Clarity Administration Resource User Name field. In the following example, the user name is using all lower-case characters for 'myuser', which matches the definition in Clarity.
Click 'SAVE' button at the bottom or top of the page > the saved changes will now appear as shown for this line item
Because you set the Priority of the Category to All, a yellow Alert message will appear on the Logs Configuration page. This serves as a reminder to disable the Action Trace later
After performing the Action trace activity, be sure to remove the Category line item or change the Category Priority to FATAL to turn off the Action Trace for this specific user
The log files generated from this configuration will be found in the 'logs' directory on the Clarity application server

NOTE: The following 2 flags should be set to true in order to allow SQL Action Trace to work:

traceEnabled="true" - this parameter the result set and sql query
traceJDBCEnabled="true"

If these values are set to "false" then tracing will not generate. Hence, to enable tracing you would need to either set both of these parameters to "true" or remove both parameters from properties.xml which requires a stop/restart of the Clarity services. Likewise, once the tracing has been completed you would need to stop the services, change the parameter values back to "false" or add the above values back into properties.xml, and then restart the Clarity services.

Additional Information

KB Articles on troubleshooting Action Tracing issues:

The below video will demonstrate the steps to enable SQL trace for CA PPM Versions prior to 15.1:

Clarity - SQL Trace Activation (YouTube)

Action Trace logging in V13 and higher no longer uses the SQLTRACE_ACTIVE trace levels in the CMN_SEC_USERS table as described in technical articles for prior releases. The detail level is now controlled by the logging priority level for the 'trace.server' category. The Debug level provides performance information, query text, parameter values, and resource usage - equivalent to the trace level "4" in the previous versions. The Trace level provides the Debug information plus the result sets, equivalent to trace level "8". Make sure to re-login after each change to a user-specific Action Trace logging configuration.

NOTE: The following 2 flags should be set to true in order to allow SQL Action Trace to work:

traceEnabled="true" - this parameter the result set and sql query
traceJDBCEnabled="true"

If these values are set to "false" then tracing will not generate! Hence, to enable tracing you would need to either set both of these parameters to "true" or remove both parameters from properties.xml which requires a stop/restart of the Clarity services. Likewise, once the tracing has been completed you would need to stop the services, change the parameter values back to "false" or add the above values back into properties.xml, and then restart the Clarity services.

For more information on the configuration fields in this page, reference the Clarity Installation Guide.