Skip to main content

Labelling Conventions and Best Practices

Team & Organization Structure

It’s a common practice for teams to “own” services or groups of services. One easy way to label services is to add a label for teams. For example:

team: front-end, team: platform, team: payments, team: catalog org: gaming-division, org: wealth-mgmt, org: consumer

You can create labels for different hierarchy levels, perhaps org or group. Team-based labels make it easy to see which services or projects are in the organization quickly, so you can quickly take inventory or contact the right team to ask questions.

Geographic and Customer Segments

If you’re running services used by different user groups geographically or different customer segments (like trial vs. paid customers), you may have separate SLOs you want to label, for example:

geo: us, geo: eu, geo: japan, geo: tier-1 customer-type: vip, customer-type: enterprise, customer-type: basic sku: enterprise, sku: teams, sku: trial

Service Dependencies & Sequence

Using labels, you can also describe the relationship between services. These labels are helpful when there is a clear order to the steps in a process that the services support. For example, consider a simple checkout workflow described using labels on SLOs:

  • Step 1: Price Items in Cart
  • Step 2: Calculate Tax
  • Step 3: Collect the Payment
  • Step 4: Send the Receipt

Using labels, you can describe the order of these operations as follows:

checkout-steps: price-items-step-1, checkout-steps: calculate-tax-step-2, checkout-steps: collect-payment-step-3, checkout-steps: send-receipt-step-4

You can also add dependencies to labels, for example:

depends-on: another-service, depends-on: aws, depends-on: mongodb dependent: another-service, dependent: some-api, dependent: mobile

Release Management & Versioning

Another use case for labels is defining the expected quality of a set of services - for example, explaining what is in production vs. dev or test. You can also use this to set clear expectations for experimental features or the state of progressive releases of new software.

env: dev, env: test, env: deprecated release: canary, release: experimental, release: public platform: v-next, platform: v-current

Management Reporting

You may need to produce consolidated reports about uptime, reliability, SLAs, etc., and then use them for management that doesn’t closely tie to the reality of how these systems work under the covers.

In such cases, you can use labels to create reporting groups to simplify these reports. For example:

reporting-group: sla-compliant, reporting-group: alpha, reporting-group: uptime cost-center: research-and-development, cost-center: cogs sla: tier-1, sla: best-effort

Incident Severity Level

Alert Policies can also have labels attached to them. This way, you can describe the severity of incidents or communication channels where your alerts will be routed. For example:

alert: low, alert: medium, alert: high channel: emergency, channel: ticket, channel: fyi

Build Your Own Naming Convention

Software is constantly changing, and how you organize and label your services will need to evolve. You may want to “pave the goat paths” and see what works in practice and codify it as a set of conventions. As you learn how to make labels better, add them to a simple internal wiki page or document that describes your SLO naming convention.

Building on an existing coding standard or naming conventions you already use for services or configuration in your cloud provider is an excellent place to start. Your SLOs and objects in Nobl9 should be idiomatic to your existing environment. Using business- and industry-specific terms will help less-technical users understand the SLOs, reducing the required translation.