Struct cadence::QueuingMetricSink
source · [−]pub struct QueuingMetricSink { /* private fields */ }
Expand description
Implementation of a MetricSink
that wraps another implementation
and uses it to emit metrics asynchronously, in another thread.
Metrics submitted to this sink are queued and sent to the wrapped sink
that is running in a separate thread. The wrapped implementation can
be any thread (Sync
+ Send
) and panic (RefUnwindSafe
) safe
MetricSink
. Results from the wrapped implementation will be discarded.
The thread used for network operations (actually sending the metrics
using the wrapped sink) is created and started when the QueuingMetricSink
is created. The dequeuing of metrics is stopped and the thread stopped
when QueuingMetricSink
instance is destroyed (when .drop()
is
called).
This sink may be created with either a bounded or unbounded queue connecting the sink to the thread performning network operations. When an unbounded queue is used, entries submitted to the sink will always be accepted and queued until they can be drained by the network operation thread. This means that if the network thread cannot drain entries off the queue for some reason, it will grow without bound. Alternatively, if created with a bounded queue, entries submitted to the sink will not be accepted if the queue is full. This means that the network thread must be able to keep up with the rate of entries submit to the queue or writes to this sink will begin to fail.
Entries already queued are guaranteed to be sent to the wrapped sink
before the queuing sink is stopped. Meaning, the following code ends up
calling wrapped.emit(metric)
on every metric submitted to the queuing
sink.
Example
use cadence::{MetricSink, QueuingMetricSink, NopMetricSink};
let wrapped = NopMetricSink;
{
let queuing = QueuingMetricSink::from(wrapped);
queuing.emit("foo.counter:4|c");
queuing.emit("bar.counter:5|c");
queuing.emit("baz.gauge:6|g");
}
At the end of this code block, all metrics are guaranteed to be sent to the underlying wrapped metric sink before the thread used by the queuing sink is stopped.
Implementations
sourceimpl QueuingMetricSink
impl QueuingMetricSink
sourcepub fn from<T>(sink: T) -> Self where
T: MetricSink + Sync + Send + RefUnwindSafe + 'static,
pub fn from<T>(sink: T) -> Self where
T: MetricSink + Sync + Send + RefUnwindSafe + 'static,
Construct a new QueuingMetricSink
instance wrapping another sink
implementation with an unbounded queue connecting them.
The .emit()
method of the wrapped sink will be executed in a
different thread after being passed to it via a queue. The wrapped
sink should be thread safe (Send + Sync
) and panic safe
(RefUnwindSafe
).
The thread in which the wrapped sink runs is created when the
QueuingMetricSink
is created and stopped when the queuing sink
is destroyed.
The queuing sink communicates with the wrapped sink by an unbounded queue. If entries cannot be drained from the queue for some reason, it will grow without bound.
Buffered UDP Sink Example
In this example we wrap a buffered UDP sink to execute it in a different thread.
use std::net::UdpSocket;
use cadence::{BufferedUdpMetricSink, QueuingMetricSink, DEFAULT_PORT};
let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
let host = ("metrics.example.com", DEFAULT_PORT);
let udp_sink = BufferedUdpMetricSink::from(host, socket).unwrap();
let queuing_sink = QueuingMetricSink::from(udp_sink);
sourcepub fn with_capacity<T>(sink: T, capacity: usize) -> Self where
T: MetricSink + Sync + Send + RefUnwindSafe + 'static,
pub fn with_capacity<T>(sink: T, capacity: usize) -> Self where
T: MetricSink + Sync + Send + RefUnwindSafe + 'static,
Construct a new QueuingMetricSink
instance wrapping another sink
implementation with a queue of the given size connecting them.
The .emit()
method of the wrapped sink will be executed in a
different thread after being passed to it via a queue. The wrapped
sink should be thread safe (Send + Sync
) and panic safe
(RefUnwindSafe
).
The thread in which the wrapped sink runs is created when the
QueuingMetricSink
is created and stopped when the queuing sink
is destroyed.
The queuing sink communicates with the wrapped sink by a bounded queue of the provided size. When the queue is full, writes to this sink will fail until the queue is drained.
Buffered UDP Sink Example
In this example we wrap a buffered UDP sink to execute it in a different thread.
use std::net::UdpSocket;
use cadence::{BufferedUdpMetricSink, QueuingMetricSink, DEFAULT_PORT};
let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
let host = ("metrics.example.com", DEFAULT_PORT);
let udp_sink = BufferedUdpMetricSink::from(host, socket).unwrap();
let queuing_sink = QueuingMetricSink::with_capacity(udp_sink, 512 * 1024);
sourcepub fn panics(&self) -> u64
pub fn panics(&self) -> u64
Return the number of times the wrapped sink or underlying worker thread
has panicked and needed to be restarted. In typical use this should always
be 0
but may be > 0
for buggy MetricSink
implementations.
sourcepub fn queued(&self) -> u64
pub fn queued(&self) -> u64
Return the number of currently queued metrics. Note that due to the way this number is computed (submitted metrics - processed metrics), it is necessarily approximate.
Trait Implementations
sourceimpl Clone for QueuingMetricSink
impl Clone for QueuingMetricSink
sourcefn clone(&self) -> QueuingMetricSink
fn clone(&self) -> QueuingMetricSink
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl Debug for QueuingMetricSink
impl Debug for QueuingMetricSink
sourceimpl Drop for QueuingMetricSink
impl Drop for QueuingMetricSink
sourceimpl MetricSink for QueuingMetricSink
impl MetricSink for QueuingMetricSink
Auto Trait Implementations
impl RefUnwindSafe for QueuingMetricSink
impl Send for QueuingMetricSink
impl Sync for QueuingMetricSink
impl Unpin for QueuingMetricSink
impl UnwindSafe for QueuingMetricSink
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more