Record incidental values (rather than on a fixed schedule). Meant to be combined with other plugins in a continuous Telemetry Task; if you merely want to publish metrics once, instead use a publisher plugin by itself.
Atelemetry
plugin.
Click to expand
- Usage
- API
plugin = incidental.single(metricName, options)
plugin = incidental.summary(metricName, options)
plugin = incidental.min(metricName, options)
plugin = incidental.max(metricName, options)
plugin = incidental.sum(metricName, options)
plugin = incidental.count(metricName, options)
plugin
plugin.record(value)
- Install
- Acknowledgements
- License
const telemetry = require('@telemetry-js/telemetry')()
const incidental = require('@telemetry-js/collector-incidental')
const myCount = incidental.single('my.count', { unit: 'count' })
telemetry.task()
.collect(myCount)
.schedule(..)
.publish(..)
// Elsewhere in your app
myCount.record(1000)
myCount.record(500)
This will publish every recorded value (use sparingly). You will also need a schedule plugin, otherwise the metrics stay queued in collector-incidental
and will never be published.
If you're calling record
many times within short time periods, either consider using the rate
variant of the collector-counter
plugin, if it is a rate metric you need, or use incidental.summary()
:
const myCount = incidental.summary('my.count', { unit: 'count' })
telemetry.task()
.collect(myCount)
.schedule(..)
.publish(..)
// Usage is the same
myCount.record(1000)
myCount.record(500)
This will publish one summary at every ping, summarizing the values you recorded between two pings. Pings typically happen every 5 minutes but it depends on your configured schedule.
Instead of the summary collector (which collects min, max, sum ánd count), you can also use a "reducer", one of min
, max
, sum
or count
. Taking max
as an example:
const myCount = incidental.max('my.count.max', { unit: 'count' })
telemetry.task()
.collect(myCount)
.schedule(..)
.publish(..)
// Usage is the same
myCount.record(1000)
myCount.record(500)
This will publish one single value at every ping, reducing the values you recorded between two pings. Here, the first ping will lead to a metric being emitted with value 1000 (the maximum of 500 and 1000). Note that the internal state of the maximum value resets after a ping.
The emitted metrics get a relevant .statistic
property which publishers like publisher-appoptics
use to control server-side rollup behavior (when it's aggregating values into a lower resolution a.k.a. higher interval).
Emits every value recorded between pings. It is recommended to end the metric name with the unit, e.g. batch_size.count
, size.bytes
.
Options:
unit
: string, required- Other options are passed as-is to
metric
.
Emits a summary of values recorded between pings. Same arguments as incidental.single()
.
Emits the minimum of values recorded between pings. Same arguments as incidental.single()
.
Emits the maximum of values recorded between pings. Same arguments as incidental.single()
.
Emits the sum of values recorded between pings. Same arguments as incidental.single()
.
Emits the count of values recorded between pings. Same arguments as incidental.single()
, except that the unit
option defaults to 'count'
and does not need to be specified.
Known issue: if no values were recorded, it should emit a metric with value 0 (in order to differentiate that situation from missing metrics) but it doesn't.
This is a function to be passed to a Telemetry Task. Can be used by multiple tasks, sharing state:
telemetry.task().collect(plugin)
telemetry.task().collect(plugin)
Record a value (as well as the current time when using single
; summaries and reducers use ping time). Value must be a number.
With npm do:
npm install @telemetry-js/collector-incidental
This project is kindly sponsored by Reason Cybersecurity Ltd.
MIT © Vincent Weevers