Skip to main content

Service Groups

Summary

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

  • Including/excluding services from Scorecards
  • Reporting
  • Tagging

Use Cases

Tagging

The simplest use case for Service Groups is tagging. You may want to segment your services 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 services with Service 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 Service 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".

Service Descriptor

Service Groups are defined as a list of tags.

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

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

Hierarchies

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

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

This hierarchy is used for:

  • Executive reporting, letting you roll up services 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" when using Service Group subscriptions

API

Currently, you can only define hierarchies through our API.

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

curl -X PUT 'https://api.getcortexapp.com/api/v1/service-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 Service Groups instead of Custom Data?
    1. To determine whether or not to use Service 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].