Overseer

Simple process manager library.

• Note: The master branch is the development branch. To make sure you use the correct version, use the repository tags.

At the heart of this library is the os/exec.Cmd from Go-lang and the first wrapper for that is the Cmd struct.

The Overseer struct can supervise one or more Cmds running at the same time.

You can safely run multiple Overseer instances at the same time.

There are 3 states in the normal lifecycle of a proc: starting, running, finished.

If the process is killed prematurely, the states are: starting, running, interrupted.

If the process cannot start, the states are: starting, fatal.

Overseer API

Setting up a logger is optional, but if you want to use it, it must be called before creating a new Overseer.

By default, the logger is DefaultLogger from ShinyTrinkets/meta-logger/default.go.

To disable the logger completely, you need to create a Logger interface, with empty functions for Info and Error, see examples/simple-overseer.

• NewOverseer() - Returns a new instance of the Overseer process manager.
• Add(id string, exec string, args ...interface{}) - Register a proc, without starting it. The id must be unique. The name of the executable is exec. The args of the executable are args.
• Remove(id string) - Unregister a proc, only if it's not running. The id must be unique.
• SuperviseAll() - This is the main function. Supervise all registered processes and block until they finish. This includes killing all the processes when the main program exits. The function can be called again, after all the processes are finished. The status of the running processes can be watched live with the WatchState(..) function and the logs with WatchLogs(..).
• Supervise(id string) - Supervise one registered process and block until it finishes. This includes checking if the process was killed from the outside, delaying the start and restarting in case of failure (failure means the program has an exit code != 0 or it ran with errors). The function can be called again, after the process is finished.
• WatchState(outputChan chan *ProcessJSON) - Subscribe to all state changes via the provided output channel. The channel will receive status changes for all the added procs, but you can easily identify the one your are interested in from the ID, Group, etc. Note that for each proc you will receive only 2 or 3 messages that represent all the possible states (eg: starting, running, finished).
• UnWatchState(outputChan chan *ProcessJSON) - Un-subscribe from the state changes, by un-registering the channel.
• WatchLogs(logChan chan *LogMsg) and UnWatchLogs(logChan chan *LogMsg) - Subscribe/ un-subscribe to/ from log messages using the provided channel.
• Stop(id string) - Stops the process by sending its process group a SIGTERM signal and resets RetryTimes to 0 so the process doesn't restart.
• Signal(id string, sig syscall.Signal) - Sends an OS signal to the process group.
• StopAll(kill bool) - Cycles and stops all processes. If "kill" is false, all procs receive SIGTERM to allow a graceful shut down. If "kill" is true, all procs receive SIGKILL and they are killed immediately.

Cmd API

It's recommended to use the higher level Overseer, instead of Cmd directly.

If you use Cmd directly, keep in mind that it is one use only. After starting a instance, it cannot be started again. However, you can Clone your instance and start the clone. The Supervise method from the Overseer does all of that for you.

• NewCmd(name string, args ...interface{}) - Returns a new instance of Cmd.
• Clone() - Clones a Cmd. All the options are copied, but the state of the original object is lost.
• Start() - Starts the command and immediately returns a channel that the caller can use to receive the final Status of the command when it ends. The function can only be called once.
• Stop() - Stops the command by sending its process group a SIGTERM signal.
• Signal(sig syscall.Signal) - Sends an OS signal to the process group.
• Status() - Returns the Status of the command at any time. The Status struct contains: PID, Exit code, Error (if it's the case) Start and Stop timestamps, Runtime in seconds.
• IsInitialState() - true if the Cmd is in initial state.
• IsRunningState() - true if the Cmd is starting, or running.
• IsFinalState() - true if the Cmd is in a final state.

Project highlights

• real-time status
• real-time stdout and stderr
• complete and consolidated return
• easy to track process state
• proper process termination on program exit
• portable command line binary for managing procs
• heavily tested, very good test coverage
• no race conditions

For examples of usage, please check the Examples folder, the Overseer CLI app, the manager tests, or the Spinal app.

Similar libraries

• https://github.com/go-cmd/cmd - os/exec.Cmd with concurrent-safe access, real-time streaming output and complete runtime/return status. Overseer is based off this one.
• https://github.com/immortal/immortal - A *nix cross-platform (OS agnostic) supervisor. The real deal.
• https://github.com/ochinchina/supervisord - A Golang supervisor implementation, inspired by Python supervisord.
• https://github.com/DarthSim/hivemind - Process manager for Procfile-based applications.

Icon is made by Freepik from www.flaticon.com and licensed by CC 3.0 BY.

License

MIT © Cristi Constantin.