statsd-lambda 🔨
A simple UDP based statsd client designed for Amazon Lambda. (And is probably useful for other functions as a service.) It leverages the microtask queue to batch metrics messages and sends them out via UDP for a very cheap way to collect counters, gauges, and timers that wont block your responses.
- Overview
- API
Why another statsd client?
Many statsd clients exist and if you're not using lambda you should consider them. However on amazon lambda once you've responded to a request your function is put to sleep preventing background tasks from executing. Most stats libraries use a background task or send metrics data which will be unpredictable. Most lambda specific libraries will block your response to send metrics over https slowing down your process which is unnecessary. To report stats data without leveraging background task queues or slowing down your response statsd-lambda
queues sending metrics using process.nextTick
which is fired after promises resolve and before the next event loop. This allows the very fast process of sending UDP packets to complete
This has proven to reliably report metrics with a low impact (0-2 ms).
Why statsd vs a hosted service?
There are currently no UDP based hosted services. Every single service I have found blocks your lambda's response with an https request that can take anywhere from 10-300ms to complete (this includes Cloudwatch metrics which has pretty harsh rate limiting). With one exception, Amazon's X-Ray, which isn't suitable for metric collection.
That aside (and it's a big aside) every hosted solution is significantly more money than a self hosted solution. So while Lambda has brought in an era of reduced operations, it hasn't eliminated all of it.
Install
There are no dependencies.
npm install statsd-lambda
We ship esm, umd (with the AMD global streamingIterables
) and typescript types.
API
constructor
Returns a new metric client.
close
client.close: void
Closes the transport. This is handy if you're outside of lambda (eg, tasks or tests) and need to close the udp socket so node will exit cleanly.
// after some workclient.close
counter
client.countername: string, count?: number, sampleRate?: number: void
Sends a statsd counter.
name
must only include letters, numbers. Periods may be used as a namespace separator.count
a number to countsampleRate
is both communicated and respected. A value of1
(default) means send all the time, a value of0
means never send, and a value of0.5
means send 50% of the time.
Counters are batched by name and sample rate so two calls to a specific counter will be combined into one.
for of pokemon // sends "pokedex.production.pokemon.caught:3|c" on process.nextTick
flush
client.flush: void
Flushes all buffered metrics to the transport as a multi-metric packet. This is automatically run on process.nextTick
but may be run manually at any time.
client.counter'pokemon.trained', 2client.flush// sends "pokedex.production.pokemon.trained:2|c" immediately
gauge
client.gaugename: string, value: number | string, sampleRate?: number: void
Sends a statsd gauge.
name
must only include letters, numbers. Periods may be used as a namespace separator.value
the value of the gauge or a change in gauge value eg-1
,+1
sampleRate
is both communicated and respected. A value of1
(default) means send all the time, a value of0
means never send, and a value of0.5
means send 50% of the time.
client.gauge'pokemon.percentDiscovered', Math.rounddiscovered / total * 100// sends "pokedex.production.pokemon.percentDiscovered:50|g"
timer
client.timername: string, time: number, sampleRate?: number: void
Sends a statsd timer.
name
must only include letters, numbers. Periods may be used as a namespace separator.time
the milliseconds to recordsampleRate
is both communicated and respected. A value of1
(default) means send all the time, a value of0
means never send, and a value of0.5
means send 50% of the time.
await findPokemonclient.time'pokemon.discoverTime', Date.now - start// sends "pokedex.production.pokemon.discoverTime:30|ms"
MockTransport
MockTransport
is an IStatsTransport
conforming transport that does nothing but store the packets to be sent as strings up to maxBuffer
(default is 100). This is helpful for testing.
client.counter'test.count', 1client.counter'test.count', 3client.flushconsole.logtransport.packets// ["pokedex.production.test.count:4|c"]
UDPTransport
UDPTransport
is an IStatsTransport
conforming transport that sends packets via UDP to a host and port. host
must be an ip address or dns hostname, and port must be a number (default to 8125
the statsd port). It is not necessary to interact with this object directly.
client.counter'test.count', 1client.flush// a packet is sent to statsdserver.local with the value of// "pokedex.production.test.count:1|c"
Contributors wanted!
This library was developed at Bustle. However writing docs and code is a lot of work! Thank you in advance for helping out and keeping projects like this open source.