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.
Atelemetryplugin.
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)pluginplugin.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