PLT Service Monitor
1 Heartbeats
beat
2 Taking a Pulse
take-pulse
3 Configuring a Service Monitor
get-task
set-task
remove-task
get-site
set-site
remove-site
get-email
set-email
remove-email
6.12

PLT Service Monitor

The "plt-service-monitor" package provides tools for tasks to register “heartbeat” activity to an AWS S3 bucket and for a periodic polling of heartbeats and HTTP sites.

The configuration of tasks, sites, and e-mail addresses to alert are stored in the S3 bucket in a "config.rktd" file. The plt-service-monitor/config module provides functions to adjusting the configuration.

1 Heartbeats

The plt-service-monitor/beat library provides an API for a monitored task to register a heartbeat—typically as the last step in a periodic task.

Besides providing the beat function, plt-service-monitor/beat can be run from the command line and given its arguments as command-line arguments.

procedure

(beat s3-bucket task-name [#:region region])  void?

  s3-bucket : string?
  task-name : string?
  region : string? = ...
Records a heartbeat, based on the current machine’s time in UTC.

If the region of s3-bucket is not supplied, it is determined through a query.

2 Taking a Pulse

The plt-service-monitor/take-pulse library implements the monitor; it polls an S3 bucket and associated HTTP sites.

The plt-service-monitor/take-pulse module can be run from the command-line, in which case the S3 bucket name must be given as a command-line argument. In addition, --email-config can specify a file that contains a configuration hash table for sending e-mail alerts, and --no-email or --fail-email configure the e-mail alert mode.

procedure

(take-pulse s3-bucket    
  [#:region region    
  #:email-mode email-mode    
  #:email-config email-config])  boolean?
  s3-bucket : string?
  region : string? = ...
  email-mode : (or/c 'none 'always 'failure) = 'always
  email-config : hash? = (hash)
Polls the specified S3 bucket for heartbeats and polls configured HTTP sites. The results are printed to the current output port and the resulting boolean is #t only if all checks succeed. If the region of s3-bucket is not supplied, it is determined through a query.

The S3 bucket’s configuration file may specify e-mail addresses to receive the poll summary. If email-mode is 'always or it is 'failure and the health check fails, then e-mail is sent (although individual e-mail addresses can be configured to send mail only on failure). In that case, email-config configures the way that e-mail is sent through the following keys:

3 Configuring a Service Monitor

The plt-service-monitor/config library provides functions for adjusting a service monitor’s configuration as stored at its S3 bucket. (The region of the bucket is determined automatically through a query.)

procedure

(get-task s3-bucket    
  task-name    
  [#:force? force?])  (or/c #f hash?)
  s3-bucket : string?
  task-name : string?
  force? : any/c = #f

procedure

(set-task s3-bucket task [#:force? force?])  void?

  s3-bucket : string?
  task : hash?
  force? : any/c = #f

procedure

(remove-task s3-bucket task-name)  void?

  s3-bucket : string?
  task-name : string?
Gets, adjusts, or removes a task to the configuration at s3-bucket for use by take-pulse.

The get-task function returns #f if the task name is not configured, otherwise it returns a hash table suitable for updating and returning to set-task.

The hash table provided to set-task can have the following keys with the indicated contracts on the key values:

Unless force? is true, then get-task or set-task fail if s3-bucket does not have a configuration object "config.rktd".

procedure

(get-site s3-bucket url [#:force? force?])  (or/c #f hash?)

  s3-bucket : string?
  url : string?
  force? : any/c = #f

procedure

(set-site s3-bucket site [#:force? force?])  void?

  s3-bucket : string?
  site : hash?
  force? : any/c = #f

procedure

(remove-site s3-bucket url)  void?

  s3-bucket : string?
  url : string?
Gets, adjusts, or removes a polled URL to the configuration at s3-bucket for use by take-pulse. The function protocol is the same as for get-task, set-task, and remove-task.

The hash table provided to set-site can have the following keys with the indicated contracts on the key values:

procedure

(get-email s3-bucket addr [#:force? force?])  (or/c #f hash?)

  s3-bucket : string?
  addr : string?
  force? : any/c = #f

procedure

(set-email s3-bucket to [#:force? force?])  void?

  s3-bucket : string?
  to : hash?
  force? : any/c = #f

procedure

(remove-email s3-bucket addr)  void?

  s3-bucket : string?
  addr : string?
Gets, adjusts, or removes an e-mail address to the configuration at s3-bucket for use by take-pulse, where Each e-mail address receives a message to summarize the check results. The function protocol is the same as for get-task, set-task, and remove-task.

The hash table provided to set-email can have the following keys with the indicated contracts on the key values: