Skip to main content

Groups

Summary

Groups are a tagging system that can be used to group your catalog together, enabling a variety of use cases including:

  • Including/excluding services from Scorecards
  • Reporting
  • Tagging

Use Cases

Tagging

The simplest use case for Groups is tagging. You may want to segment your catalog into different types or domains. For example:

  • Language (python, java)
  • Domain (infra, payments)
  • Type (backend/frontend, library/api)
  • Tier (tier-1, tier-2)

Scorecards

Once you've tagged your catalog with Groups, you can use them to include/exclude services from your Scorecards. For example, you may say "this Scorecard only applies to all Python services".

Reporting

You can also use Groups for reporting. You may want to aggregate Scorecard scores by domain or tier, for example "I want to see our Production Readiness scorecard broken down by tier".

Catalog Descriptor

Groups are defined as a list of tags.

x-cortex-groups:
- group-1
- another-group
- third-group

Groups must contain only alphanumeric characters, and may not contain whitespaces.

Hierarchies

Since Groups can be used as tags for product/domain areas and other such hierarchical data, we expose an ability to define a hierarchy of Groups.

For example, you may have the following structure as a domain hierarchy paymentsorderscheckoutshopping, where any entity tagged with payments also belongs to orders, checkout, and shopping.

This hierarchy is used for:

  • Executive reporting, letting you roll up your catalog at different levels of granularity
  • Including/Excluding categories of services from Scorecards (for example, "this Scorecard applies to all services under the shopping umbrella").
  • "My Services" and "My Resources" when using Group subscriptions

API

Currently, you can only define hierarchies through our API.

The API accepts a list of "edges", defining relationships between groups.

curl -X PUT 'https://api.getcortexapp.com/api/v1/groups/relationships' \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Content-Type: application/json' \
--data-raw '{
"relationships":[
{
"parent": "cortex",
"child": "infra"
},
{
"parent": "infra",
"child": "library"
}
]
}'

By default, this API appends any relationships to the graph you've already sent to Cortex using this API. If you want to replace the entire graph, just add a replace=true query param to the request.

FAQ

  1. When should I use Groups instead of Custom Data?
    1. To determine whether or not to use Groups or Custom Data, consider whether your use case would be considered "tagging" with a definite enum of values (backend vs frontend), or more freeform metadata availability-zones: [east, west].