KBEA-00002 - Information to collect before reporting an issue

Summary

You want to report a bug and want to know which information is needed. The solution’s steps use the scientific method for investigation and analysis.

Solution

Electric Cloud recommends keeping a very detailed log of steps you perform (try to key this off of the build ID). When attempting to diagnose an issue, here is some basic information to gather:

• What you are building
• What you were using to do this (vanilla Electric Make (eMake), a custom version, and so on)
• What you are trying to prove
• What is the expected outcome
• What happened, and why you think that happened
• Keep the output of the step (build logs, annotation, eMake history, and so on)

Complete the following steps to retrieve detailed information that Electric Cloud requires to diagnose the issue. Electric Cloud support engineers will request this information almost immediately, so you may want to provide it proactively:

1. What OS is this happening on (be as exact as possible… version, service pack, patch level, and so on)?
   1. Linux:
      1. Run uname -a to show the OS information
      2. Run cat /proc/cpuinfo to show the processor configuration
      3. Run cat /proc/meminfo to show the memory configuration
      4. Run cat /etc/issue to show the installation version
      5. Run rpm -qa (or whatever package management tool you use) to list installed packages
      6. Run ulimit -a to show the OS limit
      7. Run df -h to list free disk space
   2. Solaris:
      1. Run uname -a to show the OS information
      2. Run /usr/sbin/psrinfo -v to check in the processor configuration
      3. Run /usr/sbin/prtconf to show the memory configuration
      4. Run showrev -p to show installed patches
      5. Run pkginfo -l to see installed packages
      6. Run pkginfo -p to see if there are any partially installed packages
      7. Run ulimit -a to show the OS limits
      8. Run df -h to list free disk space
   3. Windows:
      1. Run the commandline tool systeminfo
      2. Run net use to list mounted shares
2. What is the exact version of ElectricAccelerator that you are using (down to the build ID)?
   1. Run emake --version on the build machine
   2. Check the Cluster Manager About box for the version
   3. Check the Cluster Manager for the agents’ EFS and Agent versions
3. What tools (if any) are involved in the issue/build, and what are their versions?
4. What is the exact error message?
5. How reproducible is the error (sporadic, 1 in 10 builds, always)?
6. Does the issue occur at the same point during the build each time?
   Issues that move around in the build generally indicate one of the following: multiple issues, an issue with a particular machine, or an infrastructure-related issue. Issues encountered in the past:
   1. Overloaded file servers
   2. Overloaded local network drivers (For example, AFS on Windows has an issue with too many concurrent connections.)
   3. Overloaded ClearCase servers
   4. Overloaded network
   5. Filled up local disks on the agent or eMake machine
7. Does the issue occur on a specific machine, or does it occur on different machines?
   1. Is the machine in question configured exactly the same as all others?
   2. Can the machine is question see the same network resources?
   3. A particular tool may not have been activated on the agent machine. (For example, Visual Studio requires the user to select the development environment to set up when it’s called for the first time. In a non-interactive build, this results in a popup sitting on the agent machine waiting for input.)
   4. In some instances, a failure occurs because of an earlier step, so the location of the failed step is irrelevant.
8. Does the issue occur when running the build without ElectricAccelerator?
9. Are there any messages in the Cluster Manager system log?
10. If possible, provide a minimal test case that Electric Cloud can use to track down the issue. (It is understood that this is difficult.)

Agent Issues

1. For agent-side issues, enable full session tracing before running the builds. Refer to the following knowledge base articles for additional information gathering and troubleshooting tasks:
   • KBEA-00020 - Getting and setting Agent and EFS debug levels
   • KBEA-00021 - Determining current Agent status
   • KBEA-00027 - Enabling diskcache logging
   • KBEA-00036 - Fixing builds that appear to hang
2. For “hanging” agents, provide a core dump (KBEA-00092 - Creating a process or machine core dump).
3. On Linux, depending on the issue, engineering may need a kernel dump (KBEA-00091 - Forcing a kernel dump).
4. In certain cases, it might be useful to run procmon on Windows to track what files/registry keys are accessed during the build.
5. Provide any messages in the Cluster Manager system log.
6. Send any memory dump files you can find:
   1. Linux:
      1. /*core*
      2. /root/*core*
      3. /opt/ecloud/i686_Linux/bin/*core*
      4. A kernel panic will not produce a core dump in any of those locations. If a Linux system is set up to capture kernel dumps, it will create a dump in /var/crash//vmcore, or something along those lines.
   2. Solaris:
      1. /*core*
      2. /tmp/*core*
      3. /opt/ecloud/sun4u_SunOS/bin/*core*
   3. Windows:
      1. c:*.dmp
      2. c:\ECloud\i686_win32\bin*.dmp
      3. c:\windows
7. Provide the agent/EFS log files:
   1. UNIX:
      1. /var/log/ecagent*.log
      2. /var/log/console*.log
      3. /var/log/diskcache*.log
      4. /var/log/erunner.log
      5. /var/log/messages* or /var/adm/messages*
   2. Windows:
      1. c:\ECloud\ecagent*.log
      2. c:\ECloud\console*.log
      3. c:\ECloud\efs*.log
      4. c:\ECloud\diskcache*.log
      5. c:\ECloud\erunner.log
      6. c:\ECloud\i686_win32\bin\ecagentsvc.log
      7. Any errors or warnings in the Windows event log

eMake Issues

1. Run the build to gather more information.
2. Provide any messages in the Cluster Manager system log.
3. Provide an annotation file (--emake-annodetail=basic,file,lookup --emake-annofile=emake.xml).
4. Provide a debug log (--emake-debug=jnpf --emake-logfile=emake.log).
5. For parsing issues, you may need to collect a remote parser log (see ?KBEA-00041 - Collecting a remote parse log).
6. Are there any conflicts in the build?
7. Is history really being used (ensure you check the build details)?

Cluster Manager Issues

1. Provide any messages in the Cluster Manager system log.
2. Provide the Cluster Manager log files:
   1. UNIX:
      1. /var/log/cmlog
      2. /opt/ecloud/<ARCH>/logs/accelerator.log
      3. /opt/ecloud/<ARCH>/logs/ElectricAcceleratorCMService.log
      4. /opt/ecloud/<ARCH>/apache/logs/access.log
      5. /opt/ecloud/<ARCH>/apache/logs/error.log
      6. /opt/ecloud/<ARCH>/mysql/data/*.err
   2. Windows:
      1. c:\ECloud\i686_win32\logs\accelerator.log
      2. c:\ECloud\i686_win32\logs\ElectricAcceleratorCMService.log
      3. c:\ECloud\i686_win32\apache\logs\access.log
      4. c:\ECloud\i686_win32\apache\logs\error.log
      5. c:\ECloud\i686_win32\mysql\data*.err

Install Issues

1. What version of the product were you trying to install?
2. What platform (OS and revision level) is running on the machines?
3. Describe the problem that you encountered (for example, install failed; install completed but the product did not start; and so on.)
4. Send the related installation log files, from c:\ECloud or /opt/ecloud.
   Note: There is a temporary version of this log file in /usr/tmp (on UNIX), or %TEMP% (on Windows), the location is printed in the summary for the GUI install.

Visual Studio Plugin Issues

Run the build with ECADDIN_DEBUG set to 1, and collect the plugin log from the agent. It is located in c:\ on the agent and its name is similar to ecdebug_12345678.log

Applies to

• Product versions: All
• OS versions: All