External Metrics View
Situations may arise in which you want to observe a quality property of code and Teamscale does not provide such metric. For instance, observing code defect density (i.e. the number of code defects per specific number of lines of code) or frequency of bug-fixes on a file level. You can do this by first creating an external metric. Once created, it needs to be activated in the analysis profile that is used by the current project before it becomes visible in the Metrics and Delta perspectives, and also in the metrics-related dashboard widgets. To create an external metric, select Project Configuration → External Metric Descriptions in the left navigation sidebar. This leads you to the External Metric Descriptions view.
External Metrics Descriptions Page
On this page, you will find a table of external metric descriptions if they have been configured already. This image shows the two external metrics described in the previous paragraph:
Click the button New metric description. This provides the Create External Metric Description view:
Create External Metric Page
In this view, you have to enter a unique external metric id (that Teamscale uses internally to identify metrics), an analysis group name (collects similar metrics under a common group in analysis profile configuration), a UI name (some friendly name to be displayed on the user interface) and a description of the metric. The field aggregation indicates how values of this metric will be aggregated for directories, e.g., by selecting the minimum value or the maximum value or using the sum operator as aggregation.
You can select one or more metric properties under Select Metrics Properties . They are explained here:
SIZE_METRIC | Indicates a size metric describing the amount of source code in some manner, e.g.800 lines of code or 1000 source lines of code. |
RATIO_METRIC | Indicates a ratio metric that only has values between 0 and 1. In the UI, these values are expressed as percentages. |
LOW_IS_BAD | Indicates that lower numeric values represent lower quality. The default case is that lower is considered better. |
QUALITY_NEUTRAL | Means that values of a metric are not assessed to have negative or positive impact on quality. This value contradicts with LOW_IS_BAD and you should select only one or the other. |
Sample
For example, the code defect density metric described previously is a SIZE_METRIC and qualifies as RATIO_METRIC if expressed per 100 lines of code.
The field value type tells the kind of value for a metric. Possible values are:
NUMERIC | A numeric metrics consists of a numeric value e.g., file size. |
TIMESTAMP | Indicates that a metric conveys time information e.g., last date modified. It's value is a number in milliseconds since 1.1.1970. |
ASSESSMENT | An assessment metric stores an assessment with red, yellow and green. |
On the External Metric Descriptions page, in the table of existing metrics under Actions , you can edit a metric by clicking the edit button . This leads to the Edit External Metric View. Also, you can use the delete button to delete a metric.
All external metrics once created require three additional steps before they are accessible in Teamscale. The first step is activating them in the analysis profile of the project. You can do this by editing the analysis profile, making changes only in the Select Analysis Tools section of the profile. There, you can select the checkbox besides Custom External Metrics . After clicking Continue underneath, a new quality indicator named Custom Metrics is visible in the Configure Quality Indicator section of the profile, organizing the new metrics under the specified analysis groups and providing more options for configuration.
In the second step, perform a re-analysis of the Teamscale project in the Projects view as explained here.
Finally, metrics need then be uploaded for files via the REST interface (endpoint: /api/projects/{project}/external-analysis/session/{sessionId}/external-metrics).
Import External Metric Descriptions
External metric descriptions can be imported into Teamscale. On the External Metric Descriptions page of the Project Perspective, you can click the Import metric descriptions button at the top of the page. This leads to the import view:
Browse to select a zip archive containing metric descriptions and click Upload. Upon successful import, you will be directed back to the Project Perspective showing the imported metric descriptions.
Export External Metric Descriptions
At the top of the External Metric Descriptions page, you can click the Export metric descriptions button to download as a zip archive, the stored external metric descriptions.