Overview Of Cognos Analytics Jupyter Troubleshooting Process

What we are trying to do is to verify all 3 components are in communication with each other.

• The Cognos Gateway.
• The Cognos Application Tier.
• The Jupyter Server.

The Key takeaway from this document is that the syntax needs to be EXACTLY the same across the entire environment. Subsequently all components need to be able to telnet to each other. Finally all must be either (All SSL) or (All non-SSL).

For any WebSocket issue you will need up to 7 things to understand all the variables at play.

• The config.conf from within Jupyter
• This command from the docker server (only if Jupyter contains $hostname) docker inspect ca_jupyter_hub | grep HOST > HOST.txt
• Screenshot of fyre.ibm.com:8000 directly in the browser.
• The exact contents of what was placed in “Navigate to Configuration > System > Environment (tab)” (screenshots for proof are always good)
• The cogstartup.xml from within cognos
• If using a gateway, it is helpful to have the web.config file(s).
  1. <Install Directory>/webcontent/bi --> web.config
• F12 Network trace is always helpful.

What we are looking for in each file

1 – config.conf

First take the config.conf and examine the file to see what was entered in the hostname variable. This will be the variable Jupyter uses to start up.

• The HOST_NAME will tell you the hostname being used to start up (more below)
• The HOST_PORT will tell you the port Jupyter will be working on

If anything within the SSL section is filled out at all, we will be expecting a SSL connection. If it is blank, a non SSL connection is expected.

• PROXY_CERTIFICATE_FILE_PATH:
• PROXY_KEY_FILE_PATH:
• CERTIFICATES_DIRECTORY_PATH:

2 - ca_jupyter_hub | grep HOST > HOST.txt

If HOST_NAME was left default it will be ($hostname), which is fine, but it might not start up under the hostname you are expecting. If you have $hostname its critical we check the output of the docker inspect

• docker inspect ca_jupyter_hub | grep HOST > HOST.txt

This will feed you something like this:

• ws://Jupyter1.fyre.ibm.com:8000

The Key takeaways here are:

• The WS or WSS will tell is if Jupyter is expecting an SSL or non SSL connection
• The server name or IP will tell you what needs to be accessible to/from other servers
• The Port number will tell you what port needs to be accessible.

If the hostname Jupyter starts up as, is not the one you intended or expected. Modify the Host_name variable within the config.conf and rebuild using the ./build script.

3 - Screenshot of Jupyter1.fyre.ibm.com:8000 directly in the browser.

We need screenshots of the browser directly. You will hopefully get the following error message. This is actually not an error message but the default splash screen for Jupyter. It indicates to us that your browser can successfully connect to the Jupyter Server.

404: Not Found – Jupyter has lots of moods, but this is not one…

Please see the following defect regarding changes to this splash screen in versions released after June 2020.

PH25889 "404 : NOT FOUND JUPYTER HAS LOTS OF MOONS" MESSAGE IS CONFUSING AND ACTUALLY MEANS A SUCCESSFUL CONNECTION HAS BEEN MADE.

https://www.ibm.com/support/pages/apar/PH25889

If you receive any other message, your browser cannot connect to the Jupyter server. Verify the Jupyter containers are running and contact your network admin to rectify the issue.

4 - The exact contents of what was placed in “Navigate to Configuration > System > Environment (tab)”

Here we just want to make sure we do not have a trailing slash. This server name and port number combination should mirror exactly what was within STEP 2 - docker inspect ca_jupyter_hub | grep HOST > HOST.txt

In my case:

http://jupyter1.fyre.ibm.com:8000

Be sure not to include a trailing slash here.

If you do not have the server name and port number combination that mirrors what you have in STEP2 please rectify this.

5- The cogstartup.xml from within cognos

Here we want to look at and verify 2 elements. The Gateway URI and the Dispatcher URI for external Applications.

• The Gateway URI will need to be one of the following. Syntax is important. If it is not of the following, Jupyter will not work. You will need to
  • http:webserver.fqdn.com:80/aliasname/bi/v1/disp
  • https:webserver.fqdn.com:443/aliasname/bi/v1/disp
  • http:APPSERVER.fqdn.com:PORT /bi/v1/disp
  • https:APPSERVER.fqdn.com:PORT /bi/v1/disp
• The Dispatcher URI for external applications will need to be of either Syntax
  • http:APPSERVER.fqdn.com:PORT/ bi/v1/disp
  • https:APPSERVER.fqdn.com:PORT/ bi/v1/disp

The Server and port of each entry should be accessible via telnet from Jupyter. If they are not accessible, contact your network administrator to rectify this situation (more below).

6 - If using a gateway the web.config files.

The first question to ask: Are we using a Gateway? You can tell this from the Gateway URI, if it is using port 443 or 80)  you are indeed! You should then collect the following files:

1. <Install Directory>/webcontent/bi --> web.config

Within the web.config file you will note that the IIS Jupyter rule should look like. This server name and port number combination should mirror exactly what was within STEP 2 - docker inspect ca_jupyter_hub | grep HOST > HOST.txt. If they do not match, correct this within IIS Rules. (Blog To-Be Published under this topic).

                <rule name="Jupyter Server" enabled="true" stopProcessing="true">

                    <match url="v1/jupyter/(user/[^/]*)/(api/kernels/[^/]+/channels)" />

                    <action type="Rewrite" url="http://jupyter1.fyre.ibm.com:8000/bi/v1/jupyter/{R:1}/{R:2}" />

                </rule>

If using Apache these steps will be different, but the crux of the issue would be to make sure you are pointed to the correct server defined in Step 2.

7- F12 Network trace is always helpful.

More information can be found here: https://www.ibm.com/support/pages/troubleshoot-enabling-browser-trace

Checking the network trace WebSocket tab is always helpful.

Select the WS tab (websocket)

Double click on any red WS entries to pull up more information on it. This should indicate the Host and Origin (which should be the Cognos server and Jupyter server respectively).

Final Testing

Now that we have all this information and we know it is consistent across, we can begin testing the network connections:

On the Jupyter Box, Telnet from within the hub  container to the Cognos server and the Cognos Gateway.

1. docker exec -it -u 0 ca_jupyter_hub bash
2. apt-get install telnet
3. telnet <Applicationserver.FQDN.com as shown in Dispatcher URI for External Applications> 9300
   • telnet CognosAppServerProd.ibm.com 9300
4. telnet <Webserver.FQDN.com as shown in Gateway URI> 80 (or 443)
   • telnet CognosWebServerProd.ibm.com 80

On the Cognos Application Server Telnet to the Jupyter Box.

1. telnet <Jupyter server exactly as shown in step 2> 8000
   • telnet jupyter1.ibm.com 8000

On the Cognos Application Server Telnet to the Jupyter Box.

1. telnet <Jupyter server exactly as shown in step 2> 8000
   • telnet jupyter1.ibm.com 8000

If any of these tests fail contact your network administrator to make sure those server names and port numbers are accessible.