Skip to main content

Aggregation Property

Aggregation properties allow you to calculate metrics based on the relations in your catalog.

Using the aggregation property enables you to see relevant metrics on related entities, without having to manually calculate them.

Aggregations can be performed on any blueprint that is related in any way to the current blueprint (directly, indirectly, upstream or downstream).

💡 Common aggregation usage

For example, if you have a microservice blueprint, you can define aggregation properties on it to calculate metrics based on related entities such as:

  • Number of open jira issues related to a microservice.
  • Number of CRITICAL and HIGH vulnerabilities that are not resolved related to a microservice.
  • Average deployment frequency in the last week.
  • Build success rate in the last month.

The aggregation property enables you to specify scorecards and initiative rules based on metrics of related entities.

tip

For example - If you have a microservice blueprint, with related Alert blueprint, you can define a rule that will check if the number of open CRITICAL and HIGH alerts that are related to each microservice is greater than 0.

When to use Aggregation Properties

Aggregation property ideally will be defined on blueprints which are in the higher abstraction level in your catalog.

Those blueprints are usually the ones that are related to many other blueprints in your catalog, and therefore, they are the ones that can benefit the most from aggregation properties.

Specification

The aggregationProperties key is a top-level key in the JSON of an entity (similar to identifier, title, properties, etc..)

The aggregation property supports calculations by entities or by property.

  • Calculations by entities are performed on the entities that match the query (e.g. count the number of entities that match the query).

  • Calculations by property are performed on the property of the entities that match the query (e.g. sum the value of the property of the entities that match the query).

Definitions

Calculate By Entities

Calculate by entities is used to calculate metrics based on the entities that match the query.

Supported methods:

  • count - Count the number of entities that match the query. For example, count the number of open Jira issues related to a microservice.
  • average - Calculate the average of entities per a defined time period. For example, calculate the average deployment frequency per week.

In this example, we have a microservice blueprint and we want to calculate the number of open Jira issues related to each microservice.

{
"aggregationProperties": {
"numberOfOpenJiraIssues": {
"title": "Number of open Jira issues",
"target": "jiraIssue",
"calculationSpec": {
"calculationBy": "entities",
"func": "count"
},
"query": {
"combinator": "and",
"rules": [
{
"property": "status",
"operator": "=",
"value": "OPEN"
}
]
}
}
}
}

The aggregationProperties contains a key called numberOfOpenJiraIssues which is the identifier of the aggregation property we want to define.

  • title - The title of the aggregation property.
  • target - The blueprint we want to aggregate data from.
  • query - Optional - The query that will be performed on the target blueprint. The query is based on the Filters to include or exclude specific data based on Port's Search Rules
  • calculationSpec - The calculation specification.
    • "calculationBy": "entities" - The calculation will be performed on the entities that match the query.
    • "func": "count" - is the function we want to use for the calculation.

Calculate By Property

Calculate by property is used to calculate metrics based on the property of the entities that match the query.

The property type must be a number.

Supported methods:

  • sum - Sum the value of the property of the entities that match the query. For example, sum the story points of open Jira issues related to a microservice.
  • average - Calculate the average of the property of the entities that match the query. For example, average cpu usage of a microservice.
  • min - Calculate the minimum value of the property of the entities that match the query. For example, lowest alert severity of a microservice in the last week.
  • max - Calculate the maximum value of the property of the entities that match the query. For example, highest alert severity of a microservice in the last week.
  • median - Calculate the median value of the property of the entities that match the query. For example, median cpu usage of a microservice in the last week.

In this example, we have a microservice blueprint, and we want to calculate the sum of the story points of open Jira issues related to each microservice.

{
"aggregationProperties": {
"sumOfStoryPoints": {
"title": "Sum of story points",
"target": "jiraIssue",
"calculationSpec": {
"calculationBy": "property",
"func": "sum",
"property": "storyPoints"
},
"query": {
"combinator": "and",
"rules": [
{
"property": "status",
"operator": "=",
"value": "OPEN"
}
]
}
}
}
}

The aggregationProperties contains a key called sumOfStoryPoints which is the identifier of the aggregation property we want to define.

  • title - The title of the aggregation property.
  • target - The blueprint we want to aggregate data from.
  • query - Optional - The query that will be performed on the target blueprint. The query is based on the Filters to include or exclude specific data based on Port's Search Rules
  • calculationSpec - The calculation specification.
    • "calculationBy": "property" - The calculation will be performed on the property of the entities that match the query (e.g. sum the value of the property of the entities that match the query).
    • "func": "sum" is the function we want to use for the calculation.
    • "property": "storyPoints" - The property we want to calculate the sum of. The property type must be a number.

Limitations

The aggregation property result for all entities of a blueprint will be recalculated every 15 minutes.