diff --git a/Cargo.toml b/Cargo.toml index 2d1d3e3..0c416b5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,7 +6,7 @@ members = [ "metrics-util", "metrics-exporter-log", "metrics-exporter-http", - "metrics-observer-text", + "metrics-observer-yaml", "metrics-observer-prometheus", "metrics-observer-json", ] diff --git a/README.md b/README.md index 1b04271..cf7af29 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,17 @@ # metrics -[![conduct-badge][]][conduct] [![downloads-badge][] ![release-badge][]][crate] [![docs-badge][]][docs] [![license-badge][]](#license) +[![conduct-badge][]][conduct] [![license-badge][]](#license) [![gitter-badge][]][gitter] ![last-commit-badge][] ![contributors-badge][] [conduct-badge]: https://img.shields.io/badge/%E2%9D%A4-code%20of%20conduct-blue.svg -[downloads-badge]: https://img.shields.io/crates/d/metrics.svg -[release-badge]: https://img.shields.io/crates/v/metrics.svg -[license-badge]: https://img.shields.io/crates/l/metrics.svg -[docs-badge]: https://docs.rs/metrics/badge.svg +[license-badge]: https://img.shields.io/badge/license-MIT-blue [conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md -[crate]: https://crates.io/crates/metrics -[docs]: https://docs.rs/metrics +[gitter-badge]: https://img.shields.io/gitter/room/metrics-rs/community +[gitter]: https://gitter.im/metrics-rs/community +[last-commit-badge]: https://img.shields.io/github/last-commit/metrics-rs/metrics +[contributors-badge]: https://img.shields.io/github/contributors/metrics-rs/metrics -__metrics__ is a high-quality, batteries-included metrics library for Rust. + +The Metrics project: a metrics ecosystem for Rust. ## code of conduct @@ -19,50 +19,63 @@ __metrics__ is a high-quality, batteries-included metrics library for Rust. # what's it all about? -Running applications in production can be hard when you don't have insight into what the application is doing. We're lucky to have so many good system monitoring programs and services to show us how are servers are performing, but we still have to do the work of instrumenting our applications to gain deep insight into their behavior and performance. +Running applications in production can be hard when you don't have insight into what the application is doing. We're lucky to have so many good system monitoring programs and services to show us how our servers are performing, but we still have to do the work of instrumenting our applications to gain deep insight into their behavior and performance. -`metrics` makes it easy to instrument your application to provide real-time insight into what's happening. It provides a straight-forward interface for you to collect metrics at different points, and a flexible approach to exporting those metrics in a way that meets your needs. +_Metrics_ makes it easy to instrument your application to provide real-time insight into what's happening. It provides a number of practical features that make it easy for library and application authors to start collecting and exporting metrics from their codebase. + +# why would I collect metrics? Some of the most common scenarios for collecting metrics from an application: - see how many times a codepath was hit - track the time it takes for a piece of code to execute - expose internal counters and values in a standardized way -The number of reasons why you'd want to collect metrics is too large to list out here, and some applications emit metrics that have nothing to do with the application performance itself! Ultimately, `metrics` strives to simply provide support for the most basic types of metrics so that you can spend more time focusing on the data you'd like to collect and less time on how you're going to accomplish that. +Importantly, this works for both library authors and application authors. If the libraries you use are instrumented, you unlock the power of being able to collect those metrics in your application for free, without any extra configuration. Everyone wins, and learns more about their application performance at the end of the day. -## high-level technical features -- Supports the three most common metric types: counters, gauges, and histograms. -- Based on `metrics-core` for composability at the exporter level. -- Access to ultra-high-speed timing facilities out-of-the-box with [quanta](https://github.com/nuclearfurnace/quanta). -- Scoped metrics for effortless nesting. -- Bundled with Prometheus pull endpoint capabilities by default. +# project goals -## project layout +Firstly, we want to establish standardized interfaces by which everyone can interoperate: this is the goal of the `metrics` and `metrics-core` crates. -Metrics provide a way to gather metrics from your application. Exporters provide a way to get data outside of the application and observers tell the exporters what format to use. +`metrics` provides macros similar to `log`, which are essentially zero cost and invisible when not in use, but automatically funnel their data when a user opts in and installs a metrics recorder. This allows library authors to instrument their libraries without needing to care which metrics system end users will be utilizing. -Application developers can use the `metrics-runtime` crate to get running quickly. +`metrics-core` provides foundational traits for core components of the metrics ecosystem, primarily the output side. There are a large number of output formats and transports that application authors may consider or want to use. By focusing on the API boundary between the systems that collect metrics and the systems they're exported to, these pieces can be easily swapped around depending on the needs of the end user. -* [`metrics`]: Provides macros similar to the `log` crate. +Secondly, we want to provide a best-in-class reference runtime: this is the goal of the `metrics-runtime` crate. -* [`metrics-core`]: Defines foundational traits for interoperable metrics libraries. +Unfortunately, a great interface is no good without a suitable implementation, and we want to make sure that for users looking to instrument their applications for the first time, that they have a batteries-included option that gets them off to the races quickly. The `metrics-runtime` crate provides a best-in-class implementation of a metrics collection system, including support for the core metric types -- counters, gauges, and histograms -- as well as support for important features such as scoping, labels, flexible approaches to recording, and more. -* [`metrics-exporter-http`]: Exports metrics over an HTTP server. +On top of that, collecting metrics isn't terribly useful unless you can export those values, and so `metrics-runtime` pulls in a small set of default observers and exporters to allow users to quickly set up their application to be observable by their existing downstream metrics aggregation/storage. -* [`metrics-exporter-log`]: Exports metrics by outputting to console using the `log` crate. +# project layout -* [`metrics-observer-json`]: Encodes metrics in the JSON format. +The Metrics project provides a number of crates for both library and application authors. -* [`metrics-observer-prometheus`]: Encodes metrics in the Prometheus exposition format. +If you're a library author, you'll only care about using [`metrics`] to instrument your library. If you're an application author, you'll primarily care about [`metrics-runtime`], but you may also want to use [`metrics`] to make instrumenting your own code even easier. -* [`metrics-observer-text`]: Encodes metrics as text suitable for console logging. +Overall, this repository is home to the following crates: -* [`metrics-runtime`]: A batteries included metrics library. +* [`metrics`][metrics]: A lightweight metrics facade, similar to [`log`](https://docs.rs/log). +* [`metrics-core`][metrics-core]: Foundational traits for interoperable metrics libraries. +* [`metrics-runtime`][metrics-runtime]: A batteries-included metrics library. +* [`metrics-exporter-http`][metrics-exporter-http]: A metrics-core compatible exporter for serving metrics over HTTP. +* [`metrics-exporter-log`][metrics-exporter-log]: A metrics-core compatible exporter for forwarding metrics to logs. +* [`metrics-observer-json`][metrics-observer-json]: A metrics-core compatible observer that outputs JSON. +* [`metrics-observer-yaml`][metrics-observer-yaml]: A metrics-core compatible observer that outputs YAML. +* [`metrics-observer-prometheus`][metrics-observer-prometheus]: A metrics-core compatible observer that outputs the Prometheus exposition format. +* [`metrics-util`][metrics-util]: Helper types/functions used by the metrics ecosystem. -* [`metrics-util`]: Helper library used in the metrics ecosystem. +# contributing -## performance +We're always looking for users who have thoughts on how to make metrics better, or users with interesting use cases. Of course, we're also happy to accept code contrbutions for outstanding feature requests! 😀 -High. `metrics` is fast enough that you'll barely notice the overhead. +We'd love to chat about any of the above, or anything else, really! You can find us over on [Gitter](https://gitter.im/metrics-rs-community). -There is a `benchmark` example in the crate that can be run to see the type of performance achievable on your system. A 2015 MacBook Pro (4c/8t, 2.1GHz) can push over 5 million samples per second from a single thread. +[metrics]: https://github.com/metrics-rs/metrics/tree/master/metrics +[metrics-core]: https://github.com/metrics-rs/metrics/tree/master/metrics-core +[metrics-runtime]: https://github.com/metrics-rs/metrics/tree/master/metrics-runtime +[metrics-exporter-http]: https://github.com/metrics-rs/metrics/tree/master/metrics-exporter-http +[metrics-exporter-log]: https://github.com/metrics-rs/metrics/tree/master/metrics-exporter-log +[metrics-observer-json]: https://github.com/metrics-rs/metrics/tree/master/metrics-observer-json +[metrics-observer-yaml]: https://github.com/metrics-rs/metrics/tree/master/metrics-observer-yaml +[metrics-observer-prometheus]: https://github.com/metrics-rs/metrics/tree/master/metrics-observer-prometheus +[metrics-util]: https://github.com/metrics-rs/metrics/tree/master/metrics-util diff --git a/metrics-core/CHANGELOG.md b/metrics-core/CHANGELOG.md new file mode 100644 index 0000000..3116d8f --- /dev/null +++ b/metrics-core/CHANGELOG.md @@ -0,0 +1,39 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.5.0] - 2019-07-29 +### Added +- `Key` now supports labels. (#27) +- `Builder` for building observers in a more standardized way. (#30) + +### Changed +- `Recorder` is now `Observer`. (#35) + +## [0.4.0] - 2019-06-11 +### Added +- Add `Key` as the basis for metric names. (#20) +- Add `AsNanoseconds` for defining types that can be used for start/end times. (#20) + +## [0.3.1] - 2019-04-30 +### Removed +- Removed extraneous import. + +## [0.3.0] - 2019-04-30 +### Added +- Added snapshot traits for composable snapshotting. (#8) + +### Changed +- Reduced stuttering in type names. (#8) + +## [0.2.0] - 2019-04-23 +### Changed +- Changed from "exporter" to "recorder" in type names, documentation, etc. + +## [0.1.2] - 2019-03-26 +### Added +- Effective birth of the crate -- earlier versions were purely for others to experiment with. (#1) diff --git a/metrics-core/Cargo.toml b/metrics-core/Cargo.toml index d766f1a..4f0471e 100644 --- a/metrics-core/Cargo.toml +++ b/metrics-core/Cargo.toml @@ -1,20 +1,16 @@ [package] name = "metrics-core" -version = "0.4.0" +version = "0.5.0" authors = ["Toby Lawrence "] edition = "2018" license = "MIT" -description = "Foundational traits for interoperable metrics libraries in Rust." - +description = "Foundational traits for interoperable metrics libraries." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" documentation = "https://docs.rs/metrics-core" - readme = "README.md" +categories = ["development-tools::debugging"] keywords = ["metrics", "interface", "common"] - -[dependencies] -futures = "^0.1" diff --git a/metrics-core/README.md b/metrics-core/README.md index f8f781b..f2d1dd2 100644 --- a/metrics-core/README.md +++ b/metrics-core/README.md @@ -7,7 +7,7 @@ [release-badge]: https://img.shields.io/crates/v/metrics-core.svg [license-badge]: https://img.shields.io/crates/l/metrics-core.svg [docs-badge]: https://docs.rs/metrics-core/badge.svg -[conduct]: https://github.com/metrics-rs/metrics-core/blob/master/CODE_OF_CONDUCT.md +[conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md [crate]: https://crates.io/crates/metrics-core [docs]: https://docs.rs/metrics-core diff --git a/metrics-exporter-http/CHANGELOG.md b/metrics-exporter-http/CHANGELOG.md new file mode 100644 index 0000000..7b64689 --- /dev/null +++ b/metrics-exporter-http/CHANGELOG.md @@ -0,0 +1,19 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.2.0] - 2019-07-29 +### Changed +- Switch to metrics-core 0.5.0. + +## [0.1.2] - 2019-05-11 +### Changed +- Switch to metrics-core 0.4.0. + +## [0.1.0] - 2019-05-05 +### Added +- Effective birth of the crate. diff --git a/metrics-exporter-http/Cargo.toml b/metrics-exporter-http/Cargo.toml index 3183476..033cc43 100644 --- a/metrics-exporter-http/Cargo.toml +++ b/metrics-exporter-http/Cargo.toml @@ -1,19 +1,21 @@ [package] name = "metrics-exporter-http" -version = "0.1.2" +version = "0.2.0" authors = ["Toby Lawrence "] edition = "2018" license = "MIT" -description = "metric exporter for serving metrics over HTTP" - +description = "A metrics-core compatible exporter for serving metrics over HTTP." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" documentation = "https://docs.rs/metrics-exporter-http" readme = "README.md" +categories = ["development-tools::debugging"] +keywords = ["metrics", "metrics-core", "exporter", "http"] + [dependencies] -metrics-core = { path = "../metrics-core", version = "^0.4" } +metrics-core = { path = "../metrics-core", version = "^0.5" } hyper = "^0.12" log = "^0.4" diff --git a/metrics-exporter-http/README.md b/metrics-exporter-http/README.md index 61f15e6..f8b82df 100644 --- a/metrics-exporter-http/README.md +++ b/metrics-exporter-http/README.md @@ -7,11 +7,11 @@ [release-badge]: https://img.shields.io/crates/v/metrics-exporter-http.svg [license-badge]: https://img.shields.io/crates/l/metrics-exporter-http.svg [docs-badge]: https://docs.rs/metrics-exporter-http/badge.svg -[conduct]: https://github.com/metrics-rs/metrics-exporter-http/blob/master/CODE_OF_CONDUCT.md +[conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md [crate]: https://crates.io/crates/metrics-exporter-http [docs]: https://docs.rs/metrics-exporter-http -__metrics-exporter-http__ is a metric exporter that outputs metrics over HTTP. +__metrics-exporter-http__ is a metrics-core compatible exporter for serving metrics over HTTP. ## code of conduct diff --git a/metrics-exporter-log/CHANGELOG.md b/metrics-exporter-log/CHANGELOG.md new file mode 100644 index 0000000..60596bc --- /dev/null +++ b/metrics-exporter-log/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.3.0] - 2019-07-29 +### Changed +- Switch to metrics-core 0.5.0. + +## [0.2.1] - 2019-06-11 +### Changed +- Switch to metrics-core 0.4.0. + +## [0.2.0] - 2019-05-01 +### Changed +- Switch to metrics-core 0.3.0. + +## [0.1.0] - 2019-04-23 +### Added +- Effective birth of the crate. diff --git a/metrics-exporter-log/Cargo.toml b/metrics-exporter-log/Cargo.toml index cf299d4..4da3875 100644 --- a/metrics-exporter-log/Cargo.toml +++ b/metrics-exporter-log/Cargo.toml @@ -1,20 +1,22 @@ [package] name = "metrics-exporter-log" -version = "0.2.1" +version = "0.3.0" authors = ["Toby Lawrence "] edition = "2018" license = "MIT" -description = "metric exporter for outputting to logs" - +description = "A metrics-core compatible exporter for forwarding metrics to logs." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" documentation = "https://docs.rs/metrics-exporter-log" readme = "README.md" +categories = ["development-tools::debugging"] +keywords = ["metrics", "metrics-core", "exporter", "log"] + [dependencies] -metrics-core = { path = "../metrics-core", version = "^0.4" } +metrics-core = { path = "../metrics-core", version = "^0.5" } log = "^0.4" futures = "^0.1" tokio-timer = "^0.2" diff --git a/metrics-exporter-log/README.md b/metrics-exporter-log/README.md index c0d82fe..289191a 100644 --- a/metrics-exporter-log/README.md +++ b/metrics-exporter-log/README.md @@ -7,11 +7,11 @@ [release-badge]: https://img.shields.io/crates/v/metrics-exporter-log.svg [license-badge]: https://img.shields.io/crates/l/metrics-exporter-log.svg [docs-badge]: https://docs.rs/metrics-exporter-log/badge.svg -[conduct]: https://github.com/metrics-rs/metrics-exporter-log/blob/master/CODE_OF_CONDUCT.md +[conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md [crate]: https://crates.io/crates/metrics-exporter-log [docs]: https://docs.rs/metrics-exporter-log -__metrics-exporter-log__ is a metric exporter that outputs metrics in a textual format via the `log` crate. +__metrics-exporter-log__ is a metrics-core compatible exporter for forwarding metrics to logs. ## code of conduct diff --git a/metrics-observer-json/CHANGELOG.md b/metrics-observer-json/CHANGELOG.md new file mode 100644 index 0000000..681d883 --- /dev/null +++ b/metrics-observer-json/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.0] - 2019-07-29 +### Added +- Effective birth of the crate. diff --git a/metrics-observer-json/Cargo.toml b/metrics-observer-json/Cargo.toml index 940005c..048a162 100644 --- a/metrics-observer-json/Cargo.toml +++ b/metrics-observer-json/Cargo.toml @@ -6,17 +6,17 @@ edition = "2018" license = "MIT" -description = "metric observer for JSON output" - +description = "A metrics-core compatible observer that outputs JSON." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" -documentation = "https://docs.rs/metrics-observer-text" +documentation = "https://docs.rs/metrics-observer-json" readme = "README.md" +categories = ["development-tools::debugging"] keywords = ["metrics", "telemetry", "json"] [dependencies] -metrics-core = { path = "../metrics-core", version = "^0.4" } +metrics-core = { path = "../metrics-core", version = "^0.5" } metrics-util = { path = "../metrics-util", version = "^0.3" } hdrhistogram = "^6.1" serde_json = "^1.0" diff --git a/metrics-observer-json/README.md b/metrics-observer-json/README.md index be9112b..9aeb9a2 100644 --- a/metrics-observer-json/README.md +++ b/metrics-observer-json/README.md @@ -7,11 +7,11 @@ [release-badge]: https://img.shields.io/crates/v/metrics-observer-json.svg [license-badge]: https://img.shields.io/crates/l/metrics-observer-json.svg [docs-badge]: https://docs.rs/metrics-observer-json/badge.svg -[conduct]: https://github.com/metrics-rs/metrics-observer-json/blob/master/CODE_OF_CONDUCT.md +[conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md [crate]: https://crates.io/crates/metrics-observer-json [docs]: https://docs.rs/metrics-observer-json -__metrics-observer-json__ is a metric observer that outputs JSON. +__metrics-observer-json__ is a metrics-core compatible observer that outputs JSON. ## code of conduct diff --git a/metrics-observer-json/src/lib.rs b/metrics-observer-json/src/lib.rs index e4a2d52..a8c6f6c 100644 --- a/metrics-observer-json/src/lib.rs +++ b/metrics-observer-json/src/lib.rs @@ -1,4 +1,4 @@ -//! Observes metrics in a JSON format. +//! Observes metrics in JSON format. //! //! Metric scopes are used to provide the hierarchy of metrics. As an example, for a //! snapshot with two metrics — `server.msgs_received` and `server.msgs_sent` — we would @@ -27,8 +27,8 @@ //! All histograms have the sample count of the histogram provided in the output. //! //! ```c -//! {"connect_time count":15,"connect_time min":1334,"connect_time p50":1934,"connect_time -//! p99":5330,"connect_time max":139389} +//! {"connect_time_count":15,"connect_time_min":1334,"connect_time_p50":1934, +//! "connect_time_p99":5330,"connect_time_max":139389} //! ``` //! #![deny(missing_docs)] @@ -96,7 +96,7 @@ impl Default for JsonBuilder { } } -/// Records metrics in a hierarchical, text-based format. +/// Observes metrics in JSON format. pub struct JsonObserver { pub(crate) quantiles: Vec, pub(crate) pretty: bool, diff --git a/metrics-observer-prometheus/CHANGELOG.md b/metrics-observer-prometheus/CHANGELOG.md new file mode 100644 index 0000000..681d883 --- /dev/null +++ b/metrics-observer-prometheus/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.0] - 2019-07-29 +### Added +- Effective birth of the crate. diff --git a/metrics-observer-prometheus/Cargo.toml b/metrics-observer-prometheus/Cargo.toml index 7bf14c0..0e298bd 100644 --- a/metrics-observer-prometheus/Cargo.toml +++ b/metrics-observer-prometheus/Cargo.toml @@ -1,21 +1,21 @@ [package] name = "metrics-observer-prometheus" -version = "0.3.0" +version = "0.1.0" authors = ["Toby Lawrence "] edition = "2018" license = "MIT" -description = "metric observer for Prometheus exposition output" - +description = "A metrics-core compatible observer that outputs the Prometheus exposition output." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" documentation = "https://docs.rs/metrics-observer-prometheus" readme = "README.md" +categories = ["development-tools::debugging"] keywords = ["metrics", "telemetry", "prometheus"] [dependencies] -metrics-core = { path = "../metrics-core", version = "^0.4" } +metrics-core = { path = "../metrics-core", version = "^0.5" } metrics-util = { path = "../metrics-util", version = "^0.3" } hdrhistogram = "^6.1" diff --git a/metrics-observer-prometheus/README.md b/metrics-observer-prometheus/README.md index b614a6d..99f06db 100644 --- a/metrics-observer-prometheus/README.md +++ b/metrics-observer-prometheus/README.md @@ -7,11 +7,11 @@ [release-badge]: https://img.shields.io/crates/v/metrics-observer-prometheus.svg [license-badge]: https://img.shields.io/crates/l/metrics-observer-prometheus.svg [docs-badge]: https://docs.rs/metrics-observer-prometheus/badge.svg -[conduct]: https://github.com/metrics-rs/metrics-observer-prometheus/blob/master/CODE_OF_CONDUCT.md +[conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md [crate]: https://crates.io/crates/metrics-observer-prometheus [docs]: https://docs.rs/metrics-observer-prometheus -__metrics-observer-prometheus__ is a metric observer that outputs a Prometheus exposition format. +__metrics-observer-prometheus__ is a metrics-core compatible observer that outputs the Prometheus exposition format. ## code of conduct diff --git a/metrics-observer-text/.gitignore b/metrics-observer-yaml/.gitignore similarity index 100% rename from metrics-observer-text/.gitignore rename to metrics-observer-yaml/.gitignore diff --git a/metrics-observer-yaml/CHANGELOG.md b/metrics-observer-yaml/CHANGELOG.md new file mode 100644 index 0000000..681d883 --- /dev/null +++ b/metrics-observer-yaml/CHANGELOG.md @@ -0,0 +1,11 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.1.0] - 2019-07-29 +### Added +- Effective birth of the crate. diff --git a/metrics-observer-text/CODE_OF_CONDUCT.md b/metrics-observer-yaml/CODE_OF_CONDUCT.md similarity index 100% rename from metrics-observer-text/CODE_OF_CONDUCT.md rename to metrics-observer-yaml/CODE_OF_CONDUCT.md diff --git a/metrics-observer-text/Cargo.toml b/metrics-observer-yaml/Cargo.toml similarity index 57% rename from metrics-observer-text/Cargo.toml rename to metrics-observer-yaml/Cargo.toml index b4811dd..c9baaf6 100644 --- a/metrics-observer-text/Cargo.toml +++ b/metrics-observer-yaml/Cargo.toml @@ -1,22 +1,22 @@ [package] -name = "metrics-observer-text" -version = "0.3.0" +name = "metrics-observer-yaml" +version = "0.1.0" authors = ["Toby Lawrence "] edition = "2018" license = "MIT" -description = "metric observer for hierarchical, text-based output" - +description = "A metrics-core compatible observer that outputs YAML." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" -documentation = "https://docs.rs/metrics-observer-text" +documentation = "https://docs.rs/metrics-observer-yaml" readme = "README.md" +categories = ["development-tools::debugging"] keywords = ["metrics", "telemetry", "yaml"] [dependencies] -metrics-core = { path = "../metrics-core", version = "^0.4" } +metrics-core = { path = "../metrics-core", version = "^0.5" } metrics-util = { path = "../metrics-util", version = "^0.3" } hdrhistogram = "^6.1" serde_yaml = "^0.8" diff --git a/metrics-observer-text/LICENSE b/metrics-observer-yaml/LICENSE similarity index 100% rename from metrics-observer-text/LICENSE rename to metrics-observer-yaml/LICENSE diff --git a/metrics-observer-text/README.md b/metrics-observer-yaml/README.md similarity index 56% rename from metrics-observer-text/README.md rename to metrics-observer-yaml/README.md index 3baa1d0..f669f50 100644 --- a/metrics-observer-text/README.md +++ b/metrics-observer-yaml/README.md @@ -1,17 +1,17 @@ -# metrics-observer-text +# metrics-observer-yaml [![conduct-badge][]][conduct] [![downloads-badge][] ![release-badge][]][crate] [![docs-badge][]][docs] [![license-badge][]](#license) [conduct-badge]: https://img.shields.io/badge/%E2%9D%A4-code%20of%20conduct-blue.svg -[downloads-badge]: https://img.shields.io/crates/d/metrics-observer-text.svg -[release-badge]: https://img.shields.io/crates/v/metrics-observer-text.svg -[license-badge]: https://img.shields.io/crates/l/metrics-observer-text.svg -[docs-badge]: https://docs.rs/metrics-observer-text/badge.svg -[conduct]: https://github.com/metrics-rs/metrics-observer-text/blob/master/CODE_OF_CONDUCT.md -[crate]: https://crates.io/crates/metrics-observer-text -[docs]: https://docs.rs/metrics-observer-text +[downloads-badge]: https://img.shields.io/crates/d/metrics-observer-yaml.svg +[release-badge]: https://img.shields.io/crates/v/metrics-observer-yaml.svg +[license-badge]: https://img.shields.io/crates/l/metrics-observer-yaml.svg +[docs-badge]: https://docs.rs/metrics-observer-yaml/badge.svg +[conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md +[crate]: https://crates.io/crates/metrics-observer-yaml +[docs]: https://docs.rs/metrics-observer-yaml -__metrics-observer-text__ is a metric observer that outputs a hierarchical, text-based format. +__metrics-observer-yaml__ is a metrics-core compatible observer that outputs YAML. ## code of conduct diff --git a/metrics-observer-text/src/lib.rs b/metrics-observer-yaml/src/lib.rs similarity index 89% rename from metrics-observer-text/src/lib.rs rename to metrics-observer-yaml/src/lib.rs index 67c8a24..3366639 100644 --- a/metrics-observer-text/src/lib.rs +++ b/metrics-observer-yaml/src/lib.rs @@ -1,4 +1,4 @@ -//! Observes metrics in a hierarchical, text-based format. +//! Observes metrics in YAML format. //! //! Metric scopes are used to provide the hierarchy and indentation of metrics. As an example, for //! a snapshot with two metrics — `server.msgs_received` and `server.msgs_sent` — we would @@ -24,7 +24,7 @@ //! ## Histograms //! //! Histograms are rendered with a configurable set of quantiles that are provided when creating an -//! instance of `TextBuilder`. They are formatted using human-readable labels when displayed to +//! instance of `YamlBuilder`. They are formatted using human-readable labels when displayed to //! the user. For example, 0.0 is rendered as "min", 1.0 as "max", and anything in between using //! the common "pXXX" format i.e. a quantile of 0.5 or percentile of 50 would be p50, a quantile of //! 0.999 or percentile of 99.9 would be p999, and so on. @@ -45,13 +45,13 @@ use metrics_core::{Builder, Drain, Key, Label, Observer}; use metrics_util::{parse_quantiles, MetricsTree, Quantile}; use std::collections::HashMap; -/// Builder for [`TextObserver`]. -pub struct TextBuilder { +/// Builder for [`YamlObserver`]. +pub struct YamlBuilder { quantiles: Vec, } -impl TextBuilder { - /// Creates a new [`TextBuilder`] with default values. +impl YamlBuilder { + /// Creates a new [`YamlBuilder`] with default values. pub fn new() -> Self { let quantiles = parse_quantiles(&[0.0, 0.5, 0.9, 0.95, 0.99, 0.999, 1.0]); @@ -70,11 +70,11 @@ impl TextBuilder { } } -impl Builder for TextBuilder { - type Output = TextObserver; +impl Builder for YamlBuilder { + type Output = YamlObserver; fn build(&self) -> Self::Output { - TextObserver { + YamlObserver { quantiles: self.quantiles.clone(), tree: MetricsTree::default(), histos: HashMap::new(), @@ -82,20 +82,20 @@ impl Builder for TextBuilder { } } -impl Default for TextBuilder { +impl Default for YamlBuilder { fn default() -> Self { Self::new() } } -/// Records metrics in a hierarchical, text-based format. -pub struct TextObserver { +/// Observess metrics in YAML format. +pub struct YamlObserver { pub(crate) quantiles: Vec, pub(crate) tree: MetricsTree, pub(crate) histos: HashMap>, } -impl Observer for TextObserver { +impl Observer for YamlObserver { fn observe_counter(&mut self, key: Key, value: u64) { let (levels, name) = key_to_parts(key); self.tree.insert_value(levels, name, value); @@ -120,7 +120,7 @@ impl Observer for TextObserver { } } -impl Drain for TextObserver { +impl Drain for YamlObserver { fn drain(&mut self) -> String { for (key, h) in self.histos.drain() { let (levels, name) = key_to_parts(key); @@ -128,7 +128,7 @@ impl Drain for TextObserver { self.tree.insert_values(levels, values); } - let rendered = serde_yaml::to_string(&self.tree).expect("failed to render json output"); + let rendered = serde_yaml::to_string(&self.tree).expect("failed to render yaml output"); self.tree.clear(); rendered } diff --git a/metrics-runtime/CHANGELOG.md b/metrics-runtime/CHANGELOG.md index c76d974..e78e564 100644 --- a/metrics-runtime/CHANGELOG.md +++ b/metrics-runtime/CHANGELOG.md @@ -6,6 +6,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.11.0] - 2019-07-29 +### Added +- Metrics now support labels. (#27) +- Add support for proxy metrics. (#39) + +### Changed +- `metrics` becomes `metrics-runtime` after switching the runtime and the facade crate. (#27) +- Switch from "recorders" to "observers." (#35) + +## [0.10.0] - 2019-06-11 +### Changed +- Entirely remove the event loop and switch to pure atomics. (#13) + +## [0.9.1] - 2019-05-01 +### Added +- Expose exporters/recorders via a facade module in `metrics`. (#8) + +## [0.9.0] - 2019-04-03 +### Changed +- `hotmic` is renamed to `metrics. (#2) + ## [0.8.2] - 2019-03-19 ### Added - Histograms now track the sum of all values they record, to support target systems like Prometheus. diff --git a/metrics-runtime/Cargo.toml b/metrics-runtime/Cargo.toml index 75b6540..f2ff670 100644 --- a/metrics-runtime/Cargo.toml +++ b/metrics-runtime/Cargo.toml @@ -6,27 +6,26 @@ edition = "2018" license = "MIT" -description = "high-speed metrics collection library" - +description = "A batteries-included metrics library." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" documentation = "https://docs.rs/metrics" - readme = "README.md" +categories = ["development-tools::debugging"] keywords = ["metrics", "telemetry", "histogram", "counter", "gauge"] [features] default = ["exporters", "observers"] exporters = ["metrics-exporter-log", "metrics-exporter-http"] -observers = ["metrics-observer-text", "metrics-observer-json", "metrics-observer-prometheus"] +observers = ["metrics-observer-yaml", "metrics-observer-json", "metrics-observer-prometheus"] [[bench]] name = "histogram" harness = false [dependencies] -metrics-core = { path = "../metrics-core", version = "^0.4" } +metrics-core = { path = "../metrics-core", version = "^0.5" } metrics-util = { path = "../metrics-util", version = "^0.3" } metrics = { path = "../metrics", version = "^0.11", features = ["std"] } im = "^12" @@ -36,10 +35,10 @@ hashbrown = "^0.5" quanta = "^0.3" futures = "^0.1" crossbeam-utils = "^0.6" -metrics-exporter-log = { path = "../metrics-exporter-log", version = "^0.2", optional = true } -metrics-exporter-http = { path = "../metrics-exporter-http", version = "^0.1", optional = true } -metrics-observer-text = { path = "../metrics-observer-text", version = "^0.3", optional = true } -metrics-observer-prometheus = { path = "../metrics-observer-prometheus", version = "^0.3", optional = true } +metrics-exporter-log = { path = "../metrics-exporter-log", version = "^0.3", optional = true } +metrics-exporter-http = { path = "../metrics-exporter-http", version = "^0.2", optional = true } +metrics-observer-yaml = { path = "../metrics-observer-yaml", version = "^0.1", optional = true } +metrics-observer-prometheus = { path = "../metrics-observer-prometheus", version = "^0.1", optional = true } metrics-observer-json = { path = "../metrics-observer-json", version = "^0.1", optional = true } [dev-dependencies] diff --git a/metrics-runtime/README.md b/metrics-runtime/README.md index 834f64d..87519b8 100644 --- a/metrics-runtime/README.md +++ b/metrics-runtime/README.md @@ -3,15 +3,15 @@ [![conduct-badge][]][conduct] [![downloads-badge][] ![release-badge][]][crate] [![docs-badge][]][docs] [![license-badge][]](#license) [conduct-badge]: https://img.shields.io/badge/%E2%9D%A4-code%20of%20conduct-blue.svg -[downloads-badge]: https://img.shields.io/crates/d/metrics.svg -[release-badge]: https://img.shields.io/crates/v/metrics.svg -[license-badge]: https://img.shields.io/crates/l/metrics.svg -[docs-badge]: https://docs.rs/metrics/badge.svg +[downloads-badge]: https://img.shields.io/crates/d/metrics-runtime.svg +[release-badge]: https://img.shields.io/crates/v/metrics-runtime.svg +[license-badge]: https://img.shields.io/crates/l/metrics-runtime.svg +[docs-badge]: https://docs.rs/metrics-runtime/badge.svg [conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md -[crate]: https://crates.io/crates/metrics -[docs]: https://docs.rs/metrics +[crate]: https://crates.io/crates/metrics-runtime +[docs]: https://docs.rs/metrics-runtime -__metrics__ is a high-quality, batteries-included metrics library for Rust. +__metrics__ is a batteries-included metrics library. ## code of conduct @@ -19,26 +19,21 @@ __metrics__ is a high-quality, batteries-included metrics library for Rust. # what's it all about? -Running applications in production can be hard when you don't have insight into what the application is doing. We're lucky to have so many good system monitoring programs and services to show us how are servers are performing, but we still have to do the work of instrumenting our applications to gain deep insight into their behavior and performance. +`metrics-runtime` is the high-quality, batteries-included reference metrics runtime for the Metrics project. -`metrics` makes it easy to instrument your application to provide real-time insight into what's happening. It provides a straight-forward interface for you to collect metrics at different points, and a flexible approach to exporting those metrics in a way that meets your needs. +This crate serves to provide support for all of the goals espoused by the project as a whole: a runtime that can be used with `metrics`, support for interoperating with `metrics-core` compatible observers and exporters. On top of that, it provides a deliberately designed API meant to help you quickly and easily instrument your application. -Some of the most common scenarios for collecting metrics from an application: -- see how many times a codepath was hit -- track the time it takes for a piece of code to execute -- expose internal counters and values in a standardized way - -The number of reasons why you'd want to collect metrics is too large to list out here, and some applications emit metrics that have nothing to do with the application performance itself! Ultimately, `metrics` strives to simply provide support for the most basic types of metrics so that you can spend more time focusing on the data you'd like to collect and less time on how you're going to accomplish that. +As operators of systems at scale, we've attempted to distill this library down to the core features necessary to successfully instrument an application and ensure that you succeed at providing observability into your production systems. ## high-level technical features - Supports the three most common metric types: counters, gauges, and histograms. -- Based on `metrics-core` for composability at the exporter level. +- Based on `metrics-core` for composability at the observer/exporter level. - Access to ultra-high-speed timing facilities out-of-the-box with [quanta](https://github.com/nuclearfurnace/quanta). -- Scoped metrics for effortless nesting. -- Bundled with Prometheus pull endpoint capabilities by default. +- Scoped and labeled metrics for rich dimensionality. +- Bundled with a number of useful observers/exporters: export your metrics with ease. ## performance -High. `metrics` is fast enough that you'll barely notice the overhead. +Even as a reference runtime, `metrics-runtime` still has extremely impressive performance. On modern cloud systems, you'll be able to ingest millions of samples per second per core with p99 latencies in the low hundreds of nanoseconds. While `metrics-runtime` will not be low-enough overhead for every use case, it will meet or exceed the performance of other metrics libraries in Rust and in turn providing you wih fast and predictably low-overhead measurements under production workloads. -There is a `benchmark` example in the crate that can be run to see the type of performance achievable on your system. A 2015 MacBook Pro (4c/8t, 2.1GHz) can push over 5 million samples per second from a single thread. +There are a few example benchmark programs in the crate that simulate basic workloads. These programs specifically do not attempt to fully simulate a production workload, in terms of number of metrics, frequency of ingestion, or dimensionality. They are brute force benchmarks designed to showcase throughput and latency for varied concurrency profiles under high write contention. diff --git a/metrics-runtime/src/lib.rs b/metrics-runtime/src/lib.rs index 401662a..6adc83b 100644 --- a/metrics-runtime/src/lib.rs +++ b/metrics-runtime/src/lib.rs @@ -254,7 +254,7 @@ //! ```rust //! # extern crate metrics_runtime; //! use metrics_runtime::{ -//! Receiver, observers::TextBuilder, exporters::LogExporter, +//! Receiver, observers::YamlBuilder, exporters::LogExporter, //! }; //! use log::Level; //! use std::{thread, time::Duration}; @@ -279,7 +279,7 @@ //! // Now create our exporter/observer configuration, and wire it up. //! let exporter = LogExporter::new( //! receiver.get_controller(), -//! TextBuilder::new(), +//! YamlBuilder::new(), //! Level::Info, //! Duration::from_secs(5), //! ); @@ -327,7 +327,8 @@ mod sink; pub mod exporters; #[cfg(any( - feature = "metrics-observer-text", + feature = "metrics-observer-yaml", + feature = "metrics-observer-json", feature = "metrics-observer-prometheus" ))] pub mod observers; diff --git a/metrics-runtime/src/observers.rs b/metrics-runtime/src/observers.rs index 64db9bc..abdda8f 100644 --- a/metrics-runtime/src/observers.rs +++ b/metrics-runtime/src/observers.rs @@ -1,8 +1,8 @@ //! Commonly used observers. //! -//! Observers define the format of the metric output: text, JSON, etc. -#[cfg(feature = "metrics-observer-text")] -pub use metrics_observer_text::TextBuilder; +//! Observers define the format of the metric output: YAML, JSON, etc. +#[cfg(feature = "metrics-observer-yaml")] +pub use metrics_observer_yaml::YamlBuilder; #[cfg(feature = "metrics-observer-json")] pub use metrics_observer_json::JsonBuilder; diff --git a/metrics-util/CHANGELOG.md b/metrics-util/CHANGELOG.md new file mode 100644 index 0000000..c44d036 --- /dev/null +++ b/metrics-util/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.3.0] - 2019-04-30 +### Added +- `MetricTree` allows storing hierarchical metric values while being serializable by serde. (#38) + +## [0.2.1] - 2019-06-12 +Erroneously bumped/published. No changes. + +## [0.2.0] - 2019-06-11 +### Added +- `StreamingIntegers` allows holding a set of integers in a compressed format in-memory. (#13) +- `AtomicBucket` provides an append-only list of items that can be snapshot without stopping writes. (#13) + +## [0.1.0] - 2019-04-23 +### Added +- Effective birth of the crate. diff --git a/metrics-util/Cargo.toml b/metrics-util/Cargo.toml index fd256d2..b2f80ea 100644 --- a/metrics-util/Cargo.toml +++ b/metrics-util/Cargo.toml @@ -6,14 +6,13 @@ edition = "2018" license = "MIT" -description = "helper types/functions used by the metrics ecosystem" - +description = "Helper types/functions used by the metrics ecosystem." homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" documentation = "https://docs.rs/metrics-util" - readme = "README.md" +categories = ["development-tools::debugging"] keywords = ["metrics", "quantile", "percentile"] [[bench]] diff --git a/metrics-util/README.md b/metrics-util/README.md index 115f301..5b37b76 100644 --- a/metrics-util/README.md +++ b/metrics-util/README.md @@ -7,7 +7,7 @@ [release-badge]: https://img.shields.io/crates/v/metrics-util.svg [license-badge]: https://img.shields.io/crates/l/metrics-util.svg [docs-badge]: https://docs.rs/metrics-util/badge.svg -[conduct]: https://github.com/metrics-rs/metrics-util/blob/master/CODE_OF_CONDUCT.md +[conduct]: https://github.com/metrics-rs/metrics/blob/master/CODE_OF_CONDUCT.md [crate]: https://crates.io/crates/metrics-util [docs]: https://docs.rs/metrics-util diff --git a/metrics/CHANGELOG.md b/metrics/CHANGELOG.md new file mode 100644 index 0000000..faca7d0 --- /dev/null +++ b/metrics/CHANGELOG.md @@ -0,0 +1,12 @@ +# Changelog +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.11.0] - 2019-07-29 +### Added +- Life begins at 0.11.0 for this crate, after being renamed from `metrics-facade` to `metrics` to + reflect the duality of `metrics` to the `log` crate. (#27) diff --git a/metrics/CODE_OF_CONDUCT.md b/metrics/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..21dae9f --- /dev/null +++ b/metrics/CODE_OF_CONDUCT.md @@ -0,0 +1,30 @@ +# The Code of Conduct + +This document is based on the [Rust Code of Conduct](https://www.rust-lang.org/conduct.html) and outlines the standard of conduct which is both expected and enforced as part of this project. + +## Conduct + +* We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other similar characteristic. +* Avoid using overtly sexual nicknames or other nicknames that might detract from a friendly, safe and welcoming environment for all. +* Please be kind and courteous. There's no need to be mean or rude. +* Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer. +* Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works. +* We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behaviour. We interpret the term "harassment" as including the definition in the [Citizen Code of Conduct](http://citizencodeofconduct.org/); if you have any lack of clarity about what might be included in that concept, please read their definition. In particular, we don't tolerate behavior that excludes people in socially marginalized groups. +* Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or made uncomfortable by a community member, please contact one of the repository Owners immediately. Whether you're a regular contributor or a newcomer, we care about making this community a safe place for you and we've got your back. +* Likewise any spamming, trolling, flaming, baiting or other attention-stealing behaviour is not welcome. + +## Moderation + +These are the policies for upholding our community's standards of conduct. If you feel that a thread needs moderation, please use the contact information above, or mention @tobz or @LucioFranco in the thread. + +1. Remarks that violate this Code of Conduct, including hateful, hurtful, oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed, but never targeting another user, and never in a hateful manner.) +2. Remarks that moderators find inappropriate, whether listed in the code of conduct or not, are also not allowed. + +In the Rust community we strive to go the extra step to look out for each other. Don't just aim to be technically unimpeachable, try to be your best self. In particular, avoid flirting with offensive or sensitive issues, particularly if they're off-topic; this all too often leads to unnecessary fights, hurt feelings, and damaged trust; worse, it can drive people away from the community entirely. + +And if someone takes issue with something you said or did, resist the urge to be defensive. Just stop doing what it was they complained about and apologize. Even if you feel you were misinterpreted or unfairly accused, chances are good there was something you could've communicated better — remember that it's your responsibility to make your fellow Rustaceans comfortable. Everyone wants to get along and we are all here first and foremost because we want to talk about cool technology. You will find that people will be eager to assume good intent and forgive as long as you earn their trust. + +## Contacts: + +- Toby Lawrence ([toby@nuclearfurnace.com](mailto:toby@nuclearfurnace.com)) +- Lucio Franco ([luciofranco14@gmail.com](mailto:luciofranco14@gmail.com)) diff --git a/metrics/Cargo.toml b/metrics/Cargo.toml index 17aa7a2..a3d3a50 100644 --- a/metrics/Cargo.toml +++ b/metrics/Cargo.toml @@ -2,16 +2,19 @@ name = "metrics" version = "0.11.0" authors = ["Toby Lawrence "] -license = "MIT" edition = "2018" + +license = "MIT" + +description = "A lightweight metrics facade." +homepage = "https://github.com/metrics-rs/metrics" repository = "https://github.com/metrics-rs/metrics" documentation = "https://docs.rs/metrics" -description = """ -A lightweight metrics facade for Rust -""" -categories = ["development-tools::debugging"] readme = "README.md" + +categories = ["development-tools::debugging"] keywords = ["metrics", "facade"] + build = "build.rs" [[bench]] @@ -19,7 +22,7 @@ name = "macros" harness = false [dependencies] -metrics-core = { path = "../metrics-core", version = "^0.4" } +metrics-core = { path = "../metrics-core", version = "^0.5" } [dev-dependencies] log = "^0.4"