PLT Service Monitor

6.3.90.900

top ← prev up next →

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

(require plt-service-monitor/beat)
	package: plt-service-monitor

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

(require plt-service-monitor/take-pulse)
	package: plt-service-monitor

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:

'server — a string or #f (the default); if a string is provided then the SMTP protocol is used with the specified server, otherwise e-mail is sent through sendmail
'from — an e-mail address for the sender; the default is the first e-mail address in the list of receivers
'connect (SMTP only) — 'plain, 'ssl, or 'tls
'user (SMTP only) — a username string for authentication
'password (SMTP only) — a password string for authentication

3 Configuring a Service Monitor

(require plt-service-monitor/config)
	package: plt-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:

'name : string? (required) — the task name as used with beat (but beat does not check whether a given task name is configured as one that is checked by take-pulse)
'period : exact-nonnegative-integer? — the maximum number of seconds that should elapse between heartbeats for the task; the default is one day

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:

'url : string? (required) — the URL to poll

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:

'to : string? (required) — the e-mail address
'on-success? : boolean? — whether e-mail is sent even when all health checks succeed; the default is #t

top ← prev up next →