Summary: Documentation for the OMG-ATDM extension.

Extension ID

com.castsoftware.omg-atdm

What's new?

Please see OMG-ATDM - 1.0 - Release Notes for more information.

Description

ATDM (Automated Technical Debt Measure), is an OMG standard that has been submitted by the CISQ Consortium. This extension implements the OMG Automated Technical Debt Measure to estimate future corrective maintenance costs, i.e. the technical debt of the application in number of minutes, as described in the OMG ATDM specification 1.0, see: https://www.omg.org/spec/ATDM/1.0/PDF.

Note that this extension is not a replacement for the built-in Technical Debt measures included in CAST AIP "out-of-the box". Indeed both the existing Technical Debt measures and this extension can be used at the same time. In other words, the installation of this extension does not mean that the calculation of the existing Technical Debt measures will be disabled.

Compatibility

ProductReleaseSupported
AIP Core≥ 8.3.21 for 1.0.0-beta releases and 1.0.0-funcrel(tick)
≥ 8.3.24 for ≥ 1.0.1-funcrel(tick)
CAST RestAPI
(tick)

CAST Engineering Dashboard

  • 1.19 - 1.21 = beta5
  • ≥ 1.22 ≥ beta6
(tick)
CAST Health Dashboard-(tick)
CAST Security Dashboard≥ 1.19(tick)

OMG-ATDM version

1.0 (September 2018)(tick)

Dependencies with other extensions

Some CAST extensions require the presence of other CAST extensions in order to function correctly. The OMG-ATDM extension requires that the following other CAST extensions are also installed - these will be installed automatically when you install OMG-ATDM Index:

Download and installation instructions

Assessment Model

The extension calculates the following metrics as a Sizing Measures:

ReleaseMetric IDNameDescription
≥ beta31062030

OMG-ATDM: Remediation Effort ADDED

Measures the added remediation effort in number of minutes between two snapshots. Results are available at Application, Module, CISQ Business Criteria, CISQ Technical Criteria, Rule and Object level. 

≥ beta31062032OMG-ATDM: Remediation Effort DELETED

Measures the removed remediation effort in number of minutes between two snapshots. Results are available at Application, Module, CISQ Business Criteria, CISQ Technical Criteria, Rule and Object level. 

≥ beta21062010

OMG-ATDM: Number of occurrences

An occurrence (or Pattern Occurrence) designates a single instance of a Source Code Pattern (or Pattern) representing a weakness that has been implemented in the measured software. (ASCMM, ASCRM, ASCPEM, ASCSM). This sizing measure keeps, per snapshot, the number of occurrences per object, rule, CISQ Technical Criterion and CISQ Business Criterion.

≥ beta21062011OMG-ATDM: Complexity

The Complexity - or Effort Complexity - of the code elements implementing an Occurrence is qualification information that is measured according to the Effort Complexity definition from the Automated Enhancement Points (AEP) specification. (AEP).

≥ beta21062012OMG-ATDM: Exposure

The Exposure of an Occurrence is qualification information that measures the level of connectedness of the Occurrence with the rest of the software, both directly and indirectly through call paths.

≥ beta21062013OMG-ATDM: Concentration

Concentration is qualification information that measures the number of Occurrences within any Code Element in the software.

≥ beta21062014OMG-ATDM: Technological Diversity

The Technological Diversity of an Occurrence is qualification information that measures the number of distinct programming languages in which the code elements included in a single occurrence of a source code pattern are written.

≥ beta21062015OMG-ATDM: Gap Size

In the context of patterns which rely on roles that model values and threshold values that are not to be exceeded, the gap between these values must be closed to remediate this weakness; the Occurrence Gap Size is the extent of the gap, measured as the difference between the values and the thresholds.

≥ beta21062016OMG-ATDM: Adjustment Factor

Adjustment Factor is computed based on qualification measures.

≥ beta11062020OMG-ATDM: Adjusted Remediation EffortRemediation Effort designates the time required to remove an occurrence – or a set of occurrences – of a Technical Debt Item from the software. It covers the coding activity as well as unit/non-regression testing activities.

How are results calculated?

Predefined Un-Adjusted Remediation Effort

Configuration data is loaded to have the remediation effort for each CISQ Pattern. This is called Un-Adjusted Remediation Effort. The unit of effort is minute. The effort taken in to account by ATDM for each pattern is EFFORT_DEFAULT.

E.g.:

UNADJ_REMEDIATION_EFFORT
STANDARD : CISQ
PATTERN : ASCPEM-PRF-15
EFFORT_DEFAULT: 90
EFFORT_MIN: 30
EFFORT_MAX: 210
EFFORT_UNIT: MIN 


For all violations of pattern ASCPEM-PRF-15, the Un-Adjusted Remediation Effort is equal to 90 minutes

Scope

All CAST rules mapped to the CISQ 1.0 (December 2016) standard.

Qualification information

Complexity

The Complexity - or Effort Complexity - of the code elements implementing an Occurrence is qualification information that is measured according to the Effort Complexity definition from Automated Enhancement Points:

EC/LowEffortComplexity

EC is computed by the following metrics:

LowEffortComplexity

The technology related Low Complexity column for ADDED artifacts ( from COST_CONFIG ). When the violation has related objects, then the average EC of all objects is taken in to account. The complexity is computed for the main object violating a rule:

Complexity = AVG ( Effort Complexity all objects of the violation )/ Low Complexity for the related technology

Concentration

Concentration is qualification information that measures the number of Occurrences within any Code Element in the software:

1/nb of time the object violates any rule

Exposure

The Exposure of an Occurrence is qualification information that measures the level of contentedness of the Occurrence with the rest of the software, both directly and indirectly through call paths:

1+log(nb paths)

Technical diversity

The Technological Diversity of an Occurrence measures the number of distinct technologies in which the code elements included in a single occurrence of a source code pattern are written. This is set to 1. 

Gap size

In the context of patterns which rely on roles that model values and threshold values that are not to be exceeded, the gap between these values must be closed to re-mediate this weakness. This is set to 1. 

Adjustment Factor

The adjustment factor is computed based on qualification information, as follows:

AVG(Complexity) X AVG(Exposure) X Count(Technological diversity) X AVG(Concentration) X Sum(Gap size)

Technical debt

Finally the technical debt is computed by:

Nb Of Occurrences X Adjustment Factor X Un-adjusted Remediation Effort

Result storage

In ≥ 1.0.0-beta6, new result storage methods were implemented as described below.

Default result storage method - high level data only

By default only data aggregated at the following level is available and is stored in the Dashboard schema table DSS_METRIC_RESULTS:

Detailed information at Object and Rule level can be generated and made available to the dashboard on demand by executing the following query against the Dashboard schema:

select OMG_ATDM_COMPUTE_DETAILS (SNAPSHOT_ID, OBJECT_ID, RULE_ID) 

Where:

SNAPSHOT_IDIs the ID of the snapshot you want to generate detailed object and rule level information for.
RULE_ID

The ID of the rule you want to generate detailed information for. Note that if RULE_ID = -1, detailed information will be generated for all rules.

OBJECT_IDThe ID of the object you want to generate detailed information for. Note that if OBJECT_ID = -1, detailed information will be generated for all objects.

When the next snapshot is generated, detailed object/rule level information will be saved in the table OMGTD_RESULTS.

Alternative result storage method - all data

This method is not recommended for very large Applications, since the impact on performance of generating all data for every snapshot will be significant.

It is possible to change the behaviour and choose to always save all results (including Object and Rule level information) for every snapshot that is generated. To do so, execute the following query against the Dashboard schema:

select OMG_ATDM_DETAILSALL();

This option will be taken in account when a new snapshot is generated and as a result all information is saved as follows:

To disable the storage of all details, execute the following query against the Dashboard schema:

select OMG_ATDM_DETAILSONDEMAND();

What results can you expect?

Health Dashboard tiles

Two tiles are available out of the box (in v. ≥ 1.17) in the Overview and Trends sections respectively (the tiles will display no value if the OMG-ATDM extension is not installed and no snapshot has been generated):

Clicking these tiles will provide more detailed information:

Click to enlarge

Engineering Dashboard tile

This tile:

This tile displays Total Added and Removed OMG Technical Debt and the number of days taken for the same:

Clicking these tiles will provide more detailed information:

Click to enlarge

Using the RestAPI to obtain results

Total Technical Debt by Application, Module

Results can be obtained using a RestAPI query. For example, to obtain technical debt as a remediation effort use the metric #1062020 (you can replace this ID with other supported Sizing Measure IDs):

AAD/results?metrics=1062020&modules=$all&technologies=$all

Example showing the technical debt for all applications, with a breakdown by technology and by module for an example Application called "shopizer8321":

C:>curl -H "Accept: text/csv" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/AAD/results?metrics=1062020&modules=$all&technologies=$all"

Results:

Application Name;Module Name;Technology;Metric Name;Metric Id;Metric Type;Critical;Snapshot Date #1;Result #1
shopizer8321;null;null;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;387350.0
shopizer8321;null;HTML5;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;770.0
shopizer8321;null;JEE;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;386580.0
shopizer8321;shopizer8321 full content;null;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;387350.0
shopizer8321;shopizer8321 full content;HTML5;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;770.0
shopizer8321;shopizer8321 full content;JEE;OMG-ATDM: Remediation Effort;1062020;technical-debt-statistics;N/A;2020-03-27;386580.0

In other words, the "shopizer8321" application has a technical debt of 387350 minutes, which is equivalent to 387350 ÷ 60 ÷ 8 = 806 workload days. The remediation effort is dispatched between HTML5 code and Java Code as follows:

TechnologyRemediation effort
HTML       770 minutes
JEE386,580 minutes

Total Technical Debt by Business Criterion, Technical Criterion, Rule

With a CISQ Business Criterion ID, you can obtain the technical debt for this Quality Indicator and all related indicators (ie CISQ Measure Elements):

CISQ Business Criterion IDName
1062100CISQ-Index
1062101CISQ-Maintainability
1062102CISQ-Performance-Efficiency
1062103CISQ-Reliability
1062104CISQ-Security

Example:

C:>curl -H "Accept: text/csv" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/SHOPIZER/applications/3/results?metrics=c:1062100&select=omgTechnicalDebt"

Application Name;Technical Criterion;Metric Id;Metric Type;Critical;Snapshot Date #1;Result #1;OMG Technical Debt (Result #1);OMG Occurrences (Result #1);OMG Added Technical Debt (Result #1);OMG Removed Technical Debt (Result #1)
shopizer8321;ASCMM-MNT-1 - Control Flow Transfer Control Element outside Switch Block;1062110;technical-criteria;false;2020-05-15;4.0;0;2;0;0
shopizer8321;ASCMM-MNT-11 - Callable and Method Control Element Excessive Cyclomatic Complexity Value;1062112;technical-criteria;false;2020-05-15;3.58017346587814;null;null;null;null
shopizer8321;ASCMM-MNT-12 - Named Callable and Method Control Element with Layer-skipping Call;1062113;technical-criteria;false;2020-05-15;4.0;null;null;null;null
shopizer8321;ASCMM-MNT-13 - Callable and Method Control Element Excessive Number of Parameters;1062114;technical-criteria;false;2020-05-15;4.0;null;null;null;null
shopizer8321;ASCMM-MNT-15 - Public Member Element;1062116;technical-criteria;false;2020-05-15;4.0;40;1;0;0
...

You can get also the technical debt for a single rule, as long as this rule is identified as a CISQ rule by the CISQ Index:

C:>curl -H "Accept: application/json" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/SHOPIZER/applications/3/results?metrics=8216&select=omgTechnicalDebt,violationRatio"


...
				"result": {
					"grade": 4,
					"omgTechnicalDebt": {
						"total": 11040,
						"numberOccurrences": 176,
						"added": 0,
						"removed": 0
					},
					"violationRatio": {
						"totalChecks": 7411,
						"failedChecks": 33,
						"successfulChecks": 7378,
						"ratio": 0.9955471596275807
					}
				},

Detailed Technical Debt for a violation

As we refer to findings from a snapshot ID, and object ID and a rule ID with URI such as:
TINY/components/568/snapshots/8/findings/8216

We can refer technical debt details in a similar Web Service:
TINY/components/568/snapshots/8/omg-technical-debt/8216

C:>curl -H "Accept: application/json" -u admin:cast "http://localhost:9190/CAST-RESTAPI/rest/TINY/components/568/snapshots/8/omg-technical-debt/8216"
{
	"total": 180,
	"numberOccurrences": 3,
	"complexity": 1,
	"exposure": 1,
	"concentration": 0,
	"technologicalDiversity": 1,
	"gapSize": 1,
	"unadjustedEffort": 60,
	"added": 0,
	"removed": 0,
	"adjustmentFactor": 3
}

Querying the Dashboard schema for results

The Dashboard schema contains views and tables that provide information about the results generated by this extension:

View/TableDescription Type
OMG_ATDM_RESULTS_OBJ_APPRemediation effort and adjusted Factor aggregated at Application, Module, PATTERN level.
 
VIEW
OMG_ATDM_RESULTS_OBJ_RULE_APPRemediation effort and adjusted Factor for Object Rule, aggregated at Application, Module, PATTERN level.VIEW
OMG_ATDM_DETAILS_OBJ_RULEDetails all metrics computed for all violations.VIEW
ATDM_SCOPE_OCCURENCESLast scope taken in to account.TABLE

Obtaining results at Application level for a snapshot

SET search_path=xxx_central;
SELECT * 
FROM   omg_atdm_results_obj_app 
WHERE  snapshot_id = <snapshot_id>

Click to enlarge

Obtaining results per CAST Rule / CISQ Pattern at the application level for a snapshot

SET search_path=xxx_central;
SELECT * 
FROM   omg_atdm_results_obj_rule_app 
WHERE  snapshot_id = <snapshot_id>

For example to get the results for all metrics of pattern 'ASCPEM-PRF-8':

SELECT * 
FROM   omg_atdm_results_obj_rule_app 
WHERE  snapshot_id = 4 
       AND ( metric_value_index IN (SELECT T.metric_id + 1 
                                    FROM   aed_metric_quality_tags T 
                                    WHERE  T.tag = 'ASCPEM-PRF-8') 
              OR aggregatelevel = 'ASCPEM-PRF-8' ) 

Click to enlarge

To get the details of all computed metrics at object and rule level.

SELECT * 
FROM   omg_atdm_details_obj_rule 
WHERE  snapshot_id = 4 
       AND object_name = 'getOrdersList'

Click to enlarge

Note that to obtain the CISQ Pattern of a given CAST rule, you can adapt the following query. For example, to find the CISQ Pattern for the rule ID = 7201, the following query will return ASCPEM-PRF-8:

SELECT C.tag 
FROM   aed_quality_tags_doc C 
       join aed_metric_quality_tags T 
         ON T.tag = C.tag 
WHERE  C.standard = 'CISQ' 
       AND T.metric_id + 1 = 7201