programmatic-access-events.md

Help

1. Starting and stopping processes
2. Controlling the Daemon
3. Managing clusters
4. Installing and running apps
5. Remote access and monitoring (e.g. guv-web)
6. Web interface
7. Web interface - configuration
8. Web interface - user management
9. Programmatic access
10. Programmatic access - local
11. Programmatic access - remote
12. Programmatic access - events

Programmatic access - events

The guvnor daemon is a wildemitter so you can use wildcards to listen for events:

guvnor.on('*', function() {
  var type = arguments[0]
  var args = Array.prototype.slice.call(arguments, 1)

  console.info(type, 'emitted with args', args)
})

Process events

These are events that are to do with managed processes. They are emitted by processes, cluster managers and workers. For example:

guvnor.on('process:starting', function(processInfo) {
  console.info('process %s is starting', processInfo.name)
})

guvnor.on('cluster:starting', function(clusterInfo) {
  console.info('cluster %s is starting', clusterInfo.name)
})

guvnor.on('worker:starting', function(clusterInfo, workerInfo) {
  console.info('worker %s from cluster %s is starting', workerInfo.id, clusterInfo.name)
})

Note that the signature for cluster worker events is slightly different - they receive both the cluster and worker process information.

### 'process:starting' processInfo

A process is about to be created.

### 'process:forked' processInfo

A process is now active (although the v8 instance behind it may still be initialising).

### 'process:failed' processInfo, error

A process wrapper initialised incorrectly - hopefully you will never see this

### 'process:started' processInfo

A process has started and your module code has been loaded.

### 'process:errored' processInfo, error

Your module code threw an exception on start up.

### 'process:ready' processInfo

A connection has been established between guvnor and the managed process. All systems go.

'process:stopping' processInfo

A process is about to stop.

'process:uncaughtexception' processInfo, error

A process experienced an uncaught exception after startup.

### 'process:fatality' processInfo

A process experienced an uncaught exception and there were no handlers for the exception. The process will now exit with a non-zero error code which will cause it to be be restarted.

'process:exit' processInfo, error, code, signal

A process exited or errored with the specified error code. If a signal was used to kill the process, it will be passed as the second argument. If the exit code is non-zero the process will be automatically restarted.

'process:restarted' processInfo

A process restarted successfully.

'process:aborted' processInfo, error

A process failed to (re)start because it error'd on startup more times than allowed.

'process:config:request'

A managed process has requested configuration from guvnor

Cluster events

Cluster events are divided into two types - cluster and worker. Cluster events are emitted by the process that manages cluster workers and worker events are emitted by the workers themselves.

'cluster:starting' processInfo

A cluster manager is starting

'cluster:ready' clusterInfo

A cluster manager has started and can be connect to

'cluster:failed' clusterInfo, error

A cluster manager has failed to start

'cluster:online' clusterInfo

A cluster manager and all it's worker processes are ready

'worker:new' clusterInfo, workerInfo

A new cluster worker was created

'worker:stopping:' clusterInfo, workerInfo

A worker is about to get killed

'worker:exit' clusterInfo, workerInfo, code, signal

A worker exited with the passed code. If a signal was used to kill the worker, it is passed as the third argument to the callback.

Daemon events

These are events that are to do with the guvnor daemon itself.

'daemon:fatality' error

Guvnor crashed. Hopefully you'll never see this.

'daemon:exit'

The daemon is about to shut down cleanly, usually in response to the guv kill command.

'daemon:dump'

The daemon has written process information out to /etc/guvnor/processes.json, usually in response to the guv dump command.

'daemon:restore'

The daemon has loaded process information from /etc/guvnor/processes.json if available, usually in response to the guv restore command.

'daemon:config:response'

Guvnor is sending configuration to a managed process

App events

App events related to installed apps. An app is a node.js program installed from a git repository containing a package.json file at it's root.

'app:installed' appInfo

An app was installed. The passed appInfo object contains the name, url, etc of the new app.

'app:removed' appInfo

An app was removed and all files deleted from the filesystem. The passed appInfo object contains the name, url, etc of the removed app.

'app:refs:updated' appInfo, refs

New app refs were pulled from the upstream repository. The passed appInfo object represents the app and refs is the list of available ref names. A ref is a git branch or tag.

'app:refs:switched' appInfo, oldRef, newRef

The app represented by appInfo was switched from oldRef to newRef. A ref is a git branch or tag.

## Log events

There are four types of log event: info, warn, error and debug. Log events are emitted by processes, cluster managers, cluster workers and the guvnor daemon itself.

info and error correspond to stdout and stderr.

info

A process emitted an info log event. The log object contains the time and the message.

guvnor.on('process:log:info', function(processInfo, log) {
  console.info('process %s said %s at %s', processInfo.name, log.message, log.date)
})

guvnor.on('cluster:log:info', function(clusterInfo, log) {
  console.info('cluster manager %s said %s at %s', clusterInfo.name, log.message, log.date)
})

guvnor.on('worker:log:info', function(clusterInfo, workerInfo, log) {
  console.info('worker %s from cluster %s said %s at %s', workerInfo.id, cluster.name, log.message, log.date)
})

guvnor.on('daemon:log:info', function(log) {
  console.info('guvnor said %s at %s', log.message, log.date)
})

warn

A process emitted an warn log event. The log object contains the time and the message.

guvnor.on('process:log:warn', function(processInfo, log) {
  console.warn('process %s said %s at %s', processInfo.name, log.message, log.date)
})

guvnor.on('cluster:log:warn', function(clusterInfo, log) {
  console.warn('cluster manager %s said %s at %s', clusterInfo.name, log.message, log.date)
})

guvnor.on('worker:log:warn', function(clusterInfo, workerInfo, log) {
  console.warn('worker %s from cluster %s said %s at %s', workerInfo.id, cluster.name, log.message, log.date)
})

guvnor.on('daemon:log:warn', function(log) {
  console.warn('guvnor said %s at %s', log.message, log.date)
})

error

A process emitted an error log event. The log object contains the time and the message.

guvnor.on('process:log:error', function(processInfo, log) {
  console.error('process %s said %s at %s', processInfo.name, log.message, log.date)
})

guvnor.on('cluster:log:error', function(clusterInfo, log) {
  console.error('cluster manager %s said %s at %s', clusterInfo.name, log.message, log.date)
})

guvnor.on('worker:log:error', function(clusterInfo, workerInfo, log) {
  console.error('worker %s from cluster %s said %s at %s', workerInfo.id, cluster.name, log.message, log.date)
})

guvnor.on('daemon:log:error', function(log) {
  console.error('guvnor said %s at %s', log.message, log.date)
})

debug

A process emitted an debug log event. The log object contains the time and the message.

guvnor.on('process:log:debug', function(processInfo, log) {
  console.info('process %s said %s at %s', processInfo.name, log.message, log.date)
})

guvnor.on('cluster:log:debug', function(clusterInfo, log) {
  console.info('cluster manager %s said %s at %s', clusterInfo.name, log.message, log.date)
})

guvnor.on('worker:log:debug', function(clusterInfo, workerInfo, log) {
  console.info('worker %s from cluster %s said %s at %s', workerInfo.id, cluster.name, log.message, log.date)
})

guvnor.on('daemon:log:debug', function(log) {
  console.info('guvnor said %s at %s', log.message, log.date)
})