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 entities 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 entities 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".

Entity descriptor​

Groups are defined as a list of tags.

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

Groups may not contain whitespace characters.

YAML is the source of truth

If a group has been set through the catalog descriptor, an API call will NOT overwrite the existing value.

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 payments → orders → checkout → shopping, 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 or 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].