KPIs (Key Performance Indicators) are quantifiable measures for a certain objective over time. KPIs provide teams with measurable goals to hit, such as milestones or success rates. They also allow members across the engineering organization to see how effective they are so they can identify areas for improvement.
Add a KPI to a dashboard
Click on the little arrow next to the Add insight button on the top right corner of any dashboard and select New KPI.
Select a data source for your KPI
Use the Select dataset tab from the navigation menu on the left side of the screen.
Keypup grants you access to various datasets based on the applications and projects & repositories you connected.
You can identify on the right part all the fields you can query on each dataset by clicking on the See all available fields button.
Select the dataset containing the fields you are willing to use in your KPI.
Select the KPI type
Click on the visualization that best represents your data points. You can select from the following choices:
Simple KPI: Select a simple KPI when you just want to express a target against a specific number. As an example, the number of Pull Requests merged in a specific timeframe.
KPI with column chart: Select a KPI with column chart to express a target against multiple variables. As an example, the number of “items” addressed in a specific period by item type (PR, issues, bugs).
KPI with sparkline: Use KPI with sparkline to express a value and its progression over time. As an example, you could see the number of Pull Requests merged against a specific target and how it trends over time.
KPI with trend: KPI with trends is selected to showcase how a “target” number is trending over time and is expressed in percentage. As an example, the number of pull requests merged went up by 25% compared to the previous period.
KPI with cycle-time chart: Select a KPI with cycle-time chart to express a specific number against a collection of stages of a process. As an example, the duration of each stage of the software delivery lifecycle.
Query your selected dataset for your KPI
Once you have selected your KPI type and data source, you can begin building your insight by querying your dataset.
Select the Configure table tab from the navigation menu on the left. The table will include two default columns: Dimension and Metric.
Dimensions are field attributes of your data sets. For example, it could be a date of merging, an author or a label.
Metrics are the numerical values aggregated from the function applied to a specific field (Dimension).
N.B. The number of columns that are visible (Dimensions and Metrics) is determined by the visualization selected. You may add or remove dimensions and/or metrics columns by clicking on the (+) sign button on the right side of the column. To delete dimensions and/or metrics columns, click on the expand (...) button and choose Delete. |
Depending on how comfortable you are with query building, you can execute simple or complex queries. Select the field(s) you wish to query
From the drop-down menu at the top of the Dimension column, or choose "Custom formula."
Choose an operator, aggregator, or "custom formula" from the drop-down menu at a Metric level.
Simple query
Advanced query (custom formula)
Apply a filter (recommended)
You can apply AND / OR filters to narrow down the data used in your KPI.
To do so click on the Configure filter button at the top right corner of the insight builder interface.
Customize the trend to display (for trend, sparkline or column KPIs)
When selecting a bar, sparkline or trend KPI, you will have this additional step to configure the trend you are willing to represent. The selected data points used to express the trend are highlighted in blue in the table.
KPIs measure point-in-time performance against a target goal. When you create a bar, sparkline, or trend, you should be able to associate a common data trend with it. The following 3 use cases illustrate this:
For this example, KPI: review to merge pull request = less than 2 days. The KPI will display the average time elapsed from reviewed to merged requests
E.g. You can display the trend to show either:
The average time from reviewed to merged PR within the past 6 weeks in a sparkline to show a time series of this specific event
The average reviewed to merged time by contributor in a bar chart (each bar representing a contributor)
The reviewed to merged PR period-to-period ratio expressed in % to check if the team is releasing faster or not over time
The trend query can be configured independently from the KPI query, to show anything you want.
However, if you want to reuse the configuration of the KPI itself, just click on Apply KPI config. This will copy the configuration (columns and filters) of the KPI itself and apply it to the trend.
In the situation where you need to reuse only the configurations of KPI’s columns or filters, use the dropdown on the right of the button and click Apply for columns only or Apply for filters only to keep other configurations unchanged.
The other way around works as well. You can go to the Configure KPI tab then click “Apply Chart config” (or only for columns or filters) to apply the trend configuration to the KPI itself.
Configure drilldown for your KPI
The drilldown feature allows you to explore and analyze data from a particular insight in detail. It is accessed by clicking on specific data points in your insights.
By default, the drilldown table is disabled and must be activated thanks to the slider on the right part, from the Configure drilldown tab.
When enabled for the first time, a default configuration is applied:
A set of recommended columns is added
The filters are pre-configured to recover the clicked data point.
You can then apply any customization. Click here to learn more about drilldown configuration.
Customize your KPI "look & feel"
KPIs should be readily recognizable and provide information at a glance. Although it is not necessary, it is suggested that you label your KPIs in accordance with value thresholds.
A high value can be a good or bad indicator, based on the information you are evaluating - this is why it is important to specify the “unit” of the number displayed.
Depending on the nature of the chart, you can also toggle values in the cell (for heatmaps) or add visual thresholds (for all area charts, line charts, bar charts and column charts) to illustrate where your value goes below or beyond a chosen value.
Document the KPI
Insight can be complex to understand by others, which is why having proper documentation alongside it is important.
The documentation should explain the purpose of the insight (“Why do we track this metric in the team?”), provide some highlights about its configuration (e.g. “Showing data labeled as bug over the last 12 months”), and explain the best way to read it (e.g. “More than 15 bugs raised per week would be considered a warning for the team”). Doing so will guarantee that the insight remains useful and readable to others at all times.
To do so, you can set the following elements:
Title (mandatory): a short and self-explanatory title
One-liner description (recommended): a short description that is displayed when browsing insights in collections.
Full documentation (recommended): exhaustive documentation regarding the goals, configurations, or reading tips about the insight. The full documentation can be written and formatted using markdown.
The full documentation can also be disabled, in which case the (?) tooltip near the insight title on the dashboard will remain hidden. Even when disabled, the documentation can still be accessed from the insight configuration.