Merge pull request #207 from 56quarters/doc-updates

Documentation updates and version bump for 1.4.0

CHANGES.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [v1.4.0](https://github.com/56quarters/cadence/tree/1.4.0) - 2024-04-28
+* Make the previously internal `MultiLineWriter` and `SocketStats` structs
+  available from the `cadence::ext` module per [#206](https://github.com/56quarters/cadence/pull/206). 
+  These can be useful when creating custom `MetricSink` implementations.
+  Thanks to @mlowicki for this contribution.
+
 ## [v1.3.0](https://github.com/56quarters/cadence/tree/1.3.0) - 2024-03-23
 * Add support for using `u64`, `i32`, and `u32` types as counters per
   [#201](https://github.com/56quarters/cadence/pull/201). Thanks to @James-Bartman

MIGRATION.md

@@ -2,6 +2,14 @@
 
 Guides for migrating to different versions of Cadence are below.
 
+## Migrating to 1.4.0
+
+There are no backwards incompatible changes in this release.
+
+## Migrating to 1.3.0
+
+There are no backwards incompatible changes in this release.
+
 ## Migrating to 1.2.0
 
 There are no backwards incompatible changes in this release.

cadence-macros/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cadence-macros"
-version = "1.3.0"
+version = "1.4.0"
 authors = ["Nick Pillitteri"]
 description = "Macros for Cadence, an extensible Statsd client for Rust"
 homepage = "https://github.com/56quarters/cadence"
@@ -13,7 +13,7 @@ edition = "2021"
 autobenches = false
 
 [dependencies]
-cadence = { path = "../cadence", version = "1.3" }
+cadence = { path = "../cadence", version = "1.4" }
 
 [dev-dependencies]
 crossbeam-channel = "0.5.1"

cadence/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cadence"
-version = "1.3.0"
+version = "1.4.0"
 authors = ["Nick Pillitteri"]
 description = "An extensible Statsd client for Rust"
 homepage = "https://github.com/56quarters/cadence"

cadence/src/sinks/core.rs

@@ -12,6 +12,7 @@ use std::io;
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::Arc;
 
+/// I/O telemetry for a `MetricSink` implementation.
 #[derive(Clone, Debug, Default)]
 pub struct SinkStats {
     pub bytes_sent: u64,
@@ -20,6 +21,36 @@ pub struct SinkStats {
     pub packets_dropped: u64,
 }
 
+/// Thread-safe collection of stats updated by network sinks.
+///
+/// This struct is meant to be updated internally by `MetricSink` implementations
+/// and converted to an instance of `SinkStats` for consumption by external callers.
+///
+/// # Example
+///
+/// ```
+/// use std::net::{SocketAddr, UdpSocket};
+/// use cadence::ext::SocketStats;
+/// use cadence::{MetricSink, SinkStats};
+///
+/// pub struct MyCustomSink {
+///     addr: SocketAddr,
+///     socket: UdpSocket,
+///     stats: SocketStats,
+/// }
+///
+/// impl MetricSink for MyCustomSink {
+///     fn emit(&self, metric: &str) -> std::io::Result<usize> {
+///         let res = self.socket.send_to(metric.as_bytes(), &self.addr);
+///         self.stats.update(res, metric.len())
+///     }
+///
+///     fn stats(&self) -> SinkStats {
+///        (&self.stats).into()
+///     }
+/// }
+///
+/// ```
 #[derive(Debug, Clone, Default)]
 pub struct SocketStats {
     bytes_sent: Arc<AtomicU64>,