bun

package module
v1.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 21, 2019 License: Unlicense Imports: 14 Imported by: 0

README

Bun

DC/OS diagnostics bundle analysis tool

Installation

Download binaries from the release page or install from source:

$ go get github.com/adyatlov/bun/bun

Usage

$ mkdir bundle
$ unzip bundle.zip -d bundle
$ cd bundle
bundle$ bun 
[PROBLEM] "dcos-version" - Versions are different.
---------------
Problem details
---------------
master 172.20.0.23 has DC/OS version 1.11.0
master 172.20.0.24 has DC/OS version 1.11.0
agent 172.20.0.27 has DC/OS version 1.11.0
agent 172.20.0.28 has DC/OS version 1.11.0
agent 172.20.0.29 has DC/OS version 1.11.0
agent 172.20.0.21 has DC/OS version 1.10.1
agent 172.20.0.25 has DC/OS version 1.11.0
public agent 172.20.0.26 has DC/OS version 1.11.0

[PROBLEM] "health" - Problems were found.
---------------
Problem details
---------------
agent 172.20.0.21: The following components are not healthy:
dcos-docker-gc.service: health = 1

[OK] "mesos-actor-mailboxes" - All Mesos actors are fine.
[OK] "node-count" - Masters: 3, Agents: 5, Public Agents: 1, Total: 9

You can use the -p flag if you do not want to change a current directory:

bun -p <path-to-bundle-directory>

Adding new checks

Each check uses one or more bundle files. Please, refer to the filetypes/files_type_yaml.go file to find out a name of the file type by the file name and vice versa.

Simple search check

To add a simple check which fails when a specified string is found in a specified file of a specified type, add a YAML definition to the YAML document in the checks/search_checks_yaml.go file:

...
- name: disk-space-exhibitor
  description: Check disk space errors in Exhibitor logs
  fileTypeName: exhibitor-log
  searchString: Failed to remove rootfs mount point
Check if a certain condition is fulfilled on each node

If you would like to check if a certain condition is fulfilled on each node of a certain role (i.e.: master, agent or public agent), please use the bun.CheckBuilder with a default aggregate function:

package health

import (
	"fmt"
	"github.com/adyatlov/bun/filetypes"
	"strings"

	"github.com/adyatlov/bun"
)

func init() {
	builder := bun.CheckBuilder{
		Name:                    "diagnostics-health",
		Description:             "Check if all DC/OS components are healthy",
		CollectFromMasters:      collect,
		CollectFromAgents:       collect,
		CollectFromPublicAgents: collect,
		Aggregate:               bun.DefaultAggregate,
	}
	check := builder.Build()
	bun.RegisterCheck(check)
}

func collect(host bun.Host) (ok bool, details interface{}, err error) {
	h := filetypes.Host{}
	if err = host.ReadJSON("diagnostics-health", &h); err != nil {
		return
	}
	unhealthy := []string{}
	for _, u := range h.Units {
		if u.Health != 0 {
			unhealthy = append(unhealthy,
				fmt.Sprintf("%v: health = %v", u.ID, u.Health))
		}
	}
	if len(unhealthy) > 0 {
		details = fmt.Sprintf("The following components are not healthy:\n%v",
			strings.Join(unhealthy, "\n"))
		ok = false
	} else {
		ok = true
	}
	return
}
More complex checks

If you need a check which requires analysis of a collected data, you can use a custom aggregate function:

package dcosversion

import (
	"fmt"
	"github.com/adyatlov/bun"
	"github.com/adyatlov/bun/filetypes"
)

func init() {
	builder := bun.CheckBuilder{
		Name: "dcos-version",
		Description: "Verify that all hosts in the cluster have the " +
			"same DC/OS version installed",
		CollectFromMasters:      collect,
		CollectFromAgents:       collect,
		CollectFromPublicAgents: collect,
		Aggregate:               aggregate,
	}
	check := builder.Build()
	bun.RegisterCheck(check)
}

func collect(host bun.Host) (ok bool, details interface{}, err error) {
	v := filetypes.Version{}
	if err = host.ReadJSON("dcos-version", &v); err != nil {
		return
	}
	details = v.Version
	ok = true
	return
}

func aggregate(c *bun.Check, b bun.CheckBuilder) {
	version := ""
	// Compare versions
	details := []string{}
	ok := true
	for _, r := range b.OKs {
		v := r.Details.(string)
		if version == "" {
			version = v
		}
		if v != version {
			ok = false
		}
		details = append(details, fmt.Sprintf("%v %v has DC/OS version %v",
			r.Host.Type, r.Host.IP, v))
	}
	// No need to interpret problems, as we didn't create it in the host check.
	if ok {
		c.OKs = details
		c.Summary = fmt.Sprintf("All versions are the same: %v.", version)
	} else {
		c.Problems = details
		c.Summary = "Versions are different."
	}
}

Feedback

Please, report bugs and share your ideas for new features via the issue page.

Contributing

Pull requests are welcome.

Documentation

Index

Constants

View Source 
const (
	// SUndefined means that the check wasn't performed successfully.
	SUndefined Status = "UNDEFINED"
	// SOK means that the bundle passed the check.
	SOK = "OK"
	// SProblem means that the bundle failed to pass the check.
	SProblem = "PROBLEM"
)
View Source 
const (
	// DTRoot is a bundle root directory
	DTRoot DirType = "root"
	// DTMaster directory
	DTMaster = "master"
	// DTAgent direrctory
	DTAgent = "agent"
	// DTPublicAgent directory
	DTPublicAgent = "public agent"
)
View Source 
const (
	// CTJson represents CTJson files.
	CTJson ContentType = "JSON"
	// CTJournal represents CTJournal files.
	CTJournal = "journal"
	// CTDmesg represents dmesg files.
	CTDmesg = "dmesg"
	// CTOutput is a output of a command.
	CTOutput = "output"
	//CTOther file types
	CTOther = "other"
)
View Source 
const MsgErr = "Error(s) occurred while performing the check."

MsgErr is a standard message used in the check summary when errors occures during the check.

Variables

This section is empty.

Functions

func DefaultAggregate added in v1.8.0 

func DefaultAggregate(c *Check, b CheckBuilder)

Default implementation of the Aggregate function. It assumes that the implementations of the CheckHost function return Result Details as a string or nil.

func RegisterCheck 

func RegisterCheck(c Check)

RegisterCheck registers a new check to make it discoverable for consumers.

func RegisterFileType 

func RegisterFileType(f FileType)

RegisterFileType adds the file type to the filetype registry. It panics if the file type with the same name is already registered.

Types

type Aggregate added in v1.8.0 

type Aggregate func(*Check, CheckBuilder)

Aggregate check reults.

type Bundle 

type Bundle struct {
	Hosts        map[string]Host // IP to Host map
	Masters      map[string]Host
	Agents       map[string]Host
	PublicAgents map[string]Host
	// contains filtered or unexported fields
}

Bundle describes DC/OS diagnostics bundle.

func NewBundle 

func NewBundle(path string) (Bundle, error)

NewBundle creates new Bundle

func (Bundle) FindLine added in v1.8.0 

func (d Bundle) FindLine(t string, s string) (n int, l string, err error)

FindLine returns a number and a content of the first line in a file of a type t which contains a substring s. If the line is not found, n == 0.

func (Bundle) OpenFile 

func (d Bundle) OpenFile(typeName string) (File, error)

OpenFile opens the files of the typeName file type. If the file is not found, it tries to open it from a correspondent .gzip archive. If the .gzip archive is not found as well then returns an error. Caller is responsible for closing the file.

func (Bundle) ReadJSON added in v1.6.0 

func (d Bundle) ReadJSON(typeName string, v interface{}) error

ReadJSON reads JSON-encoded data from the bundle file and stores the result in the value pointed to by v.

type Check 

type Check struct {
	Name        string               // Required
	Description string               // Optional
	CheckFunc   func(*Check, Bundle) // Required
	Status      Status               // Do not set
	Summary     string               // Do not set
	Problems    []string             // Do not set
	Errors      []string             // Do not set
	OKs         []string             // Do not set
}

Check cheks some aspect of the DC/OS cluster analyzing its diagnostics bundle. Checks can be registered in the check registry with the egisterCheck function. Check is not supposed to be run more than one time.

func Checks 

func Checks() []Check

Checks Returns all registered checks.

func GetCheck added in v1.6.0 

func GetCheck(name string) Check

GetCheck returns check by name.

func (*Check) Run added in v1.6.0 

func (c *Check) Run(b Bundle)

Run runs the check.

type CheckBuilder added in v1.6.0 

type CheckBuilder struct {
	Name                    string    // Required
	Description             string    // Optional
	CollectFromMasters      CheckHost // At least one of
	CollectFromAgents       CheckHost // the Collect... functions
	CollectFromPublicAgents CheckHost // are required
	ProblemSummary          string    // Optional
	OKSummary               string    // Optional
	Aggregate               Aggregate // Implement if the default is not sufficient
	Problems                []Result  // Do not set
	OKs                     []Result  // Do not set
}

CheckBuilder helps to create checks.

func (*CheckBuilder) Build added in v1.6.0 

func (b *CheckBuilder) Build() Check

Build returns a Check

type CheckHost added in v1.6.0 

type CheckHost func(Host) (bool, interface{}, error)

CheckHost checks an individual host. It returns status, details, and error if the function cannot perform a check. If the returned error is not nil, then the status is ignored.

type ContentType 

type ContentType string

ContentType defines type of the content in the bundle file.

type DirType added in v1.8.0 

type DirType string

DirType represent different types of the hosts.

type File added in v1.2.0 

type File interface {
	io.ReadCloser
	Name() string
}

File is a safe way to access bundle files.

type FileType 

type FileType struct {
	Name        string      `yaml:"name"`
	ContentType ContentType `yaml:"contentType"`
	Paths       []string    `yaml:"paths"`
	Description string      `yaml:"description"`
	// DirTypes defines on which host types this file can be found.
	// For example, dcos-marathon.service file can be found only on the masters.
	DirTypes []DirType `yaml:"dirTypes"`
}

FileType Describes a kind of files in the bundle (e.g. dcos-marathon.service).

func GetFileType 

func GetFileType(typeName string) FileType

GetFileType returns a file type by its name. It panics if the file type is not in the registry.

type Host 

type Host struct {
	IP string
	// contains filtered or unexported fields
}

Host represents a host in a DC/OS cluster.

func (Host) FindLine added in v1.8.0 

func (d Host) FindLine(t string, s string) (n int, l string, err error)

FindLine returns a number and a content of the first line in a file of a type t which contains a substring s. If the line is not found, n == 0.

func (Host) OpenFile 

func (d Host) OpenFile(typeName string) (File, error)

OpenFile opens the files of the typeName file type. If the file is not found, it tries to open it from a correspondent .gzip archive. If the .gzip archive is not found as well then returns an error. Caller is responsible for closing the file.

func (Host) ReadJSON added in v1.6.0 

func (d Host) ReadJSON(typeName string, v interface{}) error

ReadJSON reads JSON-encoded data from the bundle file and stores the result in the value pointed to by v.

type Result added in v1.6.0 

type Result struct {
	Host    Host
	OK      bool
	Details interface{}
	Err     error
}

Result hols results of the CheckHost function.

type SearchCheckBuilder added in v1.8.0 

type SearchCheckBuilder struct {
	Name         string `yaml:"name"`         // Required
	Description  string `yaml:"description"`  // Optional
	FileTypeName string `yaml:"fileTypeName"` // Required
	SearchString string `yaml:"searchString"` // Required
}

SearchCheckBuilder builds a check which searches for the specified string in the the specified files. If the pattern is found, the check is considered problematic. The number of the found line and its content appear in the Check.Problems of the check. The check searches only for the first appearance of the line.

func (SearchCheckBuilder) Build added in v1.8.0 

func (b SearchCheckBuilder) Build() Check

Build creates a bun.Check.

type Status 

type Status string

Status defines possible check outcomes.

Source Files

View all Source files

Directories

Path Synopsis
bun
cmd
dcosversion
health
marathon/deployments
mesos/actormailboxes
nodecount

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.