Depending on the situation you’re analyzing, you may enable different loggers. Here are some recommendations we have found valuable over the past years doing support for OSLC Connect for Jira.
Prepare your logs with some specific notes
When doing debug sessions, it’s always valuable to easily identify what actions were undertaken when a specific log message appears. The start of the session deserves a specific notice, as would any action that one would perform, e.g. the last click before a given problem appears or the modification of a specific configuration key. This will help review the logs immediately after the session, but also will help with retaining a certain level of understanding weeks on months later.
Since IBM does not offer the same level of features as does Atlassian in their Jira product, we have to resort to using administrator tricks here! Our suggestion for this is to:
Linux
CODE
#!/bin/sh
for i in "${@:2}"
do
echo -ne "\n\n\n**** ${1}\n\n" >> ${i} # mark the nth log file
done
exit
Create the marklogs.sh file inside the logs folder (typically <JazzTeamServer installation dir>/server/liberty/servers/clm/logs then make it executable (using chmod u+x marklogs.sh). You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments:
CODE
./marklogs.sh "Starting the OSLC debug session" ldx.log ldx-internalSso.log
Windows (Powershell)
CODE
$log_mark=$args[0];
for ($i = 1; $i -lt $args.count; $i++) {
$logfile = $args[$i];
Add-Content "$logfile" "`n`n`n*** $log_mark`n`n";
}
Create the marklogs.ps1 file inside the logs folder (typically <JazzTeamServer installation dir>\server\liberty\servers\clm\logs. You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments:
CODE
.\marklogs.ps1 "Starting the OSLC debug session" ldx.log ldx-internalSso.log
Windows (Batch)
CODE
@echo off
setlocal enabledelayedexpansion
set argCount=0
for %%x in (%*) do (
set /A argCount+=1
set "argVec[!argCount!]=%%~x"
)
for /L %%i in (2,1,%argCount%) do (
(echo:& echo:& echo:& (echo *** %~1)& echo:& echo:)>>"!argVec[%%i]!""
)
Create the marklogs.bat file inside the logs folder (typically <JazzTeamServer installation dir>\server\liberty\servers\clm\logs. You can then mark any log file by specifying the comment as the first argument, and every log file you want to impact as subsequent arguments:
CODE
marklogs.bat "Starting the OSLC debug session" ldx.log ldx-internalSso.log
The result will look like this:
CODE
2021-11-05 04:57:51,903 [Default Executor-thread-678099 @@ 04:57 patricia <Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:93.0) Gecko/20100101 Firefox/93.0@10.100.2.223> /ccm/proxy] WARN net.jazz.ajax.service/ProxyOperation - The target https://ulm-jira-7.sodius.cloud:4430/rest/oslc/1.0/rootservices is not local and not registered as a friend
*** Starting the OSLC debug session
<new logs will appear here>
Decide on what to review
Review incoming requests to ELM
You should do that if your OSLC Connect application is experiencing problems interacting with ELM.
Incoming requests are visible in the HTTP access log. This access log is provided by Liberty and can be enabled as described at Jazz.net. Concretely, we recommend that you enable the access log on the targeted endpoint. A good value for the access log format would typically give out the following configuration block to update in the default server.xml:
NONE
<httpEndpoint id="defaultHttpEndpoint"
host="*"
httpPort="9080"
httpsPort="9443" >
<accessLogging filepath="${server.output.dir}/logs/http_defaultEndpoint_access.log"
logFormat='%h %u %t "%r" %s %b Cookie=%C %{User-agent}i %{Referer}i Authorization=%{Authorization}i Accept=%{Accept}i Content-Type=%{content-type}o Set-Cookie=%{set-cookie}o' />
</httpEndpoint>
To better understand the log format and customize it to your needs, you may want to review this article.
For an advanced access log format, you can expand this section.
HTTP headers retained in the following suggested example were taken from here.
CODE
logFormat="'%h' '%u' '%t' '%D' '%r' '%s' '%B' '%m' '%U' '%q' '%a' '%A' '%C' '%{Referer}i' '%{User-Agent}i' '%{Cookie}i' '%{Authorization}o' '%{Set-Cookie}i' '%{oslc_config.context}i' '%{OSLC-Core-Version}i' '%{Content-Length}i' '%{Accept}i' '%{Content-Type}i' '%{If-Match}i' '%{If-Modified-Since}i' '%{X-If-Modified-Since-XSD}i' '%{Forwarded}i' '%{X-Forwarded-For}i' '%{Location}o' '%{Content-Location}o' '%{Content-Disposition}o' '%{eTag}o' '%{x-com-sodius-logout-url}o' '%{x-com-sodius-logout-method}o' '%{X-com-sodius-oauth-redirect-location}o' '%{X-com-ibm-team-repository-web-auth-msg}o' '%{X-Sodius-Resource}o' '%{WWW-Authenticate}o' '%{Last-Modified}o' '%{Access-Control-Allow-Origin}o' '%{Vary}o' '%{Origin}o' '%{X-Frame-Options}o' '%{Content-Security-Policy}o'"
Which gives out the following log:
CODE
'10.100.99.5' '-' '[16/Jun/2020:07:41:36 +0200]' '628158' 'GET /secollab/web/clm/review/67082340-c545-4c86-acd7-7cd1ea2fda08/finalize?oslc_config.context=https:%2F%2Fclm-605.sodius.cloud:9443%2Fsecollab%2Fclm%2Fservices%2Fconfig%2Fstream%2F213e8151-5010-4722-a996-d1f64df4944e HTTP/1.1' '307' '0' 'GET' '/secollab/web/clm/review/67082340-c545-4c86-acd7-7cd1ea2fda08/finalize' '?oslc_config.context=https:%2F%2Fclm-605.sodius.cloud:9443%2Fsecollab%2Fclm%2Fservices%2Fconfig%2Fstream%2F213e8151-5010-4722-a996-d1f64df4944e' '10.100.99.5' '10.100.2.102' 'JSESSIONID:0000Voxgdm9kVpWRykb_1CGRSVN:5c53c125-1133-4b4d-ba65-e9e16fe6471e LtpaToken2:fjhBhxSwdPdirZzMIvZrff57j4FlS+lk/AtmCinLpdV/MER1cRHFvfAU2yrQF/YbxHEEZOKBDrrgN2BDEuOMkgVJBIjBOmM7pnioeXweRou7h9RnMMYdeCy2ePd02Ix8n8i2pUZyrfwd55apC6rQLsWIZFWjJN9lpRZrrIq5Ok3vsKsIzfv9idGIJpFhOUx6jTQuqfVOpYX4wpJ+jUuHYTDu6slRDe9pQBlw7OT5qWn8TW59WeKDVXrtFbWRo7POvNEfH1uEd4Ec3RBc5bxihsWPnKPL3eGGmLuFsaxatkMNgJkCKd5HUwAgz3YGRXeb' '-' 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:77.0) Gecko/20100101 Firefox/77.0' 'JSESSIONID=0000Voxgdm9kVpWRykb_1CGRSVN:5c53c125-1133-4b4d-ba65-e9e16fe6471e; LtpaToken2=fjhBhxSwdPdirZzMIvZrff57j4FlS+lk/AtmCinLpdV/MER1cRHFvfAU2yrQF/YbxHEEZOKBDrrgN2BDEuOMkgVJBIjBOmM7pnioeXweRou7h9RnMMYdeCy2ePd02Ix8n8i2pUZyrfwd55apC6rQLsWIZFWjJN9lpRZrrIq5Ok3vsKsIzfv9idGIJpFhOUx6jTQuqfVOpYX4wpJ+jUuHYTDu6slRDe9pQBlw7OT5qWn8TW59WeKDVXrtFbWRo7POvNEfH1uEd4Ec3RBc5bxihsWPnKPL3eGGmLuFsaxatkMNgJkCKd5HUwAgz3YGRXeb' '-' '-' '-' '-' 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8' '-' '-' '-' '-' '-' '-' 'https://clm-605.sodius.cloud:9443/ccm/oauth-authorize?oauth_token=fdfb3353c8ae4387880b5e63aa6095f4' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-' '-'
Log parameters used in this recommandation are:
%h Remote host
%u Remote user according to the WebSphere Application Server specific $WSRU header
%t NCSA format of the start time of the request
%D The elapsed time of the request - millisecond accuracy, microsecond precision
%r First line of the request
%s Status code of the response
%B Response size in bytes excluding headers. 0 is printed instead of - if no value is found.
%m Request method
%U URL Path, not including the query string
%q Output the query string with any password escaped
%a Remote IP address
%A Local IP address
%C Cookie
Retained HTTP request headers are:
Retained HTTP response headers are:
Location
Content-Location
Content-Disposition
eTag
x-com-sodius-logout-url
x-com-sodius-logout-method
X-com-sodius-oauth-redirect-location
X-com-ibm-team-repository-web-auth-msg
X-Sodius-Resource
WWW-Authenticate
Last-Modified
Access-Control-Allow-Origin
Vary
Origin
X-Frame-Options
Content-Security-Policy
Downstream-Auth
To make use of the output in Excel:
CODE
'Remote host' 'Remote user' 'Request start time' 'Request log time' 'Request duration' 'Request 1st line' 'Status' 'Response size' 'Method' 'URL' 'Query string' 'Cross Component Tracing (XCT) Context ID' 'Remote IP addr' 'Local IP addr' 'Cookie' 'i_Referer' 'i_User-Agent' 'i_Authorization' 'i_Cookie' 'i_Set-Cookie' 'i_oslc_config.context' 'i_OSLC-Core-Version' 'i_Content-Length' 'i_Accept' 'i_Content-Type' 'i_If-Match' 'i_If-Modified-Since' 'i_X-If-Modified-Since-XSD' 'i_Forwarded' 'i_X-Forwarded-For' 'o_Location' 'o_Content-Location' 'o_Content-Disposition' 'o_eTag' 'o_x-com-sodius-logout-url' 'o_x-com-sodius-logout-method' 'o_X-com-sodius-oauth-redirect-location' 'o_X-com-ibm-team-repository-web-auth-msg' 'o_X-Sodius-Resource' 'o_WWW-Authenticate' 'o_Last-Modified' 'o_Access-Control-Allow-Origin' 'o_Vary' 'o_Origin' 'o_X-Frame-Options' 'o_Content-Security-Policy'
if the copied header or lines are not automatically expanded to columns
Select column Accept
In the "Data" banner, click the button called "Text to Column"
Choose "delimited", then Next
Review outgoing requests sent by ELM, or the ELM processing
Depending on the applications installed, there can be 2 ways to set up additional application logs
For RM…
Navigate to https://server:9443/rm/admin#action=com.ibm.rdm.fronting.server.web.logging.
Click on Configure Loggers, then find the logger you want to change and click on the log level you want to set.
For any ELM application…
On Jazz server, edit the file at <JazzTeamServer installation dir>\server\conf\<app>\log4j.properties
Update the content of the file (see examples below) and save it
Reload the logging settings:
For all apps but LQE/LDX, navigate in a browser to: https://server:9443/<app>/admin?internal=true#action=com.ibm.team.repository.admin.reloadLoggingSettings
For LQE/LDX, go to https://server:9443/lqe/web/admin/data-sources → Advanced Properties
Click the Reload Log Settings button
Download the log files as explained below
Reviewing outgoing requests
To debug ELM outgoing requests, add the following lines in Log4j configuration:
CODE
log4j.logger.org.apache.http=DEBUG
Reviewing ELM processing
CODE
log4j.logger.com.ibm.rdm.fronting.server.services.discoveredlinks=DEBUG
log4j.logger.com.ibm.rdm.fronting.server.services.linkindexprovider=DEBUG
log4j.logger.com.ibm.team.links=DEBUG
CODE
log4j.logger.com.ibm.team.integration.lqe.lib.trsparser.ITRS=TRACE
Where to review
You will always review the file corresponding to the application where you have enabled specific logs. The below table lists most of them.
Log File | Name (v6) | Name (v7) |
|---|
ccm.log | RTC Rational Team Concert | EWM Engineering Workflow Management |
rm.log | DNG Rational DOORS Next Generation | DOORS Next Engineering Requirements Management DOORS Next |
qm.log | RQM Rational Quality Manager | ETM Engineering Test Management |
gc.log | GCM Global Configuration Manager | GCM Global Configuration Manager |
ldx.log | LDX Link Indexer | LDX Link Indexer |
lqe.log | LQE Lifecycle Query Engine | LQE Lifecycle Query Engine |
relm.log | RELM Rational Engineering Lifecycle Management | EI Engineering Insight |
rs.log | RS Report Builder | RS Report Builder |
Finishing the debug session
Restore your system’s previous logging features
You definitely want to mark your logs using the marklogs.sh script, e.g.
CODE
./marklogs.sh "Completed OSLC debug session" ldx.log ldx-internalSso.log
Then to avoid flooding your system with logs, you also want to undo the changes you have made during the debug session. This can be done by commenting out any line added in the log4j.properties files, prefixing them with a #.
Retrieving Jazz' server logs
From the RM admin page
Navigate to https://server:9443/rm/admin#action=com.ibm.rdm.fronting.server.web.logging.
From this page, you can either download or display in the browser any log file from the Jazz server.
From the Jazz server
Open the following file to see the log entries:
<JazzTeamServer installation dir>/server/liberty/servers/clm/logs/<app>.log
There may be a number of log files ex. rm.log, rm.log1, rm.log2 etc. because when a log file becomes full a new one is created.
We suggest attaching the log file(s) to a Jira ticket on our customer support portal if you think these provide insight into the problem you have identified, or if they were requested.
