Categorygithub.com/cognusion/go-health
modulepackage
1.1.0
Repository: https://github.com/cognusion/go-health.git
Documentation: pkg.go.dev

# README

health

import "github.com/cognusion/go-health"

Overview

Package health provides standardized means for generating healthchecks, and consuming them from JSON. The included schema files allow for validation of generation, regardless of the source.

Index

Package files

checksandmetrics.go health.go schema.go status.go statusregistry.go

Constants

const (
    OK       = StatusString("OK")
    UP       = StatusString("UP")
    WARNING  = StatusString("WARNING")
    BAD      = StatusString("BAD")
    DOWN     = StatusString("DOWN")
    CRITICAL = StatusString("CRITICAL")
    UNKNOWN  = StatusString("UNKNOWN")
    ERROR    = StatusString("ERROR")
)

Status constants to prevent fat-fingered-oopsies

Variables

var (
    // ErrNoSuchEntryError is returned when the requested element does not exist in the Registry
    ErrNoSuchEntryError = errors.New("no such element exists")
)
var SchemaJSON = []byte(`
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "http://example.com/product.schema.json",
    "title": "Go Healthcheck",
    "description": "The Go Healthcheck (health.Check) is output by HTTP services wishing to provide consumable healthcheck output",
    "type": "object",
    "properties": {
        "overallStatus": {
      "description": "The declared status of the system",
      "type": "string",
      "enum": [
        "OK",
        "WARNING",
        "ERROR",
                "BAD",
                "CRITICAL",
                "UNKNOWN"
      ]
    },
    "metrics": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/metric"
      }
    },
    "services": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/service"
      }
    },
    "systems": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/system"
      }
    }
  },
  "required": [
    "overallStatus"
  ],
  "definitions": {
    "health": {
      "type": "object",
      "required": [
        "name"
      ],
      "additionalProperties": true,
      "properties": {
        "name": {
          "type": "string",
          "description": "The name of the service"
        },
        "status": {
          "description": "The declared status of the service",
          "type": "string",
          "enum": [
            "OK",
                        "UP",
            "WARNING",
                        "ERROR",
                        "BAD",
                        "DOWN",
                        "CRITICAL",
                        "UNKNOWN"
          ]
        },
        "timeStamp": {
          "description": "The UNIX epoch timestamp for when this value was last fetched",
          "type": ["integer", "null"]
        },
        "timeout": {
          "description": "The number of milliseconds allowed to lapse between 'timeStamp' and 'now' before the metric is declared stale",
          "type": ["integer", "null"]
        },
        "message": {
            "type": ["string", "null"],
          "description": "A message explaining why the status is what it is (often exception message)"
        }
      }
    },
    "metric": {
      "type": "object",
      "required": [
        "name",
        "value"
      ],
      "extends" : {
        "$ref": "#/definitions/health"
      },
      "allOf": [{ "$ref": "#/definitions/health" }],
      "additionalProperties": true,
      "properties": {
        "value": {
          "description": "The current value for this metric",
          "type": "number"
        },
        "expectedValue": {
          "description": "The declared value that was expected for this metric",
          "type": ["number", "null"]
        },
        "minValue": {
          "description": "The declared minimum value that for this metric (graph floor)",
          "type": ["number", "null"]
        },
        "maxValue": {
          "description": "The declared maximum value that for this metric (graph ceiling)",
          "type": ["number", "null"]
        },
        "warnOver": {
          "description": "The value at which exceeding values generate WARNING status (graph yellow-line)",
          "type": ["number", "null"]
        },
        "badOver": {
          "description": "The value at which exceeding values generate CRITICAL status (graph red-line)",
          "type": ["number", "null"]
        }
      }
    },
    "service": {
      "type": "object",
      "required": [
        "name",
        "status"
      ],
      "extends" : {
        "$ref": "#/definitions/health"
      },
      "allOf": [{ "$ref": "#/definitions/health" }],
      "additionalProperties": true,
      "properties": {
      }
    },
    "system": {
      "type": "object",
      "required": [
        "name"
      ],
      "extends" : {
        "$ref": "#/definitions/health"
      },
      "allOf": [{ "$ref": "#/definitions/health" }],
      "additionalProperties": true,
      "properties": {
      }
    }
  }
}
`)

SchemaJSON was generated from schema.json at Sun Apr 17 12:23:48 PM EDT 2022

func Checks

func Checks(n *nagios.Nagios, maxAge int64, checkMap []interface{}, noisy bool)

Checks takes a status document, escalate the status, and appends Nagios-compatible information to the message

func Metrics

func Metrics(n *nagios.Nagios, checkMap []interface{}, noisy bool)

Metrics takes a "metrics" document and appends Nagios-compatible metrics information to the message

func SafeLabel

func SafeLabel(label string) string

SafeLabel returns a label that is safe to use with modern RRD

func ValidateJSON

func ValidateJSON(jsonBody string) error

ValidateJSON runs provided JSON against the JSON-Schema validator

type Check

type Check struct {
    // OverallStatus must be one of OK,WARNING,BAD/ERROR/CRITICAL, or UNKNOWN
    OverallStatus string                 `json:"overallStatus,omitempty"`
    Services      []Status               `json:"services,omitempty"`
    Systems       []Status               `json:"systems,omitempty"`
    Metrics       []Status               `json:"metrics,omitempty"`
    Properties    map[string]interface{} `json:"properties,omitempty"`
}

Check is a type used to define healthcheck statuses

func NewCheck

func NewCheck() Check

NewCheck returns an empty Check

func NewCheckfromJSON

func NewCheckfromJSON(hcjson []byte) (Check, error)

NewCheckfromJSON returns an Check populated from an Check JSON

func (*Check) AddMetric

func (s *Check) AddMetric(status *Status)

AddMetric adds the provided Status to the Metrics array

func (*Check) AddService

func (s *Check) AddService(status *Status)

AddService adds the provided Status to the Services array

func (*Check) AddSystem

func (s *Check) AddSystem(status *Status)

AddSystem adds the provided Status to the Systems array

func (*Check) Calculate

func (s *Check) Calculate()

Calculate walks the tree and updates OverallStatus if applicable

func (*Check) JSON

func (s *Check) JSON() string

JSON returns the JSON-encoded version of the Check

func (*Check) Merge

func (s *Check) Merge(hc *Check)

Merge integrates one Check into this Check. Does not merge metrics. Does not dedupe

func (*Check) PrefixedMerge

func (s *Check) PrefixedMerge(prefix string, hc *Check)

PrefixedMerge integrates one Check into this Check, prefixing all named items in the source hc before merging.

func (*Check) Terse

func (s *Check) Terse() string

Terse returns the JSON-encoded version of just the overall status of the Check

func (*Check) Validate

func (s *Check) Validate() error

Validate runs the Check.JSON() output against a JSON-Schema validator

type JSON

type JSON map[string]interface{}

JSON is an encapsulating type for "jmap"-based structures

type Status

type Status struct {
    // Name is univerally required
    Name string `json:"name,omitempty"`
    // Status is universally required, one of: OK,WARNING,
    // BAD/ERROR/CRITICAL, or UNKNOWN
    Status string `json:"status,omitempty"`
    // Value is optional for all but Metrics, and is used to convey a
    // numeric-type representation
    Value interface{} `json:"value,omitempty"`
    // ExpectedValue is optional, generally used with Services to represent what
    // Value should be, to understand deviations
    ExpectedValue interface{} `json:"expectedValue,omitempty"`
    // WarnOver is only for Metrics, and is used to represent the Value at which a
    // WARNING state will be triggered
    WarnOver interface{} `json:"warnOver,omitempty"`
    // BadOver is ony for Metrics, and is used to represent the Value at which a
    // CRITICAL state will be triggered
    BadOver interface{} `json:"badOver,omitempty"`
    // TimeStamp is optional, and is used to convey the time the Status or Value
    // was retrieved
    TimeStamp *time.Time `json:"timestamp,omitempty"`
    // TimeOut is optional, and is used to set the amount of time TimeStamp can
    // drift before it is considered stale, tiggering an alert
    TimeOut *time.Duration `json:"timeout,omitempty"`
    // Suffix is optional, and is used appended to Value for metrics
    Suffix string `json:"suffix,omitempty"`
}

Status is a type used to convey status-related information about a Service, System, or Metric

func StatusSliceFromJmap

func StatusSliceFromJmap(jmap []interface{}) []Status

StatusSliceFromJmap is a hacky function that might take a slice of interfaces, and return a same-sized slice of Status

func (*Status) MarshalJSON

func (s *Status) MarshalJSON() ([]byte, error)

MarshalJSON is a custom marshaller for JSON encoding, to output TimeStamp and TimeOut as numbers instead of pretty strings.

func (*Status) MetricString

func (s *Status) MetricString() string

MetricString returns a Nagios Performance Data -compatible representation of Status

type StatusRegistry

type StatusRegistry struct {
    sync.RWMutex
    // contains filtered or unexported fields
}

StatusRegistry is a gorosafe map of services to their Status objects

func NewStatusRegistry

func NewStatusRegistry() *StatusRegistry

NewStatusRegistry returns an initialized StatusRegistry

func (*StatusRegistry) Add

func (s *StatusRegistry) Add(name, status string, Value, ExpectedValue interface{})

Add or update an entry in StatusRegistry

func (*StatusRegistry) Get

func (s *StatusRegistry) Get(name string) (*Status, error)

Get returns the requested Status, or ErrNoSuchEntryError

func (*StatusRegistry) Keys

func (s *StatusRegistry) Keys() []string

Keys returns a list of names from the StatusRegistry

func (*StatusRegistry) Remove

func (s *StatusRegistry) Remove(name string)

Remove an entry from the StatusRegistry

type StatusString

type StatusString = string

StatusString is a string type for static string consistency


Generated by godoc2md

# Functions

Checks takes a status document, escalate the status, and appends Nagios-compatible information to the message.
Metrics takes a "metrics" document and appends Nagios-compatible metrics information to the message.
NewCheck returns an empty Check.
NewCheckfromJSON returns an Check populated from an Check JSON.
NewStatusRegistry returns an initialized StatusRegistry.
SafeLabel returns a label that is safe to use with modern RRD.
StatusSliceFromJmap is a hacky function that might take a slice of interfaces, and return a same-sized slice of Status.
ValidateJSON runs provided JSON against the JSON-Schema validator.

# Constants

Status constants to prevent fat-fingered-oopsies.
Status constants to prevent fat-fingered-oopsies.
Status constants to prevent fat-fingered-oopsies.
Status constants to prevent fat-fingered-oopsies.
Status constants to prevent fat-fingered-oopsies.
Status constants to prevent fat-fingered-oopsies.
Status constants to prevent fat-fingered-oopsies.
Status constants to prevent fat-fingered-oopsies.

# Variables

ErrNoSuchEntryError is returned when the requested element does not exist in the Registry.
SchemaJSON was generated from schema.json at Sun Apr 17 12:23:48 PM EDT 2022.

# Structs

Check is a type used to define healthcheck statuses.
Status is a type used to convey status-related information about a Service, System, or Metric.
StatusRegistry is a gorosafe map of services to their Status objects.

# Type aliases

JSON is an encapsulating type for "jmap"-based structures.
StatusString is a string type for static string consistency.