Key Performance Indicator or KPIs can be configured to provide interesting information regarding your pipelines, jobs, deployment, code coverage, etc. Please note that this feature is still at its early stage but more will come soon!

To start configuring them, go into the project's section and click Add metric, you'll then have a list of possible KPIs as well as specific popup once you clicked on the desired one.

menu configuration

# List of available KPIs

There are currently 5 available KPIs gathered in to group types: concourse & events ones.

Name Group Description
Build average time concourse gives insight on the average build time of a job
Build frequency concourse shows how frequently a job is being triggered
Build history concourse provides longer job history and better representation
Code coverage events shows code's coverage as well as evolution
Time to release events indicates how long releases spend in each environment

Notes

You might see more KPIs on the page when configuring them, because some are split into different ones depending on the widget used for each. See more details in the next sections.

# Group types

As previously mentioned some KPIs are based on concourse, while some are based on events. The one based on concourse simply need a configuration and will work out of the box afterwards. The events KPIs require not only a configuration, but also to send those events to Cycloid in order to build data.

# Concourse

Currently to configure Concourse's KPI you need to provide [LINK TO API] all elements: project, environment, pipeline & job's name. However depending on the KPI you might or might not be able to select different widget.

# Configuration

Name Type Widgets allowed Scope
Build average time build_avg_time bars project, environment, pipeline, job
Build frequency build_frequency line project, environment, pipeline, job
Build history build_history history, pie project, environment, pipeline, job

Here are some examples on how you could configure KPIs via cycloid's CLI:

cy kpi create --name "Job test history" --org test --type build_history --widget history --project test --env test --job test
cy kpi create --name "Time to release" --org test --type time_to_release --widget line --project test --config '{"envs": ["dev", "staging", "prod"]}'
1
2

# Events

Tip

If you're unafamiliar with Cycloid events, take a look at our events page to check how you cand send events through your pipelines. You can also check our CLI, if you prefer to do that from scripts or from your favorite shell.

For the events based KPI, you need to configure them, and then to modify your pipelines/scripts to include the generation/sending of such events. There are currently 2 types of KPIs using events:

Name Type Widgets allowed Scope Config
Code coverage code_coverage doughnut project
Time to release time_to_release line project {"envs": ["env1", "env2", "env3"]}

The Time to release configuration corresponds to the order of environments, from the first to the latest.

For example, if you have 3 environments: production, preproduction and development, you'd set the configuration to: development, preproduction, production. Which indicates the branch order that your features are going through, which will help to identify extra time spent at every stage.

Please note, that the version is irrelevant to establish if a version has been released or not. That is because a version could be anything: version, timestamp, tags, commit id, etc.

Instead the chronology is used to be able to identify if something has been deployed or not. This is why if you have in your list of events:

  1. dev - v1 at t
  2. dev - v2 at t+1
  3. prod - v1 at t+2

The dev v1 and v2 will be considered both released, because the deployment of prod came after (no matter the version number). However if you had the event of prod v1 deployment before dev v2 deployment, then dev v2 wouldn't be considered released.

# Formats

In order to be properly consumed by the KPIs, events have to respect a certain JSON format:

Type Body Tags
Code coverage {"coverage": 42.001} [{"key": "kpi", "value": "code_coverage"}, {"key": "project" "value": "<name>"}]
Time to release {"env": "<name>", "version": "<v>"} [{"key": "kpi", "value": "time_to_release"}, {"key": "project", "value": "<name>"}]

Important

Please ensure the body/tags are valid JSON either with an online JSON validator or using some CLI commands.

Here are some examples on how you could create those events via cycloid's CLI:

cy  --org test event create --tag kpi=time_to_release --title "Release" --tag project=test --message '{"env": "dev", "version": "v1"}'
cy  --org test event create --tag kpi=code_coverage --title "Coverage" --tag project=test --message '{"coverage": 60.10}'
1
2

# Look

KPI Widget Render
build_avg_time bars batb
build_frequency line bfl
build_history history bhh
build_history pie bhp
code_coverage doughnut ccd
time_to_release line ttrl

# Frequent Questions

# I've configured my KPIs but the data is empty, what can I do?

If the KPIs configured are based on events, you have to start sending events to feed the KPI. If the KPIs configured are based on concourse, then the data is imported every day.

# Can I change the time range?

Not yet, but we are planning to add this soon!

# I cannot update my KPI's project or environment configuration is it normal?

Yes, this is normal because the data has to match the KPI's configuration. So in order not to break that link, the configuration cannot be edited once done.

# Can I aggregate similar data together?

Not at this moment, but this is something we are working on!

# Are you planning to integrate those KPI as part of your dashboards?

Yes!

# Could we have different dashboards/KPIs depending on the profile?

Perhaps, we are still investigating how to implement the dashboard in the most efficient way.