Merge branch 'master' into fix/api-cleanup-named-etc

Cargo.toml

@@ -11,7 +11,7 @@ documentation = "https://docs.rs/dipstick"
 homepage = "https://github.com/fralalonde/dipstick"
 repository = "https://github.com/fralalonde/dipstick"
 readme = "README.md"
-keywords = ["metrics", "statsd", "graphite", "timer", "monitoring"]
+keywords = ["metrics", "statsd", "graphite", "timer", "prometheus"]
 license = "MIT/Apache-2.0"
 
 [badges]

HANDBOOK.md

@@ -53,17 +53,21 @@ Usable either through the time! macro, the closure form or explicit calls to sta
 While timers internal precision are in nanoseconds, their accuracy depends on platform OS and hardware. 
 Timer's default output format is milliseconds but is scalable up or down.
  
-```$rust,skt-run
-let app_metrics = Stream::to_stdout().metrics();
-let timer =  app_metrics.timer("my_timer");
-time!(timer, {/* slow code here */} );
-timer.time(|| {/* slow code here */} );
-
-let start = timer.start();
-/* slow code here */
-timer.stop(start);
-
-timer.interval_us(123_456);
+```rust
+extern crate dipstick;
+use dipstick::*;
+fn main() {
+    let app_metrics = Stream::to_stdout().metrics();
+    let timer =  app_metrics.timer("my_timer");
+    time!(timer, {/* slow code here */} );
+    timer.time(|| {/* slow code here */} );
+    
+    let start = timer.start();
+    /* slow code here */
+    timer.stop(start);
+    
+    timer.interval_us(123_456);
+}
 ```
 
 ### Level
@@ -84,11 +88,15 @@ Aggregated statistics may also append identifiers to the metric's name.
 Names should exclude characters that can interfere with namespaces, separator and output protocols.
 A good convention is to stick with lowercase alphanumeric identifiers of less than 12 characters.
 
-```$rust,skt-run
-let app_metrics = Stream::to_stdout().metrics();
-let db_metrics = app_metrics.named("database");
-let _db_timer = db_metrics.timer("db_timer");
-let _db_counter = db_metrics.counter("db_counter");
+```rust
+extern crate dipstick;
+use dipstick::*;
+fn main() {   
+    let app_metrics = Stream::to_stdout().metrics();
+    let db_metrics = app_metrics.named("database");
+    let _db_timer = db_metrics.timer("db_timer");
+    let _db_counter = db_metrics.counter("db_counter");
+}
 ```
 
 
@@ -112,13 +120,17 @@ Notes about labels:
   
 Metric inputs are usually setup statically upon application startup.
 
-```$rust,skt-run
+```rust
+#[macro_use]
+extern crate dipstick;
+use dipstick::*;
+
 metrics!("my_app" => {
     COUNTER_A: Counter = "counter_a";
 });
 
 fn main() {
-    Proxy::set_default_target(Stream::to_stdout().metrics());
+    Proxy::default_target(Stream::to_stdout().metrics());
     COUNTER_A.count(11);
 }
 ```
@@ -130,10 +142,15 @@ The static metric definition macro is just `lazy_static!` wrapper.
 If necessary, metrics can also be defined "dynamically". 
 This is more flexible but has a higher runtime cost, which may be alleviated with the optional caching mechanism.
 
-```$rust,skt-run
-let user_name = "john_day";
-let app_metrics = Log::to_log().cached(512).metrics();
-app_metrics.gauge(&format!("gauge_for_user_{}", user_name)).value(44);
+<<<<<<< HEAD
+```rust
+extern crate dipstick;
+use dipstick::*;
+fn main() {
+    let user_name = "john_day";
+    let app_metrics = Log::to_log().cached(512).metrics();
+    app_metrics.gauge(&format!("gauge_for_user_{}", user_name)).value(44);
+}
 ```
     
 Alternatively, you may use `Labels` to output context-dependent metrics. 
@@ -186,11 +203,16 @@ If enabled, buffering is usually a best-effort affair, to safely limit the amoun
 Some outputs such as statsd also have the ability to sample metrics.
 If enabled, sampling is done using pcg32, a fast random algorithm with reasonable entropy.
 
-```$rust,skt-run,no_run
-let _app_metrics = Statsd::send_to("server:8125")?.sampled(Sampling::Random(0.01)).metrics();
+```rust
+extern crate dipstick;
+use dipstick::*;
+fn main() {
+    let _app_metrics = Statsd::send_to("localhost:8125").expect("connected")
+        .sampled(Sampling::Random(0.01))
+        .metrics();
+}
 ```
 
-
 ## Intermediates
 
 ### Proxy

HANDBOOK.md.skt.md

@@ -1,17 +0,0 @@
-Templates
-
-Use `cargo test --features="skeptic"` to run the examples in the README using the `skeptic` crate. 
- 
-```rust,skt-run
-#[macro_use] 
-extern crate dipstick;
-use dipstick::*;
-fn main() -> std::result::Result<(), Box<std::error::Error>> {{
-    {}
-    Ok(())
-}}
-```
-
-```rust,skt-plain
-{}
-```

README.md

@@ -44,24 +44,33 @@ These are all best done by downstream timeseries visualization and monitoring to
 
 Here's a basic aggregating & auto-publish counter metric:
 
-```$rust,skt-run
-let bucket = AtomicBucket::new();
-bucket.set_drain(Stream::to_stdout());
-bucket.flush_every(std::time::Duration::from_secs(3));
-let counter = bucket.counter("counter_a");
-counter.count(8);
+```rust
+extern crate dipstick;
+use dipstick::*;
+
+fn main() {
+    let bucket = AtomicBucket::new();
+    bucket.drain(Stream::to_stdout());
+    bucket.flush_every(std::time::Duration::from_secs(3));
+    let counter = bucket.counter("counter_a");
+    counter.count(8);
+}
 ```
 
 Persistent apps wanting to declare static metrics will prefer using the `metrics!` macro:
 
-```$rust,skt-run
+```rust
+#[macro_use]
+extern crate dipstick;
+use dipstick::*;
+
 metrics! { METRICS = "my_app" => {
         pub COUNTER: Counter = "my_counter";
     }
 }
 
 fn main() {
-    METRICS.target(Graphite::send_to("localhost:2003").unwrap().metrics());
+    METRICS.set_target(Graphite::send_to("localhost:2003").expect("connected").metrics());
     COUNTER.count(32);
 }
 ```

README.md.skt.md

@@ -1,17 +0,0 @@
-Templates
-
-Use `cargo test --features="skeptic"` to run the examples in the README using the `skeptic` crate. 
- 
-```rust,skt-run
-#[macro_use] 
-extern crate dipstick;
-use dipstick::*;
-fn main() -> std::result::Result<(), Box<std::error::Error>> {{
-    {}
-    Ok(())
-}}
-```
-
-```rust,skt-plain
-{}
-```

src/bucket/atomic.rs

@@ -117,7 +117,7 @@ impl InnerAtomicBucket {
 
             let stats_fn = match self.stats {
                 Some(ref stats_fn) => stats_fn.clone(),
-                None => DEFAULT_AGGREGATE_STATS.read()?.clone(),
+                None => DEFAULT_AGGREGATE_STATS.read().expect("Aggregator").clone(),
             };
 
             for metric in snapshot {

src/core/clock.rs

@@ -26,7 +26,7 @@ impl TimeHandle {
         (duration.as_secs() * 1_000_000) + duration.subsec_micros() as u64
     }
 
-    /// Get the elapsed time in microseconds since TimeHandle was obtained.
+    /// Get the elapsed time in milliseconds since TimeHandle was obtained.
     pub fn elapsed_ms(self) -> MetricValue {
         (self.elapsed_us() / 1000) as isize
     }

src/core/error.rs

@@ -1,5 +1,6 @@
-use std::error::Error;
 use std::result;
+use std::error;
 
 /// Just put any error in a box.
-pub type Result<T> = result::Result<T, Box<Error>>;
+pub type Result<T> = result::Result<T, Box<error::Error + Send + Sync>>;
+

src/core/input.rs

@@ -141,12 +141,12 @@ impl Marker {
 }
 
 /// A counter of absolute observed values (non-negative amounts).
-/// Used to count to count things that can not be undone:
+/// Used to count things that cannot be undone:
 /// - Bytes sent
 /// - Records written
 /// - Apples eaten
 /// For relative (possibly negative) values, the `Level` counter type can be used.
-/// If ag0gregated, minimum and maximum scores will track the collected values, not their sum.
+/// If aggregated, minimum and maximum scores will track the collected values, not their sum.
 #[derive(Debug, Clone)]
 pub struct Counter {
     inner: InputMetric,
@@ -160,7 +160,7 @@ impl Counter {
 }
 
 /// A counter of fluctuating resources accepting positive and negative values.
-/// Can be used as a stateful `Gauge` or a as `Counter` of possibly decreasing amounts.
+/// Can be used as a stateful `Gauge` or as a `Counter` of possibly decreasing amounts.
 /// - Size of messages in a queue
 /// - Strawberries on a conveyor belt
 /// If aggregated, minimum and maximum scores will track the sum of values, not the collected values themselves.