Configuration

Watchghost configuration lives within four files within a single directory. These files describe our monitored infrastructure. Each file contains one kind of configured element.

The four kind of configuration element (and their filenames) are:

  • servers
  • groups
  • watchers
  • loggers

The default directory is ~/.config/watchghost. This folder can be changed using the config option of Watchghost executables.

The format of these files is JSON and each file contains a list of elements.

Servers

class watchghost.config.Server(name, config)

A Server is only represented by its name. This name is a string that must be unique amongst all servers and groups.

Any other pair of key/value can be configured.

Example:

{
  "jupiter": {
    "ipv4": "100.10.10.10",
    "ipv6": "2001:db8:100:0:bda1:1c51:c598:6ef8"
  },
  "ceres": {
    "ipv4": "100.10.10.11",
    "ipv6": "2001:db8:100:0:2df2:b059:4067:437e"
  },
  "vulcan": {
    "ipv4": "100.10.10.12",
    "ipv6": "2001:db8:100:0:eccf:6af2:e2:9e"
  }
}

Groups

A Group is only represented by its name. This name is a string that must be unique amongst all servers and groups. Values must be a list of valid server names.

Example:

{
  "postgres": ["jupiter", "vulcan"],
  "linux": ["jupiter", "ceres"],
  "windows": ["vulcan"]
}

This example defines three groups named postgres (including the jupiter and vulcan servers), linux (including the jupiter and ceres servers), and windows (including the vulcan server).

Watchers

class watchghost.services.Service(name)

A Service is responsible for checking something.

A Watcher is a Service applied to a server or a group, with custom attributes.

Any watcher must have the following attributes:

  • service: the service class name.
  • server or group: the server name or group name.

Any watcher can have the following attributes:

  • description: a string representing the watcher (default: None).
  • repeat: the time period between two checks, in seconds (default: 3600).
  • after: the hour when the checks must start (default: “00:00:00”).
  • before: the hour when the checks must stop (default: “23:59:59”).
  • retry: the number of checks giving the same result before declaring the state as hard (default: 2).
  • retry_interval: the time period (in seconds), between two checks when the state is not hard (default: 15).
  • status: a mapping between statuses and filters that trigger these statuses.

Example:

[
  {
    "service": "network.Ping",
    "group": "postgres",
    "description": "Ping IPv4",
    "ip_version": 4
  },
  {
    "service": "network.HTTP",
    "server": "ceres",
    "description": "HTTP",
    "url": "http://test.org:8888/",
    "status": {"warning": [{"code": 404}]}
  }
]

This example defines two watchers. The first one pings the IPv4 of the postgres group’s servers. The second one fetches the “http://test.org:8888/” page on the “ceres” server and gives a warning status when the status code is 404 (otherwise gives what the HTTP watcher’s default config does).

See the list of builtin services used by watchers

Loggers

class watchghost.loggers.Logger(config)

A logger make a recording of services watches.

All loggers share the following properties:

  • type: the name of the class to use as logger. This class must be found in watchghost.loggers module.
  • status: a list of status level that the logger accepts. A status level is one of info, warning, error, critical or unknown.
  • only_hard: whether or not the logger should act only on hard statuses or not. A status is hard when a watcher gives the same result N times (N being defined on the watcher).

Example:

{
  "type": "Console",
  "status": ["error", "critical"],
  "only_hard": True
}

This example defines a logger that will use the class watchghost.loggers.Console. This logger will only log error and critical statuses when these statuses are hard.

See the list of builtin loggers