Custom Metric development

Owned by Anastasia Baranouskaya
Last updated: Sept 06, 2024 by Maksim Chorny
7 min read

Create New Metric

  1. On the main menu, click Perf, and then open the required project and open the Delivery Metrics page.

  2. Click Add → Metrics on the Delivery Metrics. The Metric Catalog is opened. 

  1. Click Create Metric button and select Custom category.

Create metric.png

Step 1: General

  1. Provide a Metric Name. The following requirements should be met:

  • The minimum length of the name should be 5 characters.

  • The name must be unique among all metrics, whether they are published or in draft status.

  • Cyrillic symbols are not permitted; only English characters are allowed.

  1. You can add a metric overview in the "Description." This text will be displayed in the metric catalog and in the widget tooltip.

  2. Select a Primary Dimension where you think the metric makes the biggest contribution.

  3. Optionally you can select Secondary Dimension(s) if the metric contributes in different areas.

  4. Click Next.

As soon as 'Next' is clicked and navigation is made to the next step, the metric is saved and becomes available in the metric catalog in draft state.

Step 2: Dataset selection

To build a custom metric, it is necessary to select a dataset based on which the metric will be created. A list of available datasets is presented in the left menu (see PERF Datasets). PerfQL provides powerful techniques for data manipulation, allowing you to create advanced custom metrics using formula-like expressions. You can achieve this by selecting, joining, filtering, and aggregating your data.

  1. To generate a dataset for a metric, write PerfQL statements in the PerfQL input field.

PerfQL Rules

  1. Only Select statements.

  2. Only one root statement per query.

  3. Only specified list of functions could be used (list of supported functions).

  4. Only specified list of datasets (tables and fields) could be used (list of allowed datasets).  

  5. See examples of PerfQL Queries for different cases

  1. To preview data based on your PerfQL request, click the Run Preview button, and you'll see the result table in the Result Preview area.

The result preview is read-only and displays only the first 100 records, but the metric will be calculated for all available data.

Step 3: Chart Preview

This step is used to create charts, which provide you with an efficient and simple way of visualizing data.

  1. To define the scope of data on Axis Y:

  • To add columns, click Add +.

  • To remove any column, click Bin.

  1. Select the chart type from the drop down menu (see Available Chart Types for PERF Custom Metrics). 

  2. To configure the series, click on the series name.

  3. In the opened menu, you can select colors, switch on values on the chart, add trend lines, and set thresholds.

Rounding values on the chart

The Value Rounding feature empowers users to refine the precision of displayed numbers on the result chart, allowing them to customize the visual representation of data according to their preferences.

To enable value rounding on the chart labels:

  1. Select nessesary serias on the step 3.

  2. Check the checkbox labeled 'Show values on the chart.'

  3. Specify the number of decimal places for values on the result chart.

Example of Rounding via PerfQL:

Select key, ROUND(avg(story_points), 2) as average_story_points from ticket group by sprint;

Step 4: Drill Downs

Drill downs provide an ability to learn more about presented custom metric. This can be helpful if you need to get detailed information about the calculation at a selected point on the chart.

  1. Enter PerfQL query to form your Drill Down. You can enter PerfQL query and create a Drill Down for each series that exists on the chart. To do this, switch the tab in the PerfQL area, enter your query and save.

  1. Click Run Preview to see a preview of the Drill Down

Publish metric

By default, metrics are saved in draft state. To add a metric to the dashboard and aggregate it, the user should publish the metric. This action confirms that the metric is completed and ready.

To publish the metric, click Publish in step 4.

Edit Custom Metric

On the Delivery Metrics page, for the required project:

  1. Click Add → Metrics on the Delivery Metrics. The Metric Catalog is opened. 

 2. Find Custom Metric category in the left navigation menu and open Custom Metric category

  1. Click the gear icon for the necessary metric and click Edit. 

Copy Custom Metric to other units

The copying of metrics to other units is possible via the Support Team (AskDelivery@epam.com) .

However, please note that only the approach (PerfQL and metric settings) is copied; datasources and CSV files are not included.

Previewing metric’s PerfQL query

Previewing a metric enables all users, not just Key Staff, to understand how the metric is calculated. This is particularly useful for investigating PerfQL queries, which form the basis of metric calculations, without having to edit the metric itself.

  1. Find the custom metric published on the Metric Catalog or a widget on a dashboard that interests you.

  2. Select the "Preview PerfQL" button in the three-dot menu.

  3. A popup will appear with two tabs: "Data Selection" and "Drill Down."

 

Dublicate Custom Metric

If there is a need to create a similar metric with modifications or to experiment with data without compromising the integrity of the original metrics, a duplication of the custom metric can be made. "Save a Copy" will save a duplicate metric for you to modify and publish without the need to manually copy metric settings step by step.

  1. Navigate to the Metric Catalog.

  2. Find the published custom metric widget you want to replicate and click the three-dot menu linked to the selected metric.

  3. In the dropdown menu, select the "Save a copy" option.

  4. A copy of the metric in the draft state is created.

Delete Custom Metric

To delete Custom Metric from the Metric Catalog: 

  1. Open required project on the Delivery Metrics page.

  2. Click Add → Metrics on the Delivery Metrics. The Metric Catalog is opened. 

  3. Find Custom Metric category in the left navigation menu and open Custom Metric category

  4. Click the gear icon for the necessary metric and click Delete.