Generate the snapshot

To generate a snapshot, you need to use the Execute tab in the Application editor:

A wizard will then be displayed enabling you to set the various date and naming options if required:

Click to enlarge

• The initial General Information wizard page enables you to select:
  
  • Capture Date - by default the current date will be pre-selected. If you wish to pre or post date your Snapshot, please select the correct date in the calendar. Note that you can also choose the time (24 hour clock applies) using the fields underneath the date selector. When complete, the Capture Date will be displayed as follows: DD/MM/YY HH:MM
  • Label - by default, the label will be predetermined by the CAST Management Studio, based on the date and time the wizard is opened. You can, however, enter your own label - but remember that the label is displayed in the CAST dashboards. Note that if you change the Capture Date, then the Label will not automatically update - if you wish to retain a date based label, you need to update it manually.
  • Application Version - by default, the CAST Management Studio will enter the current version name, however you are free to change this if necessary.
• Once all the fields have been filled in to your satisfaction, click Next to continue. The Execution Options screen will then be displayed:

• This page enables you to select:
  
  • Skip Application Analysis - if you have already executed the analysis as suggested in Run the Analysis, then you can tick this option to save valuable time.
  • Ignore Empty Module - Yyu should leave this unticked (please see the CAST Management Studio help for more information)
  • Send mail report (if configured) - Leave this ticked.
  • Upload Snapshots to Measurement Service (if configured) option will be selected by default. This option ensures that the data is uploaded to the Measurement Service for use in the Health Dashboard when a snapshot has been successfully generated.

• Click Finish.
• The CAST Management Studio will then automatically generate a snapshot for the current Application.
• When complete, you should see a step-by-step list of the action's processes in a dialog box:

; Set current user's temporary path
CAST_CURRENT_USER_TEMP_PATH=%APPLICATION%\CAST_TMP

; Set root path of all CAST logs
CAST_LOG_ROOT_PATH=%APPLICATION%\CAST_LOG
 
; Set the default LISA location
CAST_DEFAULT_LISA_DIR=%APPLICATION%\CAST_STORAGE
 
; Set the default LTSA location
CAST_DEFAULT_LTSA_DIR=%APPLICATION%\CAST_STORAGE

Snapshot currently in progress

When a snapshot fails, or when it is cancelled by clicking on the Cancel button when the snapshot is running, this means that the Dashboard Service schema will be left in an inconsistent state. When the Take a snapshot option is next used, a pop-up will be displayed, asking whether you want to continue or delete the snapshot in progress:

You should proceed as follows:

• If the snapshot was interrupted due to an error, then you must ensure the Continue execution of currently running snapshot option is not ticked, then click Finish. This will delete the interrupted snapshot.
• If the snapshot was interrupted because the Cancel button was clicked when the snapshot was running, ensure that the Continue execution of currently running snapshot option is ticked, then click Finish. This will continue processing the interrupted snapshot.

Snapshot warnings

"Application X" needs to be analyzed before taking the snapshot

If you receive the warning displayed above when attempting to generate a snapshot there are two possibilities:

• If this is the first time you have generated a snapshot and the job has not previously been analyzed, then the "Skip Analysis Job" option (available in the options wizard displayed when you generate a snapshot) will mean the snapshot is generated without the analysis having been run first. This can lead to incomplete results. Ensure you untick the "Skip Analysis Job" if the job has not previously been analyzed on its own.
• If you receive this warning and your job HAS previously been analyzed, then it is likely that the LISA, LTSA and Log preferences (which are used in an analysis) have changed. This may occur if you are running the CAST Management Studio on an entirely different workstation. If this is the case then the CAST Management Studio will consider that the configuration has changed and will treat the analysis jobs as not having previously been run. In this situation CAST recommends that you untick the "Skip Analysis Job" option before you continue with the snapshot generation.

Performance issues when using an Oracle Server host for the CAST AIP schemas

If you encounter performance issues when generating a snapshot using CAST AIP schemas hosted on an Oracle Server, CAST recommends that you consider making the following changes to force the use of the ALL_ROWS optimizer mode instead of the default RULE mode:

globallysharedsettings.ini

Add the following to the globallysharedsettings.ini file: (located here: %PROGRAMDATA%\CAST\CAST\<version>):

ForceOptimizerAllRows=1

CAST-MS.l4j.ini

Add the following to the CAST-MS.l4j.ini file (this file does not exist by default therefore you must create it in the root CAST AIP installation folder):

-Doptimizer_mode=ALL_ROWS

Restart the CAST Management Studio

Restart the CAST Management Studio before you attempt to generate the snapshot again.

Check the snapshot results

The easiest and quickest way to check the results of a snapshot generation is to open the Engineering Dashboard and view your results. If you don't have one set up yet (or your licensing agreement does not allow you to install one), you can invoke the "on the fly" Engineering Dashboard by clicking the Open Engineering Dashboard option in the CAST Dashboard Service editor:

Tips for checking the results

Detect any third party libraries, generated code or code that is not maintained by the project

• Impact: This source code is not important for the project, because project can't do anything regarding it. It is better to exclude it.
• Remediation: Exclude this source code from the dashboard. It should be analyzed by AIP but it shouldn't appear in the dashboard.
• Details: Most of the time, third party libraries are very complex and not documentation.
• Tips: you can check it in top cyclomatic complexity tab for example. or you can search for some specific string pattern like 'gen', 'test' ...

Check module weight

• Impact:  Bad aggregation for modules gives bad assessment quality.
• Remediation: Usually, good aggregation is done with aggregation by Artifacts.
• Details: By default, grades are measured on the entire Application
• Tips: consolidation mode is defined in the Assessment Model in the CAST Management Studio:

Check dead code / Unreferenced functions or methods

• Impact: Some rules dealing with unreferenced objects have a high weight and these rules are very useful for the project to help identify rapidly dead code in the source code.
• Cause: unreferenced objects may come from mistakes in the configuration due to specific frameworks that are not correctly managed.
• Remediation: review your configuration and run the analysis again.
• Tips: in the Engineering Dashboard, you can look at rules starting with "unreferenced XXX".

Check naming convention (if configured)

• Impact: default parameters are often wrong and rules dealing with naming conventions are normally low.
• Remediation: assess the Assessment Model and change the parameters for these rules.
• Tips: be careful with these types of changes, the impact is very low as it is dealing with documentation, transferability.... And people are more focused on performance or robustness. Secondly, to keep a good baseline and to be able to compare apple with apple, it is sometimes better not to correct it.

Click to enlarge:

Check file volumes

• Impact: make sure, in terms of volume, you have the same range of files in input (in the source folder) and in output (Engineering Dashboard).
• Remediation: if some files are missing, you may have to re-analyze the application.
• Tips: some open source tool exist (like cloc) to help you to count files in the source code folder.

Click to enlarge:

Delete snapshot

If the initial snapshot is not satisfactory, delete it - this will delete it from the Dashboard Service and the Measurement Service (if you chose to upload the results to the Measurement Service):

• Select the snapshot
• Click the delete button as highlighted below
• You will now need to make any configuration changes that you require and then re-generate the snapshot.

Upload snapshot data to the Measurement Service for viewing in the CAST Health Dashboard

If the snapshot now contains the information you expect, then you can upload it to the Measurement Service:

Manual upload

You can perform a manual upload of the snapshot you have just generated to the Measurement Service for display in the Health Dashboard:

Automatic upload

When you are generating a snapshot for a subsequent version of the Application (i.e. one that you have already on-boarded), and you are confident that the results of the snapshot generation will be correct (i.e. the new source code changes are relatively minor) then you can upload the snapshot data to the Measurement Service automatically during the snapshot generation using the Upload Snapshots to Measurement Service (if configured) option in the snapshot generation wizard:

Check results in the Health Dashboard

Once the snapshot data has been uploaded to the Measurement Service, CAST recommends that you check the results in the Health Dashboard. However, you may first need to reload the Health Dashboard cache so that results are displayed correctly:

Reload the Health Dashboard cache

The Health Dashboard features a data cache to improve the speed at which data is displayed in the dashboard. This means that when requesting data, the Health Dashboard may return data direct from the cache rather than fetching it from the Measurement Service. This means that data displayed in the dashboard may not be up-to-date - particularly if you have very recently generated a snapshot and uploaded data to the Measurement Service and were expecting to see this new data.

To reload the cache, see HD-ED - Reload the cache

Check the results

Browse to your Health Dashboard, login and check the results:

http://server[:port]/CAST-Health/