repmon

README

Repmon

Repmon is a simple database replication monitoring tool. Repmon will send notifications based on database replication failure. Repmon also optionally support HTTP healthchecks for database replication.

Supported Databases

• MySQL 5.5 (possibly other MySQL versions but untested)

Supported Notifications

• Email

HTTP Healthcheck

Repmon can optionally listen for HTTP health probes at /healthcheck. It will return a 200 status code if replication is running and a 503 otherwise.

How does it work?

1. Download the latest release.
2. Create a YAML configuration file
3. Run it repmon -conf repmon.yaml

Configuration file

The YAML file defines repmon's operation.

Full config example

log_path: /var/log/repmon.log
log_level: error
frequency: 1h
http:
  addr: 0.0.0.0
  port: 4040
mysql:
  host: 127.0.0.1
  port: 3306
  user: user
  pass: pass
email:
  host: mail.me.com
  port: 587
  user: me
  pass: pass
  starttls: true
  ssl: false
  subject: Database Replication Failure
  from: me@me.com
  to:
    - you@me.com

Global Options

log_path - File on disk where repmon logs will be stored. Defaults to /var/log/repmon.log.

log_level - Sets the log level. Valid levels are: panic, fatal, trace, debug, warn, info, and error. Defaults to error.

frequency - How often repmon will check the database to ensure replication is running. Defaults to 1h.

HTTP

addr - The listening address for the HTTP server. Default to 127.0.0.1

port - The listening port for the HTTP server. Default to 4040

MySQL

host - The hostname or IP of the MySQL server.

port - The port of the MySQL server.

user - The username used to authenticate.

pass - The password used to authenticate.

socket_path - Connect to the MySQL database through a socket file rather than a port.

Email

host - The hostname or IP of the SMTP server.

port - The port of the SMTP server.

user - The username used to authenticate.

pass - The password used to authenticate.

start_tls - StartTLS enables TLS security. If both StartTLS and SSL are true then StartTLS will be used.

insecure_skip_verify - When using TLS skip verifying the server's certificate chain and host name.

ssl - SSL enables SSL security. If both StartTLS and SSL are true then StartTLS will be used.

from - The email address the email will be sent from.

to - An array of email addresses for which emails will be sent.

Flags

-conf - Path to the repmon configuration file

-debug - Log to STDOUT

HTTP Health Checks

The optional HTTP server creates two endpoints.

/live - A liveness check that always returns 200.

/health - A health check that returns 200 if the if there are no replication errors and 503 otherwise.

Road Map

• Docker Image
• Systemd service file
• Create rpm
• Create deb
• Support for more databases
• Support for more notifiers

Documentation

Index

• type Config
  • func OpenConfig(path string) (*Config, error)
• type Email
• type EmailNotifier
  • func NewEmailNotifier(config *Config) *EmailNotifier
  • func (n *EmailNotifier) Notify(err error) error
• type HTTP
• type MySQL
  • func (m *MySQL) DSN() string
• type MySQLReplicationChecker
  • func NewMySQLReplicationChecker(db *sql.DB, config *Config) *MySQLReplicationChecker
  • func (d *MySQLReplicationChecker) Replicating() error
• type Notifier
• type RepMon
  • func New(config *Config, replicationChecker ReplicationChecker, notifier Notifier) *RepMon
  • func (r *RepMon) Start()
  • func (r *RepMon) Stop()
• type ReplicationChecker

Types

type Config

type Config struct {
	// LogPath is the directory on disk where repmon logs will be stored. Defaults to /var/log/repmon.
	LogPath string `yaml:"log_path"`

	// LogLevel sets the level of logging. Valid levels are: panic, fatal, trace, debug, warn, info, and error. Defaults to error
	LogLevel string `yaml:"log_level"`

	// Frequency describes how often the replication status will be checked
	Frequency string `yaml:"frequency"`

	// SlaveSQLRunningField is the field checked in the database determine if slave sql is running. Defaults to Slave_SQL_Running and likely never
	// needs to be changed.
	SlaveSQLRunningField string `yaml:"slave_sql_running_field"`

	// SlaveIORunningField is the field checked in the database to determine if slave io is running. Defaults to Slave_IO_Running and likely never
	// needs to be changed.
	SlaveIORunningField string `yaml:"slave_io_running_field"`

	// SecondsBehindMasterField is the field checked in the database to determine if the seconds replica is behind master.
	// Defaults to Seconds_Behind_Master and likely never needs to be changed.
	SecondsBehindMasterField string `yaml:"seconds_behind_master_field"`

	// SecondsBehindMasterThreshold is the seconds behind master where we will send a notification email. It must be greather
	// than 0 and defaults to 36000 (10 hours).
	SecondsBehindMasterThreshold int `yaml:"seconds_behind_master_threshold"`

	HTTP  *HTTP  `yaml:"http"`
	MySQL *MySQL `yaml:"mysql"`
	Email *Email `yaml:"email"`
	// contains filtered or unexported fields
}

func OpenConfig

func OpenConfig(path string) (*Config, error)

OpenConfig returns a new Config option by reading the YAML file at path. If the file doesn't exist, can't be read, is invalid YAML, or doesn't match the repmon spec then an error is returned.

type Email

type Email struct {
	// Host is the hostname or IP of the SMTP server.
	Host string `yaml:"host"`

	// Port is the port of the SMTP server.
	Port int `yaml:"port"`

	// User is the username used to authenticate.
	User string `yaml:"user"`

	// Pass is the password used to authenticate.
	Pass string `yaml:"pass"`

	// StartTLS enables TLS security. If both StartTLS and SSL are true then StartTLS will be used.
	StartTLS bool `yaml:"starttls"`

	// Skip verifying the server's certificate chain and host name.
	InsecureSkipVerify bool `yaml:"insecure_skip_verify"`

	// SSL enables SSL security. If both StartTLS and SSL are true then StartTLS will be used.
	SSL bool `yaml:"ssl"`

	// Optional subject field for notification emails
	Subject string `yaml:"subject"`

	// From is the email address the email will be sent from.
	From string `yaml:"from"`

	// To is an array of email addresses for which emails will be sent.
	To []string `yaml:"to"`
}

type EmailNotifier

type EmailNotifier struct {
	// contains filtered or unexported fields
}

EmailNotifier sends emails based on repliaction failure

func NewEmailNotifier

func NewEmailNotifier(config *Config) *EmailNotifier

NewEmailNotifier creates a EmailNotifier using the config

func (*EmailNotifier) Notify

func (n *EmailNotifier) Notify(err error) error

Notify sends a failure notification

type HTTP

type HTTP struct {
	// The address the http server will listen on.
	Addr string `yaml:"addr"`

	// The port the http server will listen on.
	Port int `yaml:"port"`
}

HTTP defines the configuration for http health checks.

type MySQL

type MySQL struct {
	// Host is the hostname or IP of the MySQL server.
	Host string `yaml:"host"`

	// Port is the port of the MySQL server. Ignored if SocketPath is not the empty string
	Port int `yaml:"port"`

	// User is the username used to authenticate.
	User string `yaml:"user"`

	// Pass is the password used to authenticate.
	Pass string `yaml:"pass"`

	// SocketPath is the path to the unix socket. If set to the empty string then a TCP connection is used instead.
	SocketPath string `yaml:"socket_path"`
}

func (*MySQL) DSN

func (m *MySQL) DSN() string

DSN returns the go database dsn.

type MySQLReplicationChecker

type MySQLReplicationChecker struct {
	// contains filtered or unexported fields
}

MySQLReplicationChecker checks if replication is running on a given MySQL 5.5 database.

func NewMySQLReplicationChecker

func NewMySQLReplicationChecker(db *sql.DB, config *Config) *MySQLReplicationChecker

MySQLReplicationChecker returns a new MySQL replication checker.

func (*MySQLReplicationChecker) Replicating

func (d *MySQLReplicationChecker) Replicating() error

Replicating checks if replication is running. It returns an error if replication isn't running or the replica is behind by more than the configured seconds threshold.

type Notifier

type Notifier interface {
	Notify(error) error
}

Notifier defines a notification method.

type RepMon

type RepMon struct {
	// contains filtered or unexported fields
}

RepMon monitors a database to ensure that replication is running.

func New

func New(config *Config, replicationChecker ReplicationChecker, notifier Notifier) *RepMon

New returns a new RepMon instance.

func (*RepMon) Start

func (r *RepMon) Start()

Start starts monitoring the configured database.

func (*RepMon) Stop

func (r *RepMon) Stop()

Stop stops monitoring the configured database.

type ReplicationChecker

type ReplicationChecker interface {
	Replicating() error
}

ReplicationChecker defines a replication check for a database