### Install sloctl in CI/CD Source: https://docs.nobl9.com/slos-as-code/ci-cd Examples for installing and configuring sloctl using either a Docker image or direct binary installation. ```yaml # In your CI/CD configuration: stages: - deploy-slos deploy-slos: stage: deploy-slos image: nobl9/sloctl:latest script: # Set up the authentication configuration - mkdir -p /home/appuser/.config/nobl9 - echo "$N9_CONFIG" > /home/appuser/.config/nobl9/config.toml # Apply SLO definitions using sloctl - sloctl apply -f ./slo-definitions/ ``` ```yaml # In your CI/CD configuration: stages: - deploy-slos deploy-slos: stage: deploy-slos script: # Download and install sloctl - curl -L https://github.com/nobl9/sloctl/releases/latest/download/sloctl_Linux_x86_64.tar.gz | tar xz - chmod +x sloctl - mv sloctl /usr/local/bin/ # Set up configuration - mkdir -p ~/.config/nobl9 - echo "$N9_CONFIG" > ~/.config/nobl9/config.toml # Apply SLO definitions - sloctl apply -f ./slo-definitions/ ``` -------------------------------- ### Example usage of sloctl get alerts Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Various examples demonstrating how to filter alerts by project, service, objective, policy, and time range. ```bash sloctl get alert -A ``` ```bash sloctl get alert --triggered -A ``` ```bash sloctl get alert XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX ``` ```bash sloctl get alert --service authorization-page --service orders-and-payments -p customer-facing-applications ``` ```bash sloctl get alert --resolved --alert-policy slow-burn --slo usersapi -p customer-facing-applications ``` ```bash sloctl get alert --slo usersapi --objective acceptable -p customer-facing-applications ``` ```bash sloctl get alert --slo usersapi --objective acceptable --objective excellent -p customer-facing-applications ``` ```bash sloctl get alert --from 2025-03-22T00:00:00Z --to 2025-03-22T23:59:59Z -A ``` ```bash sloctl get alert --from -A ``` ```bash sloctl get alert --to 2025-03-22T00:00:00Z -A ``` -------------------------------- ### sloctl get Usage Examples Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Common usage patterns for retrieving SLOs and agent credentials. ```bash sloctl get slo streaming-other-slo streaming-latency-slo ``` ```bash sloctl get agents -Ak ``` ```bash sloctl get agents my-agent-1 my-agent-2 ``` -------------------------------- ### Apply AlertSilence with YAML Source: https://docs.nobl9.com/alerting/alert-silence Example of a full AlertSilence configuration including start time, end time, and duration. ```yaml 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 ``` -------------------------------- ### Install sloctl via Go Source: https://docs.nobl9.com/sloctl-user-guide/install-sloctl Install the latest version of sloctl using the Go toolchain. ```bash go install github.com/nobl9/sloctl/cmd/sloctl@latest ``` -------------------------------- ### Example Replay Commands Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Common command-line examples for replaying SLOs using flags, files, or stdin. ```bash sloctl replay my-slo --from=2025-04-07T00:00:00Z sloctl replay -f ./slos-to-replay.yaml sloctl replay <./slos-to-replay.yaml sloctl replay -p customer-facing-applications --from=2025-04-07T00:00:00Z error-rate ``` -------------------------------- ### Install jq Source: https://docs.nobl9.com/sources/add-data-source/amazon-redshift/aws-secrets-manager Installs the jq command-line JSON processor. ```bash brew install jq ``` -------------------------------- ### cURL Request Example Source: https://docs.nobl9.com/api/annotations/get-the-list-of-annotations Example command to fetch annotations using cURL. ```bash curl -L 'https://app.nobl9.com/api/annotations' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' ``` -------------------------------- ### Retrieve UserGroup YAML Object Source: https://docs.nobl9.com/yaml-guide Example structure of a UserGroup YAML object retrieved via the sloctl get usergroups command. ```yaml apiVersion: n9/v1alpha kind: UserGroup metadata: name: my-group spec: displayName: My Group members: - id: account-id # Specify either user account ID ``` -------------------------------- ### Install Homebrew Source: https://docs.nobl9.com/sources/add-data-source/amazon-redshift/aws-secrets-manager Command to install Homebrew on macOS or Linux systems. ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` -------------------------------- ### cURL Request Example Source: https://docs.nobl9.com/api/reports/get-resource-usage-summary-report Example command to fetch the resource usage summary using cURL. ```bash curl -L 'https://app.nobl9.com/api/reports/v1/usage-summary' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' ``` -------------------------------- ### Subcommand Usage Examples Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Examples for retrieving identifiers for data export and direct integrations. ```bash sloctl aws-iam-ids dataexport [global-flags] ``` ```bash sloctl aws-iam-ids direct my-cloudwatch-source [flags] ``` -------------------------------- ### Retrieve Alert YAML Object Source: https://docs.nobl9.com/yaml-guide Example of an Alert object returned by the sloctl get alerts command, representing a triggered notification event. ```yaml apiVersion: n9/v1alpha kind: Alert metadata: name: ********-****-****-****-************ # Alert name identifier project: customer-facing-applications # The name identifier of a project holding the affected SLO organization: flower-market spec: alertPolicy: displayName: Fast Burn name: fast-burn project: customer-facing-applications # The name identifier of a project holding the alert policy conditions: - alertingWindow: 15m0s measurement: averageBurnRate op: gte status: firstMetMetricTime: "2025-07-01T14:19:00Z" lastMetMetricTime: "2025-07-01T15:01:00Z" lastsForMetMetricTime: "2025-07-01T14:19:00Z" value: 2 coolDown: 15m0s coolDownStartedAtMetricTime: "2025-07-01T15:01:00Z" objective: displayName: "Good" name: good # The name identifier of the SLO objective that triggered the alert value: 1 resolutionReason: AlertResolved resolvedClockTime: "2025-07-01T15:17:08Z" resolvedMetricTime: "2025-07-01T15:16:00Z" service: name: orders-any-payments # The name identifier of a service holding the affected SLO project: customer-facing-applications severity: Medium silenceInfo: # Returned if alertSilence was applied at the time the alert was triggered from: "2025-07-01T11:19:09Z" to: "2025-07-01T23:19:09Z" slo: name: api-response-error-rate # The affected SLO name identifier project: customer-facing-applications status: Resolved # Alert status. Can be Canceled | Triggered | Resolved triggeredClockTime: "2025-07-01T14:20:08Z" triggeredMetricTime: "2025-07-01T14:15:08Z" ``` -------------------------------- ### Direct Subcommand Output Example Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Example of the YAML output returned when running the direct subcommand. ```yaml # Example output externalId: a1b2c3d4-5678-90ab-cdef-ghijklmnopqr accountId: 123456789012 ``` -------------------------------- ### Query Parameter Examples Source: https://docs.nobl9.com/api/prometheus-api/query-get Examples of valid values for query parameters used in the instant query request. ```text reliability{project="default"} ``` ```text 2024-01-15T10:30:00Z ``` ```text 30s ``` ```text 10m ``` -------------------------------- ### Working AlertPolicy example Source: https://docs.nobl9.com/yaml-guide A concrete example of an AlertPolicy configuration with multiple conditions and alert methods. ```yaml apiVersion: n9/v1alpha kind: AlertPolicy metadata: name: trigger-alert-policy-bad-delayed-multi project: trigger-alert annotations: registry: docker.io visibility: internal 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" alertMethods: - metadata: name: webhook-global-notification project: server-production - metadata: name: webhook-notification ``` -------------------------------- ### Configure Prometheus countMetric for SLO Source: https://docs.nobl9.com/yaml-guide Example configuration for an SLO using Prometheus as a metric source with the Occurrences budgeting method. ```yaml 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 value: 0.95 target: 0.99 countMetrics: incremental: true good: prometheus: query: "sample query" total: prometheus: query: "sample query" alertPolicies: - pagerduty-alert ``` -------------------------------- ### SLO History Report YAML Configuration Source: https://docs.nobl9.com/yaml-guide Example structure for an SLO History report, demonstrating mandatory metadata, filtering, and time frame settings. ```yaml apiVersion: n9/v1alpha kind: Report metadata: name: string # Mandatory displayName: string # Optional spec: shared: true # Optional, boolean, defaults to false filters: # You must define at least one level of filtering from these three: projects, services, slos projects: - project-1 # Mandatory if filtering by projects services: - name: string # Mandatory if filtering by services project: string # Mandatory if filtering by services slos: - name: string # Mandatory if filtering by slos project: string # Mandatory if filtering by slos labels: "key_1": - "value_1" - "value_2" "key_2": - "value_1" - "value_2" sloHistory: timeFrame: # Mandatory, rolling or calendar needed rolling: count: 1 # valid 'unit' and 'count' pairs are: 1 Week, 2 Week, 4 Week, 1 Month, 1 Quarter, 1 Year unit: Week # Option 1 to configure timeFrame #timeFrame: # calendar: # 'calendar' must contain either 'unit' and 'count' pair or 'from' and 'to' pair # count: 1 # valid 'unit' and 'count' pairs are: 1 Week, 1 Month, 1 Quarter, 1 Year # unit: Week # Option 2 to configure timeFrame #timeFrame: # calendar: # 'calendar' must contain either 'unit' and 'count' pair or 'from' and 'to' pair # from: 2024-09-29 # to: 2024-10-29 timeZone: "America/New_York" # Mandatory ``` -------------------------------- ### Define Calendar-Aligned Time Window Source: https://docs.nobl9.com/yaml-guide Configuration structure for a calendar-aligned time window, requiring a unit, count, start time, and time zone, with isRolling set to false. ```yaml 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 ``` -------------------------------- ### Handle malformed JSON payload error Source: https://docs.nobl9.com/yaml-guide Example of the error message returned by sloctl when label formatting is incorrect. ```text Error: malformed JSON payload - pass single list of valid JSON objects. ``` -------------------------------- ### Define a Reliability Roll-up Report Source: https://docs.nobl9.com/yaml-guide Example configuration for a filter-driven reliability roll-up report using the n9/v1alpha API version. ```yaml - apiVersion: n9/v1alpha kind: Report metadata: name: reliability-rollup-report # Mandatory displayName: Reliability Roll-up # Optional spec: shared: true # Optional, boolean, defaults to false filters: # Optional. Mutually exclusive with reliabilityRollup.customHierarchy. When set, the report hierarchy is generated automatically from these filters. projects: # Optional - project-1 - project-2 services: # Optional - name: service-1 # Mandatory if filtering by services project: project-1 # Mandatory if filtering by services reliabilityRollup: # Mandatory timeFrame: # Mandatory. Use exactly one of rolling or calendar rolling: # Optional, mutually exclusive with calendar unit: Week # Mandatory. One of: Day | Week | Month | Quarter | Year count: 1 # Mandatory. Number of units in the rolling window timeZone: Europe/Warsaw # Mandatory. IANA time zone name ``` -------------------------------- ### Run the Go Example Source: https://docs.nobl9.com/slos-as-code/nobl9-go Commands to prepare dependencies and execute the Go application. ```bash go mod tidy go run main.go ``` -------------------------------- ### Initialize Go Project Source: https://docs.nobl9.com/slos-as-code/nobl9-go Commands to set up a new Go module and add the Nobl9 SDK as a dependency. ```bash # Creates a new Go module. go mod init nobl9-go-example # Adds nobl9-go as a dependency to your module. go get github.com/nobl9/nobl9-go # Create an entrypoint for your application. touch main.go ``` -------------------------------- ### Manage Nobl9 Resources with Go SDK Source: https://docs.nobl9.com/slos-as-code/nobl9-go Example demonstrating how to initialize a client, read objects from YAML, define new resources, validate, apply, and delete them. ```go package main import ( "context" "encoding/json" "fmt" "log" "github.com/nobl9/nobl9-go/manifest" "github.com/nobl9/nobl9-go/manifest/v1alpha" "github.com/nobl9/nobl9-go/manifest/v1alpha/project" "github.com/nobl9/nobl9-go/manifest/v1alpha/service" "github.com/nobl9/nobl9-go/sdk" objectsV1 "github.com/nobl9/nobl9-go/sdk/endpoints/objects/v1" objectsV2 "github.com/nobl9/nobl9-go/sdk/endpoints/objects/v2" ) func main() { ctx := context.Background() client, err := sdk.DefaultClient() if err != nil { log.Fatalf("failed to create sdk client, err: %v", err) } // Read from a file, URL, or glob pattern. objects, err := sdk.ReadObjects(ctx, "./project.yaml") if err != nil { log.Fatalf("failed to read project.yaml file, err: %v", err) } // Use manifest.FilterByKind to extract specific objects from the manifest.Object slice. myProject := manifest.FilterByKind[project.Project](objects)[0] // Define objects in code. myService := service.New( service.Metadata{ Name: "my-service", DisplayName: "My Service", Project: myProject.GetName(), Labels: v1alpha.Labels{ "team": []string{"green", "orange"}, "region": []string{"eu-central-1"}, }, }, service.Spec{ Description: "Example service", }, ) objects = append(objects, myService) // Verify the objects. if errs := manifest.Validate(objects); len(errs) > 0 { log.Fatalf("service validation failed, errors: %v", errs) } // Apply the objects. if err = client.Objects().V2().Apply(ctx, objectsV2.ApplyRequest{Objects: objects}); err != nil { log.Fatalf("failed to apply objects, err: %v", err) } // Get the applied resources. services, err := client.Objects().V1().GetV1alphaServices(ctx, objectsV1.GetServicesRequest{ Project: myProject.GetName(), Names: []string{myService.GetName()}, }) if err != nil { log.Fatalf("failed to get services, err: %v", err) } projects, err := client.Objects().V1().GetV1alphaProjects(ctx, objectsV1.GetProjectsRequest{ Names: []string{myProject.GetName()}, }) if err != nil { log.Fatalf("failed to get projects, err: %v", err) } // Aggregate objects back into manifest.Objects slice. appliedObjects := make([]manifest.Object, 0, len(services)+len(projects)) for _, service := range services { appliedObjects = append(appliedObjects, service) } for _, project := range projects { appliedObjects = append(appliedObjects, project) } // Print JSON representation of these objects. data, err := json.MarshalIndent(appliedObjects, "", " ") if err != nil { log.Fatalf("failed to marshal objects, err: %v", err) } fmt.Println(string(data)) // Delete resources. if err = client.Objects().V2().Delete(ctx, objectsV2.DeleteRequest{Objects: objects}); err != nil { log.Fatalf("failed to delete objects, err: %v", err) } } ``` -------------------------------- ### Get budget adjustment events Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Examples for retrieving budget adjustment events with and without SLO filtering. ```bash sloctl budgetadjustments events get --adjustment-name=my-adjustment --from=2024-09-23T00:45:00Z --to=2024-09-23T20:46:00Z ``` ```bash sloctl budgetadjustments events get --adjustment-name=my-adjustment --from=2024-09-23T00:45:00Z --to=2024-09-23T20:46:00Z --slo-project=my-project--slo-name=my-slo ``` -------------------------------- ### Initialize and Run Go Query Source: https://docs.nobl9.com/prometheus-api/consuming-the-api Commands to initialize the Go module, install dependencies, and execute the query script. ```bash go mod init query_budget go get github.com/nobl9/nobl9-go github.com/prometheus/common go run . my-project my-slo ``` -------------------------------- ### Run sloctl with Config File Source: https://docs.nobl9.com/sloctl-user-guide/configure-sloctl Example of running a command by bind mounting the local configuration directory into the container. ```bash docker run -v ~/.config/nobl9:/root/.config/nobl9 nobl9/sloctl:latest get slos ``` -------------------------------- ### Update adjustment events request body Source: https://docs.nobl9.com/api/adjustments/update-adjustment-events Example JSON payload for updating adjustment events, requiring event start and end times. ```json [ { "update": { "eventStart": "2024-06-05T13:00:00Z", "eventEnd": "2024-06-05T13:00:00Z" }, "slos": [ { "project": "first-sample-project", "name": "first-sample-slo-name" }, { "project": "second-sample-project", "name": "second-sample-slo-name" } ], "eventStart": "2024-06-05T13:00:00Z", "eventEnd": "2024-06-05T13:00:00Z" } ] ``` -------------------------------- ### Configuration context operations Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Examples of various configuration management commands. ```bash sloctl config add-context ``` ```bash sloctl config current-context -v ``` ```bash sloctl config current-user -o ``` ```bash sloctl config delete-context my-context ``` ```bash sloctl config get-contexts my-context -v ``` ```bash sloctl config rename-context my-context my-renamed-context ``` ```bash sloctl config use-context my-context ``` -------------------------------- ### OpsGenie YAML configuration with GenieKey and Basic auth Source: https://docs.nobl9.com/alerting/alert-methods/opsgenie Examples demonstrating how to configure the OpsGenie alert method using either Basic or GenieKey authentication. ```yaml # Opsgenie Alert Method with Basic - apiVersion: n9/v1alpha kind: AlertMethod metadata: name: opsgenie displayName: Opsgenie Alert Method project: default annotations: area: latency env: prod region: us team: sales spec: description: Example Opsgenie Alert Method opsgenie: auth: Basic 123 url: https://api.opsgenie.com # Opsgenie Alert Method with GenieKey - apiVersion: n9/v1alpha kind: AlertMethod metadata: name: opsgenie displayName: Opsgenie Alert Method project: default annotations: area: latency env: prod region: us team: sales spec: description: Example Opsgenie Alert Method opsgenie: auth: GenieKey 123 url: https://api.opsgenie.com ``` -------------------------------- ### Manual installation on MacOS Source: https://docs.nobl9.com/sloctl-user-guide/install-sloctl Commands to manually configure the downloaded sloctl binary for execution on MacOS. ```bash sudo mkdir -p /usr/local/bin # Ensure the /usr/local/bin directory exists to store the sloctl binary sudo cp ~/Downloads/sloctl /usr/local/bin/ # Move the binary to the Downloads folder sudo chmod a+rx /usr/local/bin/sloctl # Ensure the stored sloctl binary is properly configured to be executable and accessible to all users open /usr/local/bin # Navigate to the bin folder in Finder ``` -------------------------------- ### sloctl get Syntax Source: https://docs.nobl9.com/sloctl-user-guide/sloctl-root-commands?adjustments-events=update Basic syntax for executing the get command. ```bash sloctl get [command] ``` -------------------------------- ### Response Schema Example Source: https://docs.nobl9.com/api/organization-status/send-issue-from-external-telemetry Example of a successful response body returned by the API. ```json { "signals": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "componentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "occurredAt": "2024-07-29T15:51:28.071Z", "comment": "string", "reportedAt": "2024-07-29T15:51:28.071Z", "reportedBy": "string", "organization": "string", "type": "external", "metadata": {} } ], "message": "Issue from external telemetry created successfully" } ``` -------------------------------- ### Set up authentication credentials Source: https://docs.nobl9.com/slos-as-code/ci-cd Export client credentials as environment variables for use in CI/CD pipelines. ```bash # Store credentials in a secure CI/CD variable export N9_CLIENT_ID="your-client-id" export N9_CLIENT_SECRET="your-client-secret" ``` -------------------------------- ### Configure and Run the Query Script Source: https://docs.nobl9.com/prometheus-api/consuming-the-api Set the required environment variables and execute the script with project and SLO arguments. ```bash export NOBL9_CLIENT_ID=... NOBL9_CLIENT_SECRET=... export NOBL9_PROM_URL=https://app.nobl9.com/api/prometheus/v1 node query_budget.mjs my-project my-slo ``` -------------------------------- ### Install AWS CLI Source: https://docs.nobl9.com/sources/add-data-source/amazon-redshift/aws-secrets-manager Installs the AWS Command Line Interface using Homebrew. ```bash brew install awscli ``` -------------------------------- ### Initialize and Run Python Query Source: https://docs.nobl9.com/prometheus-api/consuming-the-api Commands to install the prometheus-api-client library, set required environment variables, and run the script. ```bash pip install prometheus-api-client export NOBL9_CLIENT_ID=... NOBL9_CLIENT_SECRET=... export NOBL9_PROM_URL=https://app.nobl9.com/api/prometheus/v1 python query_budget.py my-project my-slo ``` -------------------------------- ### Troubleshoot Homebrew installation Source: https://docs.nobl9.com/sloctl-user-guide/install-sloctl Commands to resolve common Homebrew errors during the installation process. ```bash brew trust nobl9/sloctl ``` ```bash brew update-reset ```