This topic describes how to use query directives to assign a threshold to a metric query, so that it reports an alert.

Overview

Metric queries calculate a numerical result related to a particular property of the project that you are analyzing. For example, metric queries can calculate the size of your project by counting the number of lines of code, the number of comments or the number of statements. You can also use metric queries to measure the complexity of a function by calculating, for example, the number of execution paths through it. Metrics generate alerts when you set appropriate thresholds for the results, using Query directives. Metric alerts are typically used to indicate problems or highlight bad coding practise. For further information on the built in metrics and alerts, see Semmle standard rules.

Defining thresholds using conversion directives

You can generate alerts using metric queries, using a conversion directive. A conversion directive is a type of query directive that defines the conditions that the result output of a metric query must meet in order to generate an alert. Metric queries support the following conversion directives:

Directive

Value

Example

Purpose

@recommendation-from

<number>

@recommendation-from 3.4

All values higher than or equal to the value will generate an alert (type recommendation)

@recommendation-to

<number>

@recommendation-to 3.3

All values lower than or equal to the value will generate an alert (type recommendation)

@warning-from

<number>

@warning-from 5

All values higher than or equal to the value will generate an alert (type warning)

@warning-to

<number>

@warning-to 4

All values less than or equal to the value will generate an alert (type warning)

@error-from

<number>

@error-from 2

All values higher than or equal to the value will generate an alert (type error)

@error-to

<number>

@error-from 1.9

All values less than or equal to x will generate an alert (type error)

Example

Query directives must be defined immediately after the metric query that they act on, and each directive must appear on a separate line. There are several examples in the standard query suites, where conversion directives are used to convert metrics to alerts. In the example below, some of the the standard maintainability metrics for Python have thresholds defined, in order to generate alerts:

When you analyze a snapshot using metric queries that are subject to thresholds, formatted alerts (which include a warning message and an output value for the metric) will be reported where appropriate. As with normal alerts, you can integrate the results into a code review tool as part of your revision assessment process.