- 1 Troubleshooting
- 1.1 Container startup logic
- 1.2 Out of Memory error in log when docker-compose -f docker-compose.yml up is executed on Windows
- 1.3 Port error when compose runs on Windows
- 1.4 Genesys CX Insights fails after restart
- 1.5 Container Diagnostics
- 1.6 Generating logs
- 1.7 Kubernetes Inspection
- 1.8 MicroStrategy resources
- For the terms master/slave, Genesys uses “primary” and “secondary” or “primary” and “replica,” with exceptions for their use in third-party commands.
- For the terms blacklist/whitelist, Genesys uses blocklist/allowlist.
- For the term master, when used on its own, Genesys uses main wherever possible.
This page provides some common troubleshooting tips. Many topics on this page require advanced knowledge. For more information or assistance, talk to your Genesys representative, and see the links at the bottom of this page.
Container startup logic
This section describes the general logic of GCXI startup. Understanding this process can help you to troubleshoot problems.
You execute this job when GCXI is first installed, at which time it:
- creates GCXI service objects in the specified database server: meta / history databases and logins.
- loads gcxi data (initial Projects) into newly created databases.
Once gcxi-init completes, we expect that the Microstrategy metadata database (the "meta db") has been created. You can perform the following actions to verify that this is the case:
- Check the gcxi-init logs to ensure that the Microstrategy metadata database has been created without error.
- Check DB Server to ensure that the meta database is available.
Main gcxi container startup
Each time the gcxi container starts, it:
- Checks the environment variables and default values to determine the MicroStrategy Administrator password, and optionally changes the password.
- Starts MicroStrategy server inside the container (a valid meta db is required for MicroStrategy to start properly).
- If you encounter a problem at this stage, check the following:
- if MSTR server fails to start immediately, ensure that the meta db is available.
- if MSTR server fails to start after a delay of about 3 minutes, and exits with the error Failed to start MSTR server!, check sysctls / shared memory settings on the host.
- Runs Command Manager (a Microstrategy client tool) using the MicroStrategy Administrator account and password, and executes the following commands in Command Manager:
LIST ALL DBLOGINS;
LIST ALL DBCONNECTIONS;
LIST ALL DBINSTANCES;
- If these commands fail, ensure that Command Manager is able to log in to the MicroStrategy server (ensure that a valid MicroStrategy Administrator password was provided in step 1).
- Creates DSNs (MicroStrategy connectivity objects), which are used to connect to Genesys Info Mart and other data sources. The DSNs are created based on the container DSNDEF* environment variable.
- If the value of the environment variable GCXI_VERSION is later than the current GCXI release number, an upgrade procedure starts. This one-time task can take up to 30 minutes to complete.
- Performs other MicroStrategy server configurations (some are executed only by a PRIMARY container).
- Configures and starts Tomcat.
Out of Memory error in log when docker-compose -f docker-compose.yml up is executed on Windows
When starting GCXI on Windows, an error can appear if there is not sufficient memory configured for the virtual machine. Resolve this as follows:
- Open Hyper-V Manager.
- Open the Settings of your virtual machine, and navigate to the section Hardware > Memory.
- Select the option Enable Dynamic Memory.
- In the Windows system tray, access the Docker context menu, and open Settings of Docker Desktop “Settings”.
- In the section Resources > Advanced, increase the allocated memory, and save your changes.
Port error when compose runs on Windows
The following error can appear when you start Docker under Windows:
>docker-compose -f docker-compose.yml up <…> ERROR: for gcxi-0 Cannot start service gcxi-0: Ports are not available: listen tcp 0.0.0.0:8080: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted. ERROR: Encountered errors while bringing up the project.
This indicates that the port 8080 is in use. To resolve this issue:
- Open the docker-compose.yml file for editing.
- Change the port mapping as follows: edit the line 8080:8080, changing the first value to <unused_ port_in_windows>:8080”, where <unused_ port_in_windows> is an unused port, for example 8280:8080. If you remap this port, be sure to use the new port value when accessing MicroStrategy web interface.
Genesys CX Insights fails after restart
If Genesys CX Insights fails after restarting, one possible cause is a missing/disabled Project, which prevents the GCXI container from starting. Check to ensure that required Projects in the meta database are not in a disabled state:
- Open MicroStrategy Developer.
- Right-click the server name, and select Configure MicroStrategy Intelligence Server.
- In the Project > General section, ensure that check boxes are selected next to required Project names.
If the GCXI container fails on startup, and the reason for the failure is not immediately evident, Genesys recommends that you set the following debugging variables, and re-run the GCXI main container:
- This provides super-extended logging, which is helpful in many scenarios.
- WarningWarning: all passwords are visible in container logs. Genesys recommends that you do not share this log with Customer Care, or any other party, unless you have first removed all sensitive information, such as passwords, from the log file.
- This provides more information in scenarios where the container does not exit on error and continues to run.
If you need assistance from Genesys, you may be asked to provide logging output. At a minimum, provide the logs, saving each output to a separate file with a name that clearly identifies each one. Note that this example is for Kubernetes; if you use a container engine other than Docker, use corresponding commands for that engine:
## general docker and k8s inspection kubectl version docker version docker info docker images service docker status ## kubernetes objects # please provide the FULL log kubectl log <gcxi_master_pod> kubectl get pod --all-namespaces -o wide kubectl get node -o wide kubectl get events --all-namespaces kubectl get job -o wide kubectl get cm gcxi-config -o yaml kubectl get job gcxi-init -o yaml kubectl get deploy gcxi-master -o yaml kubectl get pod <gcxi_master_pod> -o yaml # is containerized postgres used kubectl log <gcxi_postgres_pod> kubectl get pod <gcxi_postgres_pod> -o yaml # if gcxi-init job instance still exists kubectl log <gcxi_init_pod> kubectl get pod <gcxi_init_pod> -o yaml ## linux info hostnamectl free -h df -h sestatus ## sysctls sysctl kernel.sem sysctl net.bridge sysctl vm
If you suspect that Kubertnetes might be the source of a problem, see the document https://learnk8s.io/troubleshooting-deployments, which provides a troubleshooting flow-chart to guide you through troubleshooting Kubernetes in your deployment.
This section provides links that are useful when you are performing troubleshooting. The URLs in the following table point to the latest page on the MicroStrategy documentation site. If the documentation page that loads is more recent than your installed release, you can modify the URL by replacing Current with a specific release number.
|System Settings / IPC Requirements||https://www2.microstrategy.com/producthelp/Current/InstallConfig/en-us/Content/Software_requirements_and_recommendations.htm|
|Advanced Reporting Guide||https://www2.microstrategy.com/producthelp/Current/AdvancedReportingGuide/WebHelp/Lang_1033/Content/home.htm|
|MSTR Web Guide||https://www2.microstrategy.com/producthelp/current/MSTRWeb/WebHelp/Lang_1033/Content/home_mstrweb.htm|
|MSTR Supported Configurations||https://www2.microstrategy.com/producthelp/Current/Readme/en-us/Content/certified_configurations.htm
Click View Dossier to learn more about certified product releases.