This document is intended to provide a troubleshooting methodology which incorporates publicly available utilities to diagnose and resolve an issue identified within a specific use case. The use case will be presented as a scenario where an IBM Cognos Support Analyst is working with a client to diagnose and solve a particular issue.
The utilities mentioned in this document can be found at http://www.ibm.com/software/data/support/cognos_sdk.html
Although the troubleshooting approach outlined is not IBM Cognos BI version specific, some of the diagnostic utilities used are. The version of the utility to be downloaded will be specific to the IBM Cognos BI version that is experiencing the issue.
Use Case Description
In this particular scenario, a support analyst is presented with a situation where a particular IBM Cognos Report Studio list report only returns the expected Chinese data in two out of three separate executions. During the execution where the Chinese data does not return as expected, the user is presented with and empty list object.
Troubleshooting the Use Case
As with troubleshooting any use case, a set of basic information needs to be collected in order to further clarify the environment and the issue at hand. In this particular use case, the following information was provided by the client when logging the initial PMR with support.
- IBM Cognos version: 8.4.1
- Operating System: Windows 2003
- Query Database: Oracle 10
During the initial conversation with the client, the support analyst asks the client to explain the current architecture of the IBM Cognos 8 application deployed at their site. The client responds to this question with “It’s a distributed install, but I don’t know exactly what is located where”.
Further Clarifying the IBM Cognos 8 Architecture
Since the client does not know the details about their IBM Cognos 8 architecture, it will be up to the support analyst to determine the actual IBM Cognos 8 architecture.
The support analyst decides to use the IBM Cognos Architecture Diagram Tool located at the following URL, http://www.ibm.com/support/docview.wss?uid=swg24026693
This particular tool uses the cogstartup.xml file to connect to a dispatcher in the distributed environment. That dispatcher is then used to connect to the other registered dispatchers. The result of this is a useable and accurate diagram of the existing IBM Cognos 8 deployment. The client uses the tool’s Take Screen Capture feature and sends the support analyst the resulting .JPG image file.
Upon receiving the IBM Cognos 8 architecture .JPG file, the support analyst notices that the actual environment consists of the following:
- 1 IBM Cognos Gateway
- 3 IBM Cognos Report Servers
- 2 IBM Cognos Content Manager Servers
- 1 Oracle Content Store
As this environment contains three IBM Cognos BI Application Tiers, the support analyst makes the assumption that the intermittent nature of the issue is actually caused by the round robin IBM Cognos Report Server routing mechanism which routes the report execution request to a separate IBM Cognos Report Server each time the report is executed. This could mean that one of the three servers may be the cause. The next step would be to take a look at the cogserver.log file on each of the three IBM Cognos Report Servers.
Analysing the cogserver.log File
The client has access to physical logs directory on each of the three IBM Cognos Report Servers and remembers that this particular scenario was reproduced late one evening two days prior to the current date.
The support analyst decides to use the IBM Cognos From Log Errors to Technotes Utility located at the following URL, http://www.ibm.com/support/docview.wss?uid=swg24028415
This tool individually loads the cogserver.log file and displays all the errors within a given date range. The client is then able to double click any of the error messages to automatically search the online IBM Technotes for a solution.
The support analyst steps the client through the loading and filtering of each of the three cogserver.log files. Unfortunately there are no errors listed for any report executions during the client’s specified timeframe. After thinking about it further, the support analyst determines that since the report executes successful even when it returns no Chinese data, the IBM Cognos Report Server does not record this as an error within the log file. The support analyst will need to take another approach for determining which of the three IBM Cognos Report Servers is not returning data for this particular report.
Narrowing Down the Offending IBM Cognos Report Server
By default there is no way to automatically test a report against a specific IBM Cognos Report Server so the support analyst steps the client through the disabling of two IBM Cognos Report Servers at a time in an attempt to isolate the problematic IBM Cognos Report Server.
As a result of this isolation testing, the support analyst has identified that if the report executes on the second IBM Cognos Report Server, no Chinese data is returned. If the report is executed on the first or third IBM Cognos Report Server, the report returns the Chinese data as expected. The support analyst’s next step is to determine the differences between a working IBM Cognos Report Server and a non-working one.
Comparing a Working and Non-Working IBM Cognos Report Server
The support analyst decides to start at comparing the differences between the two actual systems the IBM Cognos Report Servers are installed on. In order to do this, the support analyst uses the System Overview Diagnostic located at, http://www.ibm.com/support/docview.wss?uid=swg24020682
This utility obtains such system information as computer name, operating system version and environment variables. After stepping the client through running this utility on the two systems, the client sends in the resulting log files to the support analyst.
Upon receiving the files, the support analyst uses a third party compare utility to identify environmental differences between the two systems. Although there are a few expected differences, the support analyst notices a potential lead within the system environment variables. The IBM Cognos Report Server that returns the Chinese data has the Oracle NLS_LANG environment variable set, whereas the IBM Cognos Report Server that does not return the Chinese data does not have this variable set.
Delivering the Findings
The support analyst takes up contact with the client to discuss the environment variable differences. The client agrees to set the Oracle NLS_LANG environment variable on the IBM Cognos Report Server that does not return the Chinese data. Upon the recycling the IBM Cognos Report Server service, the client reports back that the IBM Cognos Report Studio report now consistently returns the Chinese data regardless of the execution frequency.