Skip to content

Troubleshooting

Jump to bottom
Silvio Montanari edited this page Sep 23, 2019 · 6 revisions

Here are a few hints to help you troubleshooting when the execution of code-forensics, despite not exiting with a clear error, fails to generate any data or doesn't actually display any diagram.

Sometimes these issues can be resolved through a more accurate configuration of code-forensics, other times by passing the right parameters to the analysis task. Nevertheless, if both situations don't apply, then please submit a new issue and provide as much detail as possible.

Also, before starting to investigate a problem or logging a new issue, make sure that your question hasn't yet been answered in the FAQ page.

Debug code-forensics

In order to help with troubleshooting you can run code-forensics in debug mode by setting the environment variable COMMAND_DEBUG to enable more verbose output, e.g.:

$ COMMAND_DEBUG=true gulp <analysis task>

In this execution mode code-forensics will display the exact script commands that are used to execute the vcs and code-maat programs. You may then run those commands manually, again to check the output for any anomalies.

Basic internals of code-forensics

The diagram belows attempts to visualise how the data is processed and transformed from its original source (the code repository) to its final destination (the data files in the output folder), and ultimately served to the browser

|----------|   |---------|   |---------|   |---------------|   |------------------|   |-------|
|repository|==>|log files|==>|code-maat|==>|analysis output|==>|diagram data files|==>|browser|
|----------|   |---------|   |---------|   |---------------|   |------------------|   |-------|
     log dump task -------------> report task -----> analysis task -------> webserver task

Below are described three common categories of issues that can arise.

Issues when generating log files

The log dump task consists of two steps:

  1. Log fetching: execute the vcs command to list the revisions falling into the given date range.
  2. Log normalisation: filter out the file paths corresponding to each revisions according to the repository settings (i.e. rootPath includePaths and excludePaths parameters). If at the end of this step no actual file paths are included in the log files the program stops with an error, because there is no relevant data for the analysis.
  • Check the output of the log task. The log files are located under the configured tempDir and are named after the date/time period specified for the analysis, e.g.:
vcslog_normalised_<date-range>.log

Here is a sample log file generated for a git repository:

--0d45e709f--2018-11-19--<author name>
--2d6a68c28--2018-11-19--<author name>
1       1       config/defaults.yml

--7a958bce6--2018-11-17--<author name>
3       3       config/cucumber.yml
4       4       features/step_definitions/aspects_steps.rb
2       2       features/step_definitions/post_with_poll_steps.rb

--a09f7d73d--2018-11-17--<author name>

--a6655c187--2018-11-08--<author name>
2       0       features/support/env.rb
1       1       features/support/publishing_cuke_helpers.rb
1       1       features/support/user_cuke_helpers.rb

Inspect the content of such files.

  • Check that the dates of the commits are within the expected date range
  • Check that the listed file paths correspond to the configured repository paths parameters

Log files caching

Another possible cause of incorrect or incomplete log data generation is the modification of repository paths configuration in between analysis runs. code-forensics does not attemt to generate a log file for a given period of time if such file already exists. However if the repository configuration paths have changed since the last log task execution there is a good chance the log files contains incorrect or incomplete data.

Issues when generating diagram data files

The diagram data files are located under the configured outputDir, inside a folder named after a randomly generated reportId, which you can identify from the url used to access the diagram visualisation, e.g. http://localhost:3000/index.html?reportId=<random id>.

  • The report folder should contain a manifest.json file. The manifest include report metadata and references to other generated files (dataFiles). Below is an example:
{
  "id": "35b103e5bb4ca4897c21c65611e4cbc12f54d29a",
  "reportName": "developer-coupling",
  "taskName": "developer-coupling-analysis",
  "time": "2018-12-25T05:27:52.990Z",
  "dateRange": "2011-01-01_2011-12-31",
  "parameters": {
    "maxCoupledFiles": 5
  },
  "enabledDiagrams": [
    "main-developer-coupling",
    "communication-network"
  ],
  "dataFiles": [
    {
      "fileType": "communication-network",
      "timePeriod": "2011-01-01_2011-12-31",
      "fileUrl": "35b103e5bb4ca4897c21c65611e4cbc12f54d29a/2011-01-01_2011-12-31_communication-network-data.json"
    },
    {
      "fileType": "code-ownership",
      "timePeriod": "2011-01-01_2011-12-31",
      "fileUrl": "35b103e5bb4ca4897c21c65611e4cbc12f54d29a/2011-01-01_2011-12-31_main-dev-coupling-data.json"
    }
  ]
  • Each dataFile should exist and not be empty.

Issues when rendering diagrams in the browser

This is a more advanced type of troubleshooting, which requires you to know how to debug javascript running in your browser. Any modern browser should have some kind of developer tools plugin/function to enable the inspection of its javascript console. If you see any error being printed in that console when opening the web page for a particular diagram/report then there is the most likely reason for the failure. Make a note of the error and please log a new issue.

Clone this wiki locally