Author: Amanda Jennewein
Date: December 6, 2023
Environmental details: Self-Hosted
This document is a companion piece to the Gathering Empirical Data for Troubleshooting article.
The support bundle, a feature available in versions of Jama 8.0 +, is a simple way for a customer to create a comprehensive set of information for troubleshooting purposes. A support bundle includes all the logs we'd traditionally requested in Support. It also contains records for Docker and Replicated, detailed system information, and all of the configuration and environment variables used in a customer's environment.
Generating a Support Bundle
There are two ways to generate a support bundle. The first method uses the Replicated web portal user interface (UI), the most commonly used method. However, there may be situations where the UI is unavailable; in that case, the second method is to use the command-line interface (CLI). This is an excellent alternative when the UI is not an option.
Using the UI
Using the UI is the easiest way to generate a support bundle and is the method you will use most often.
1. Log into the Replicated portal for your Jama instance. This will be located at https://<IP or hostname>:8800
2. Select the Support Tab.
3. Select the Download Support Bundle button to download the bundle to your local machine.
Using the CLI
There are times when the Replicated UI is not available. In those cases, users must use the command line (CLI).
Support Bundle Contents - Jama 8 Architecture
The support bundle has a lot of information and can be intimidating at first. Most troubleshooting happens in just a few of the logs, though, and if you understand all the moving parts involved, it will help you navigate the contents of the support bundle.
Note: This article will not describe every file in the bundle but will call out the files of most significant interest.
Here are the different parts of the Jama 8.0 architecture:
- Replicated Server - The cloudy image is the servers the company Replicated is running. The local Replicated instance checks with the Replicated Server for updates (Replicated and Jama), to download Jama during installation, etc. It's worth noting that the support bundle will not retrieve any information or logs from the Replicated Server.
- Replicated - This is the local instance of Replicated daemon. It is responsible for all of the operations of Replicated.
- UI - This is the local Replicated web console.
- Agent - Agent handles the communication between Replicated, the UI, and our Docker containers.
- Jama - This is what we're used to thinking of as Jama, although there are more services than there used to be. This includes our five containers: jamacore, tenantmanager, elasticsearch, search, and nginx.
From that, you may be looking for things relating to Replicated, the UI, the agent, and Jama/Docker.
The Folder/File structure
At the top level, you see two folders and two files:
- /daemon - This folder contains information about the host, Docker containers' status, and the Replicated processes.
- /scheduler - After drilling down, this folder's logs are all about Jama's Docker containers. It includes Docker inspect, stderr, stdout, and Jama's logs. The information in this folder only pertains to Jama. There will be one sub-folder per Docker container.
- license.txt - This includes your license's basic information, including your current version of Jama and your license's expiration date.
Let's break that down further. Here's a list of the sub-folders, their contents, and which files should be most interesting to you.:
/daemon: - Information About Your Host, Replicated, and Docker
- /docker/docker_info.json - This contains an overview of the state of your docker containers. You should see at least five running and one stopped. The tenant manager container stops once it completes getting Jamacore up. If the Docker containers are not functioning correctly, please check the following file.
- /docker/docker_ps_a.json - This has a breakdown of each container and its state. If a container is down, knowing which one is down is helpful.
- /replicated/replicated.log - The uber-replicated log of errors internal to Replicated. If you are experiencing an error on the Replicated level, this is the place to look.
/scheduler/container: - Information About Your Jama Containers
- /jamacore-<container_id>/files/var/log/tomcat/contour - These folders hold most of the logs we use to troubleshoot. This section will only cover a few of the primary records we use in this folder, but it will be good to look through all the logs here if you are doing a thorough search.
- contour.log - This is the first place to start looking when experiencing problems in Jama Connect®. This is a great starting point for troubleshooting as it logs a majority of information.
- contour-api.log - Contains errors and logs relevant to the API
- contour-c3p0.log(pre 8.56) / contour-datasource.log(post 8.56) - These logs are related to the Java connection pool that manages our database connections.
- contour-dwr.log - These are logs associated to the UI making calls to the server via DWR (DWR is the tech used to communicate to the backend along with a REST API).
- /jamanginx-<container_id>/files/var/log/nginx/error.log - The nginx container is a proxy server for the application that functions outside its container. The error.log file collects logs when that proxy server receives instructions it's unable to follow or traffic that it's unable to route.
- /search-<container_id>/files/logs/jamasearch.log - This includes any activities and errors that may be happening in the search service.
- Gathering Empirical Data for Troubleshooting
- You can find information on how to generate the Support bundle from the command line here.