monitoring-stream v1.0.0
:toc: macro :toc-title: :toclevels: 9
Monitoring Stream
image:https://travis-ci.org/jasonkuhrt/monitoring-stream.svg?branch=master["Build Status", link="https://travis-ci.org/jasonkuhrt/monitoring-stream"]
toc::[]
Installation
yarn add monitoring-stream
About
This is a tiny library that makes it trivial to monitor the results of repeatedly executing an asynchronous action. A canonical use-case would be monitoring a URL for healthy (e.g. status code 200) responses but really it could be anything, including actions that don't do any IO but still have something to monitor such random computation. This is a fairly general tool and it interestingly generalizes some things that previously would have been realized with purpose-built code. For example the concept of request-retry can be generally implemented with this library, see the example below.
Examples
Declarative Request-Retry
We can combine streams together to declaratively create request-retry logic. Inspiration for this example was taken from the imperative request-retry logic in https://github.com/elastic/elasticsearch-js/blob/master/test/integration/yaml_suite/client_manager.js#L30-L42[this ElasticSearch test suite] which establishes the connectivity with the database before running its test suite.
import Monitor from "monitoring-stream"
const runTests = () =>
Promise.resolve("Your integration test suite here...")
const pingElasticSearch = () =>
Boolean(Math.round(Math.random()))
? Promise.reject(new Error("Foobar network error"))
: Promise.resolve("OK!")
const pingInterval = 1000
const pingAttempts = 3
const monitor = Monitor.create(pingElasticSearch, pingInterval)
const maxRetries = monitor.downs.takeUntil(monitor.ups).take(pingAttempts)
monitor
.ups
.take(1)
.takeUntil(maxRetries)
.drain()
.then((result) =>
result.isResponsive
? runTests()
: Promise.reject(result.data)
))
API
Types
MonitorEvent
type MonitorEvent<A> = {
isResponsive: boolean,
isResponsiveChanged: boolean,
data: A | null
error: Error | null
}
A monitor event represents the result of an action invocation. The type variable A
represents the action's resolution type.
isResponsive
indicates if the action is resolving while isResponsiveChanged
indicates if that state is different than the previous event. For the first check wherein there is no such previous event isResponsiveChanged
is considered to be true
.
You can think of isResponsive
as being your health indicator while isResponsiveChanged
as being your alert to when crashing or recovery occurs. isResponsiveChanged
is technically a convenience that you could calculate yourself but seeing as its often needed and that its calculation requires state it seems worthwhile.
.create
Monitor.create(action: () => Promise<A>, intervalMs: number?) => Observable<MonitorEvent<A>>
action
The async action to recurse. This could be anything: HTTP requests, pure calculation, file system checks...intervalMs
The milliseconds between eachaction
invocation. Defaults to1000
.returns
An observable stream ofMonitorEvent
. The observable implementation we use is https://github.com/cujojs/most[most
].
Event State Helpers
There are several statically exported predicate functions that can tell you what kind of state a MonitorEvent
is in.
.isUp
Monitor.isUp(event: MonitorEvent) => boolean
Returns true
if event isResponsive
is true
.
.isDown
Monitor.isDown(event: MonitorEvent) => boolean
Returns true
if event isResponsive
is false
.
.isRise
Monitor.isRise(event: MonitorEvent) => boolean
Returns true
if event isResponsive
is true
and isResponsiveChanged
is true
.
.isFall
Monitor.isFall(event: MonitorEvent) => boolean
Returns true
if event isResponsive
is false
and isResponsiveChanged
is true
.
.isChanges
Monitor.isChanges(event: MonitorEvent) => boolean
Returns true
if event isResponsiveChanged
is true
.
Sub-streams
There are several additional streams on monitor instances that are filtered by event state predicates. These sub-streams provide a convenient way to consume just a subset of events without any additional code/work from you.
#ups
Stream filtered by Monitor.isUp
#downs
Stream filtered by Monitor.isDown
#rises
Stream filtered by Monitor.isRise
#falls
Stream filtered by Monitor.isFall
#changes
Stream filtered by Monitor.isChange
7 years ago