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 Add insight button down the dropdown on the top right of any dashboard., then select the type of KPI you wish to create (this can be changed later).
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.
The right part lists all the fields you can query on each dataset.
Select the dataset containing the fields you are willing to use in your KPI.
Read more about Keypup datasets here.
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 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.
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.
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 KPI 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:
Dimension: select a dimension field from the drop-down menu at the top of the column (or choose "Custom formula").
Metric: Choose an aggregator and target field (if applicable) from the drop-down menu at the top of the column (or choose "Custom formula").
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, cycle-time, or column KPIs)
When selecting a bar, sparkline, cycle-time, or trend KPI, you will have this additional step to configure the additional visualization. The selected data points used to express the trend are highlighted in blue in the table.
The KPI value usually represents the most recent data point. The trend, on the other side, shows the evolution of the KPI over time.
The visualization can be one of the following types:
Column chart: one vertical bar per value
Cycle-time: one chevron per metric (number of chevron = number of metrics added)
Sparkline: a line chart showing the evolution of values
Trend (%): a percentage showing the progression between the last two data points
The KPI trend is configured independently from the KPI value itself, giving you maximum flexibility to chart what is relevant to the associated KPI.
If you want to reuse the configuration of the KPI value for your trend, just click on Apply KPI config. This will copy the configuration (columns and filters) of the KPI itself and apply it to the trend.
If you only want to partially apply the configuration of the KPI to your trend, 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 and then click on Apply Chart config 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, we suggest specifying a unit as KPI suffix (e.g. hours, days, etc.) to let users know what the KPI is about.
Depending on the nature of the trend, different styling options will appear, such as showing/hiding values on the graph/heatmap, adding visual thresholds, etc.
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.