runbook

Documentation

Overview

Package runbook implements the SRE runbook library and claw-ops auto-execution engine. Runbooks are Markdown files with a YAML front matter header that describes the trigger condition and ordered action steps.

CLI usage:

nself runbook list
nself runbook run <id>
nself runbook test <id>   — dry-run mode, prints steps without executing

Index

• Constants
• type Executor
  • func New(runbookDir string, dryRun bool) *Executor
  • func (e *Executor) Execute(ctx context.Context, id string, alertVars map[string]string) error
  • func (e *Executor) List(ctx context.Context) ([]Runbook, error)
• type Runbook
• type RunbookStep
• type RunbookTrigger

Constants

const DefaultRunbookDir = "runbooks"

DefaultRunbookDir is the path (relative to the monitoring plugin directory) where runbooks are stored. The CLI resolves this against the installed monitoring plugin path at runtime.

Types

type Executor

type Executor struct {
	// RunbookDir is the absolute path to the directory containing .md runbook files.
	RunbookDir string
	// DryRun prevents any action from being taken; steps are only logged.
	DryRun bool
	// Out receives human-readable execution output (defaults to os.Stdout).
	Out io.Writer
	// Log is the structured logger; defaults to slog.Default().
	Log *slog.Logger
	// HTTPClient is used for Slack webhook calls.
	HTTPClient *http.Client
}

Executor loads and executes SRE runbooks.

func New

func New(runbookDir string, dryRun bool) *Executor

New creates an Executor with sane defaults.

func (*Executor) Execute

func (e *Executor) Execute(ctx context.Context, id string, alertVars map[string]string) error

Execute loads the runbook with the given ID and runs its steps in order. Steps marked requires_confirmation: true are skipped in dry-run mode and require an explicit Confirm callback in non-dry-run mode.

When alertVars contains key/value pairs (e.g. from an Alertmanager webhook), template placeholders {{ key }} in step params are replaced before execution.

func (*Executor) List

func (e *Executor) List(ctx context.Context) ([]Runbook, error)

List returns all runbooks found in RunbookDir, sorted by ID.

type Runbook

type Runbook struct {
	// ID uniquely identifies the runbook (from front matter).
	ID string `yaml:"id"`
	// Title is the human-readable name.
	Title string `yaml:"title"`
	// Trigger describes the Grafana alert that fires this runbook.
	Trigger RunbookTrigger `yaml:"trigger"`
	// Steps is the ordered list of actions to execute.
	Steps []RunbookStep `yaml:"steps"`
}

Runbook is the parsed representation of a runbook Markdown file.

type RunbookStep

type RunbookStep struct {
	Action               string            `yaml:"action"`
	Params               map[string]string `yaml:"params"`
	RequiresConfirmation bool              `yaml:"requires_confirmation"`
}

RunbookStep is a single action within a runbook.

type RunbookTrigger

type RunbookTrigger struct {
	Alert    string `yaml:"alert"`
	Severity string `yaml:"severity"`
}

RunbookTrigger describes the alert condition that activates this runbook.