Chapter 2
Detailed Specification of OpenSLO
Mastery of OpenSLO begins with a deep technical understanding of its specification. This chapter meticulously unpacks the schema, formats, validation mechanisms, and extensibility hooks that empower OpenSLO to serve as both a linchpin for interoperability and a catalyst for reliability automation. Delve into the technical craftsmanship behind OpenSLO and discover how its design enables robust, auditable, and adaptive SLO management for organizations operating at scale.
2.1 YAML Schemas and Supported Fields
OpenSLO's primary specification language leverages YAML due to its human-readable structure and ease of integration with automation tools. The specification's schema defines the arrangement, required fields, optional attributes, and nested objects that form a comprehensive, extensible description of service level objectives (SLOs). Understanding these details is crucial for accurately modeling service reliability data and ensuring interoperability.
At the root level, an OpenSLO YAML document is organized around the slo key, which serves as the primary container for describing a single SLO entity. This root object consolidates metadata, SLO specification parameters, and potential extensions in a unified manner:
slo: name: string (required) description: string (optional) service: name: string (required) owner: string (optional) indicator: ... objective: ... timeWindow: ... tags: [string] (optional) metadata: ... Inside slo, the name field is mandatory and must be a concise, unique identifier for the service-level objective itself. This is fundamental to ensure clear referencing and aggregation across monitoring and compliance systems. The description is optional but highly recommended to provide semantic context for human readers and automated systems.
The service object anchors the SLO to a particular service domain. It includes a mandatory name to identify the service and an optional owner field, generally containing an email or team name, which facilitates notifications and accountability workflows.
The indicator field is a nested object defining the measurable signal that reflects service reliability. OpenSLO supports several indicator types such as ratio, integer, and availability, each with subtype-specific attributes. For example, a ratio indicator uses numerator and denominator query strings, often Prometheus or SQL, to calculate success ratios:
indicator: type: ratio numerator: query_string denominator: query_string All indicator types require their type field to specify the calculation model. This design enforces schema clarity and guards against semantic ambiguity.
The objective component describes the target reliability or performance thresholds. It mandates an operator (>=, <=, >, <) and a target numeric value expressed as a floating-point number between 0 and 1 representing a percentage of success or uptime:
objective: operator: ">=" target: 0.995 Time bounding is managed by the timeWindow object, which confines the measurement period to common units such as 30d (30 days) or 7d (1 week). The field duration is required, and field values must adhere to an ISO 8601 duration subset format:
timeWindow: duration: 30d Additional optional fields can include tags, a list of arbitrary strings for filtering or classification, and metadata, an open map structure allowing users to embed vendor-specific extensions, policy references, or operational annotations.
Nesting is deliberately shallow to maintain human-readability, yet flexible enough to define hierarchical relationships. For instance, the indicator and objective objects serve as sibling nodes under slo, each encapsulating related attributes without excessive substructure.
OpenSLO specifications encourage the use of comments (#) to elucidate field purposes, rationale behind thresholds, or data source assumptions. These comments enhance maintainability without affecting parsing or validation, supporting collaborative environments and audit processes.
Metadata fields are recommended to be standardized when possible, such as using x- prefixes for vendor extensions to prevent collisions. Utilizing metadata effectively can enable alignment with internal compliance frameworks, automated remediation triggers, and integration with incident management platforms.
Required fields enforce strict schema validation, minimizing ambiguity in SLO interpretation. Optional ...
