Skip to main content

YAML Guide

This document explains how Nobl9 configurations are represented in the sloctl API, and how you can express them in .yaml format.

Overall Schema​

apiVersion: n9/v1alpha
kind: Agent | Annotation | AlertMethod | AlertPolicy | AlertSilence |  DataExport | Project | RoleBinding | Service | SLO |
metadata:
  name:  # string, mandatory
  displayName:  # string, optional
  project:  # string, optional
  labels: # string, optional
    "label_key":
      - "label_value"
spec:
[...]

Notes:

  • name: string - required field, convention for naming object from DNS RFC1123. name can:

    • Contain max. 63 characters.

    • Contain only lowercase alphanumeric characters or -.

    • Start with an alphanumeric character.

    • End with an alphanumeric character.

caution

Note that all names should be unique within a project. It is not possible to have two objects of the same kind with exactly the same name in a given project.

  • project: string - required field, convention for naming object from DNS RFC1123. project can:

    • Contain at most 63 characters.

    • Contain only lowercase alphanumeric characters or -.

    • Start with an alphanumeric character.

    • End with an alphanumeric character.

  • displayName: string - optional field. displayName can contain at most 63 characters. No additional validation is performed.

  • labels - string - optional field. Labels are key-value pairs that can be attached to SLOs, Services, Projects, and Alert Policies.

    • Labels must be in the key: value format (key=value in sloctl).

      • key can contain only lowercase alphanumeric characters, underscores, and dashes; must start with a letter and end with an alphanumeric character; maximum length 63 characters.

      • value can contain Unicode characters; maximum length 200 characters.

    note

    When adding labels to a YAML definition, remember to put both key and value in parentheses (""), for example:

    labels:
      "team":
        - "green"

    Otherwise, sloctl may return the following error:

    Error: malformed JSON payload - pass single list of valid JSON objects.

    • Labels can contain international (diacritic) characters.

    • Labels can contain underscores (_) and dashes (-) between the alphanumeric characters.

    • There can be max. 20 Labels assigned to a resource.

caution

If you are using a sloctl version older than 0.0.56, you will not be able to use kind: Project or kind: RoleBinding.

Overview of Available YAML Objects​

The following sections describe the types of objects that are available in Nobl9 and how to configure them.

note

Specific attributes of the various YAML objects are described in detail in the Notes following the examples.

Agent​

The Agent is a middleware between the Nobl9 app and an external data source. It gathers metrics data and sends it to Nobl9. Agents need to be installed on the customer's server.

Refer to Sources for details about configuring the Agent for each data source via sloctl.

YAML:

apiVersion: n9/v1alpha
kind: Agent
metadata:
  name:  # string
  displayName:  # string, optional
  project: # string, mandatory
spec:
  description:  # string, optional
  sourceOf:
    - Metrics
    - Services
# Only one type of source configuration is allowed for Agent, for example:
  dynatrace:
     url:  # interface URL to Dynatrace server

If you describe infrastructure as code, you might also consider creating Agents via Terraform. You can find more details in our Terraform documentation.

AlertMethod​

When an alert is triggered, Nobl9 enables you to send a notification to an external tool or a REST endpoint (Web Service). Alert methods can be associated with all available integrations.

YAML:

apiVersion: n9/v1alpha
kind: AlertMethod
metadata:
  name:  # string, mandatory
  displayName:  # string, optional
spec:
  description:  # string, optional
# Only one type of alert method configuration is allowed
  discord:
    # Secret field
    url: # URL to Discord webhook
  # or
  jira:
    url: string  # requires HTTPS
    username: string
    apiToken: string  # secret
    projectKey: string
  #or
  lightstep:
    url: string # secret field
  #or
  msteams:
    url: string # requires https://, secret field
  # or
  opsgenie:
    auth: GenieKey a5983bf6-e378-4c97-a6ab-8be3589e190f
    url: https://api.opsgenie.com
  # or
  pagerDuty:
    integrationKey:  # PagerDuty integration key
  # or
  servicenow:
    username: #string
    password: # string
    instanceName: # Service Now Instance name
  # or
  slack:
    url:  # URL to Slack webhook
  # or
  webhook:
    url: https://sample-end-point/notify

If you describe infrastructure as code, you might also consider defining the Alert Methods with the same convention. You can find more details in our Terraform documentation.

AlertPolicy​

Alert policies define when to trigger an alert via the configured alert method. A Nobl9 AlertPolicy accepts up to 7 conditions. All the specified conditions need to be satisfied to trigger an alert.

Here's a general YAML for kind: AlertPolicy:

apiVersion: n9/v1alpha
kind: AlertPolicy
metadata:
  name: # string
  displayName: # string, optional
  project: # string, optional - if not defined, Nobl9 returns a default value for this field
spec:
  description: # string, optional
  severity: Low | Medium | High
  cooldown: "5m" # valid string duration, accepted units: s, m, h
  conditions:
    - measurement: timeToBurnBudget | averageBurnRate | burnedBudget
      value: string or numeric
      op: lt | gt | lte | gte
      lastsFor: time duration  # default 0 (seconds | minutes | hours); example "5m"
      # You can define up to 5 alert policies per SLO
  alertMethods: # you can append several alertMethods
    - metadata:
        name: string # name of the alert method
        ...
    - metadata:
        name: string # name of the alert method

Notes:

  • spec[ ].cooldown - string, duration. The time measured since the last time point when all conditions were satisfied (for further details, go to Alert Methods. Default value: 5m. Accepted units: seconds | minutes | hours. Examples: 5m, 1h, 30s.

    • If cooldown period is not defined, default value 5m is used.

    • A minimum value is 5m (there's no limit for maximum value).

    • The value needs to be valid time string duration, that can be expressed as 300s, 5m, 1h. For more details, see Parse Duration.

      caution

      Cooldown on conditions level is allowed but deprecated:

      • If you define cooldown on conditions level, the maximum value from all conditions is saved.

      • If you define cooldown on both AlertPolicy and conditions level, Nobl9 will return the following validation error:

        Error: samples/sample-alert-policy.yaml:
        Key: 'AlertPolicy.spec.conditions[].coolDown' Error:Field validation for conditions[].coolDown' failed on the coolDownOnlyOnAlertPolicyOrConditionLevel' tag.
        Key: 'AlertPolicy.spec.coolDown' Error:Field validation for 'coolDown' failed on the 'coolDownOnlyOnAlertPolicyOrConditionLevel' tag.

  • conditions[ ].measurement: string - required field. The options are:

    • timeToBurnBudget - When the budget will be exhausted. The expected value is a string in time duration format (seconds | minutes | hours); for example, 72h (3 days). Example in human-readable format: Error budget will be exhausted in 3 days.

    • averageBurnRate - How fast the error budget is burning. The expected value is a float; for example, 1.1. Example in human-readable format: Error budget burn rate is 110%.

    • burnedBudget - How much error budget is already burned. This is in contrast to the UI, where the error budget is expressed in terms of the amount remaining. The expected value is a float; for example, 0.97. Example in human-readable format: Error budget is above 97%. The same example in the UI is represented as the Remaining error budget is 3%.

  • conditions[ ].lastsFor: string - optional field. Indicates how long a given condition needs to be valid to mark the condition as true. Default: 0 (seconds | minutes | hours). Examples: 5m, 1h, 30s.

  • conditions[ ].op: string - required field. A mathematical inequality operator; possible values are:

    • lte - less than or equal (<=).

    • gte - greater than or equal (>=).

    • lt - less than (<).

    • gt - greater than (>). The operator is used to compare the given value with the state of measurement. The operator depends on the measurement type: for timeToBurnBudget op=lt, for averageBurnRate op=gte, and for burnedBudget op=gte.

Here’s a working example of an alert policy created in sloctl:

apiVersion: n9/v1alpha
kind: AlertPolicy
metadata:
  name: trigger-alert-policy-bad-delayed-multi
  project: trigger-alert
spec:
  severity: Medium
  cooldown: "5m"
  conditions:
    - measurement: timeToBurnBudget
      value: "18h"
      op: lt
      lastsFor: "30m"
    - measurement: averageBurnRate
      value: 1.9
      op: gte
      lastsFor: "30m"
    - measurement: burnedBudget
      value: 0.01
      op: gte
      lastsFor: "30m"

If you describe infrastructure as code, you might also define the Alert Policy with the same convention. You can find more details in our Terraform documentation.

AlertSilence​

AlertSilence allows you to silence alerts that are attached to an SLO for a defined period of time. For more details, see Silencing Alerts | Nobl9 Documentation.

apiVersion: n9/v1alpha
kind: AlertSilence
metadata:
  name: alert-silence-name
  project: default
spec:
  description: AlertSilence description
  slo: slo-name # the name of the SLO AlertSilence will be applied to
  alertPolicy:
    name: alert-policy-name # the name of the AlertPolicy AlertSilence will be applied to
  period: # define period for the AlertSilence
    startTime: 2025-01-01T12:00:00+02:00 # define the start date-time point where the Alerts will be silenced
    endTime: 2025-01-01T13:00:00+02:00 # define the start date-time point where the Alerts will be silenced
    duration: 1h

Important Notes:

  • spec[n].alertPolicy - alertPolicy that AlertSilence will be applied to

    caution

    alertPolicy must be in the same project as AlertSilence and SLO

  • period[n].startTime, period[n].endTime:

    • These values define the date-time point where the Alerts will be silenced.
    • They must be in the YYYY-MM-DDTh:mm:ssZ format that complies with ISO8601.

  • period[n].duration

    • This value defines the duration for which Alerts will be silenced from the applying time.
    • Accepted units: s, m, h.

Annotation​

The SLO Annotations service enables Nobl9 users to add notes to their metrics. For more details, refer to SLO Annotations in the Features section of Nobl9 documentation,

YAML:

apiVersion: n9/v1alpha
kind: Annotation
metadata:
  name:  # unique name of the annotation
  project:  # the name of the project the annoation is attached to
spec:
  slo:  # annotation's objective
  description:  # string, mandatory
  startTime:  # defined start date-time point
  endTime:  # defined end date-time point

Important Notes:

  • metadata.name - a unique annotation name, required for distinguishing project annotations.

  • spec.slo - the name of the SLO the annotation applies to.

  • spec.description - a string (plain text) describing the annotation. The maximum number of characters is 1000.

  • spec.startTime, spec.endTime - these fields define the date-time point where the annotation will be placed in the graph. The values must be in the YYYY-MM-DDTh:mm:ssZ format that complies with ISO8601. If startTime == endTime, the annotation will be placed at a single time point.

DataExport​

Apply the following YAML to create the configuration to export your data from Nobl9. For more details, see the Data Export documentation.

note

DataExport is a premium feature. Contact your Nobl9 sales representative to enable it.

YAML:

apiVersion: n9/v1alpha
kind: DataExport
metadata:
  name: # string
  displayName: # string, optional
  project: # string, optional
spec:
  exportType: S3 | GCS
  spec:
    bucketName: # string
    roleArn: # string

Notes:

  • bucketName: string - required field. The name of the S3 or GCS bucket

  • roleArn: string - required for S3 and Snowflake export types. This is the Amazon Resource Name (ARN) of the role that the Nobl9 agent is assuming to upload files.

Here’s a working example of YAML for exporting your data through sloctl:

apiVersion: n9/v1alpha
kind: DataExport
metadata:
  name: s3-data-export
  displayName: S3 data export
  project: default
spec:
  exportType: S3
  spec:
    bucketName: examplebucket
    roleArn: arn:aws:iam::123456789:role/example

Objective​

Objectives are the thresholds for your SLOs. You can use objectives to define the tolerance levels for your metrics.

info

SLO Objective Unique Identifier - Grace Period Announcement​

Nobl9 is introducing an SLO objective unique identifier to support the same value for different SLIs in the same SLO. As such, Nobl9 is adding a name identifier to each SLO objective to enable uniqueness in error budget calculations. For more detailed information, refer to the SLO Objective Unique Identifier documentation.

YAML:

objectives:
  - displayName: # string, optional
    op: lte | gte | lt | gt  # an accepted comparative method for labeling the SLI
    value: numeric  # value used to compare metric values; all objectives of the SLO must have unique values
    target: numeric [0.0, 1.0)  # budget target for given objective of the SLO
    timeSliceTarget: numeric (0.0, 1.0]  # required only when budgetingMethod is set to Timeslices
    countMetrics:
    # countMetrics {good, total} should be defined only if rawMetric is not set
    # If rawMetric is defined on the SLO level, raw data received from metric source is compared with objective value
    # countMetrics good and total must contain the same source type configuration
        incremental: true | false # mandatory
        good: # value for good occurrences
        total: # value for total occurrences
  - displayName: # string, optional
    value: # numeric
    target: # numeric
    op: lte | gte | lt | gt
    timeSliceTarget: # numeric

Notes:

  • value: numeric - required field. Used to compare values gathered from the metric source.

  • op: string - required field. A mathematical inequality operator; possible values for this field are:

    • lte - less than or equal (<=).

    • gte - greater than or equal (>=).

    • lt - less than (<).

    • gt - greater than (>).

  • target: numeric [0.0, 1.0) - required field. The budget target for the given objective of the SLO.

  • timeSliceTarget: numeric (0.0, 1.0] - required only when budgetingMethod is set to Timeslices.

  • countMetrics: metric - represents the query used for gathering data from metric sources. countMetrics compares two time series, indicating the ratio of the count of good values to total values for the measured occurrences:

    • incremental: required field, boolean - depending on the method of counting data (check the SLO Calculations guide for more details):

      • If set to true (incremental method), we expect the value of a metric to be the current sum of some numerator.

      • If set to false (non-incremental method), we expect it to be the components of the sum.

    • good: received data is used to compare objective (threshold) values to find good values.

    • total: received data is used to compare objective (threshold) values to find a total number of metrics.

note

If the countMetrics field is defined it is not possible to set rawMetric on the SLO level.

Here’s a working YAML example of a countMetric SLO for Prometheus:

apiVersion: n9/v1alpha
kind: SLO
metadata:
  name: webapp-frontend
  displayName: WebApp frontend service
  project: default
spec:
  description: SLO tracking the uptime for our frontend service
  service: webapp-service
  indicator:
    metricSource:
      name: prometheus-source
  timeWindows:
    - unit: Week
      count: 1
      calendar:
        startTime: 2020-01-21 12:30:00
        timeZone: America/New_York
      isRolling: false
  budgetingMethod: Occurrences
  objectives:
    - displayName: string
      op: lte
      value: 0.95
      target: 0.99
      countMetrics:
          incremental: true
          good:
              prometheus:
                  query: "sample query"
          total:
               prometheus:
                  query: "sample query"
  alertPolicies:
    - pagerduty-alert

Project​

Projects are the primary grouping of resources in Nobl9. For more details, refer to the Projects in the Nobl9 Platform section of the documentation.

YAML:

apiVersion: n9/v1alpha
kind: Project
metadata:
  name: my-project  # mandatory
spec:
  description: ""  # optional

Notes:

  • name: string - mandatory field. Can contain only lowercase alphanumeric characters and -; for example, my-project-name.

  • description: string - optional description of the project, for example including details on the team or owner responsible for it or the purpose of creating the project.

If you describe infrastructure as code, you can create a project with the same convention. You can find more details in our Terraform documentation.

RoleBinding​

A single RoleBinding object allows the definition of the relation between exactly one user and exactly one role. Refer to RoleBinding for more details about managing role bindings via sloctl.

YAML:

apiVersion: n9/v1alpha
kind: RoleBinding
metadata:
  name:  # string, role name followed by username; for example, project-owner-adam
spec:
  projectRef:  # referenced project
  roleRef:  # referenced role
  user:  # Okta User ID

Notes:

  • projectRef - optional field. The project in which we want the user to assume the specified role.

  • roleRef - required field. The role that we want the user to assume.

  • user - required field. This is an Okta User ID that can be retrieved from the Nobl9 UI (Settings > Users).

If you describe infrastructure as code, you can manage role bindings with the same convention. You can find more details in our Terraform documentation.

Service​

A service in Nobl9 is a high-level grouping of service level objectives (SLOs). A service can represent a logical service endpoint like an API, a database, an application, or anything else you care about setting an SLO for. Every SLO in Nobl9 is tied to a service, and service can have one or more SLOs.

YAML:

apiVersion: n9/v1alpha
kind: Service
metadata:
  name: # string
  displayName: # string
  project: # string
spec:
  description: # string
  serviceType: # string

Notes:

There are two spec fields for Service (both optional):

  • description - string, up to 1050 characters.

  • serviceType - string, up to 1050 characters.

Here’s a working YAML example of a Service:

apiVersion: n9/v1alpha
kind: Service
metadata:
  name: webapp-service
  displayName: WebApp Service
  project: default
spec:
  description: Service to connect to internal notification system
  serviceType: WebApp

If you describe infrastructure as code, you can create a service with the same convention. You can find more details in our Terraform documentation.

SLO​

An SLO is a target value or range of values for a service that is measured by a service level indicator (SLI). SLOs allow you to define the reliability of your products and services in terms of customer expectations. You can create SLOs for user journeys, internal services, or even infrastructure.

info

SLO Objective Unique Identifier - Grace Period Announcement​

Nobl9 is introducing an SLO objective unique identifier to support the same value for different SLIs in the same SLO. As such, Nobl9 is adding a name identifier to each SLO objective to enable uniqueness in error budget calculations. For more detailed information, refer to the SLO Objective Unique Identifier documentation.

YAML:

apiVersion: n9/v1alpha
kind: SLO
metadata:
  name: string
  displayName: # string, optional
  project: # string
spec:
  composite: # string, optional structure for a composite SLO
    target: # float 64, defined target for the SLO
    burnRateCondition: # if budgetingMethod is set to Timeslices this field should be removed
      value: # float 64, mandatory
      op: gte # string, mandatory / gte is the only value accepted any other value will result in validation error
  budgetingMethod: Occurrences | Timeslices # enum,  mandatory
  description: # string, optional max 1050 characters
  service:  # string, mandatory - name of the service you defined (must be in the same project as the SLO)
  indicator:
    metricSource:
      name: # string, mandatory - name of the data source
      project: # string, optional - if not defined, it is the same project as the SLO
      kind: # string, optional - defaults to "Agent" (possible values: Agent)
    rawMetric: # rawMetric must be defined here once, or defined per each objective
  objectives: # You can define from 1 to 12 objectives per SLO. See the "Objectives" section of this guide for details
  - target: # numeric, first objective defined for the composite SLO (example values)
    op: lte | gte | lt | gt # enum, mandatory
    displayName: # string, optional
    value: # numeric
    rawMetric:
      query:
  - target: # numeric, second objective defined for the composite SLO
    op: lte | gte | lt | gt # enum, mandatory
    displayName: # string, optional
    value: # numeric
    rawMetric:
      query:
  timeWindows:
    # Exactly one of the following, depending on the type of time window:
    # rolling time window
    - unit: Day | Hour | Minute # enum, mandatory
      count: numeric
      isRolling: true
    # or
    # calendar-aligned time window
    - unit: Year | Quarter | Month | Week | Day # enum, mandatory
      count: numeric  # count of time units; for example, count: 7 and unit: Day means 7-day window
      calendar:
        startTime: 2020-01-21 12:30:00  # date with time in 24h format, format without time zone
        timeZone: America/New_York  # name as in IANA Time Zone Database
      isRolling: false  # false or not defined
  alertPolicies:
    - string  # The name of the alert policy associated with this SLO (must be from the same project as the SLO).
              # You can define 0 to 5 alert policies per SLO.
  attachments:
    # You can add up to 20 links to an SLO.
    - displayName: # optional, display name for the title of the link; max. length: 63 characters. The URL is used as a link title when the Display Name field is empty.
      url: # the URL to the service related to the SLO

Defining high-level specs​

  • spec.composite - optional structure that consists the following sub-fields:

    • spec.composite.target - float64.
      Mandatory provided that the spec.composite field is defined.

    • spec.composite.burnRateCondition - optional structure.
      Mandatory provided the spec.budgetingMethod field is set to Occurrences.

      The spec.composite.burnRateCondition field consists the following sub-fields:

      • spec.composite.burnRateCondition.value - mandatory, float64. Has to be a number in the range: (0, 1000> (greater than 0, less than or equal to 1000).

      • spec.composite.burnRateCondition.op - mandatory, string. The only value accepted in this field is gte

    • budgetingMethod: enum (Occurrences | Timeslices) - mandatory.

      • Occurrences method uses a ratio of counts of good events to total events.

      • Timeslices method uses a ratio of good time slices vs. total time slices in a budgeting period.

There are two methods of defining the rawMetric for an SLO:

Method 1 On the spec.indicator level:

  • spec.indicator[n].metricSource: { name string, project string, kind string }

    • identifies the data source (kind: Agent or Direct) used to gather metrics data.
    • project and kind are optional.
    • If a project is specified it is possible to point to a data source from another project than the SLO’s.

  • spec.indicator[n].rawMetric.query - This field won't be returned (for example, when using sloctl get slos command).

    • Even when a query is defined directly on the spec level (spec.indicator.rawMetric) Nobl9 will return MetricSpec defined on the objectives level.
Method 2 On the spec.objectives level:

  • spec.objectives[n].rawMetric.query - optional structure that allows user to set Metric spec per single objective.

    • spec.objectives[n].rawMetric.query - represents the query used for gathering data from metric sources. Raw data is used to compare objective (threshold) values. If rawMetric is defined it is not possible to set countMetrics on the objective level. Refer to Sources for more details about metric specifications for different Integrations.

    • spec.objectives[n].rawMetric.query - the query on the spec level is returned by default (for example, when using sloctl get slos command).

Defining timeWindows​

  • timeWindows[ ] - a list that accepts exactly one item, the rolling or calendar-aligned time window:

    • Rolling time window - minimum duration is 5 minutes, maximum 31 days
    unit: Day | Hour | Minute
     count: numeric
    isRolling: true
    • Calendar-aligned time window - minimum duration is 1 day, maximum 366 days
    unit: Year | Quarter | Month | Week | Day
    count: numeric
    calendar:
      startTime: 2020-01-21 12:30:00  # date with time in a 24h format
      timeZone: America/New_York  # name as in IANA Time Zone Database
      isRolling: false  # for calendar-aligned set to false or do not set

Defining alertPolicies​

  • alertPolicies[ ]: optional field.

    • A list of names of alert policies that can trigger alerts for this SLO when all conditions are met (can contain 0 to 5 items).

    • Alert policies must be created in the same project as the SLO (see AlertPolicy above).

If you describe infrastructure as code, you can define your SLO with the same convention. You can find more details in our Terraform documentation.

Last updated on
Submit Feedback