More detailed top-line description (#65)

autometrics/README.md

@@ -4,29 +4,34 @@
 [![Crates.io](https://img.shields.io/crates/v/autometrics.svg)](https://crates.io/crates/autometrics)
 [![Discord Shield](https://discordapp.com/api/guilds/950489382626951178/widget.png?style=shield)](https://discord.gg/kHtwcH8As9)
 
-**A Rust macro that makes it easy to understand the error rate, response time, and production usage of any function in your code.**
+Autometrics is an open source framework that makes it easy to understand the health and performance of your code in production.
 
-Jump from your IDE to live Prometheus charts for each HTTP/RPC handler, database method, or other piece of application logic.
+The Rust library provides a macro that makes it trivial to track the most useful metrics for any function: request rate, error rate, and lantency. It then generates Prometheus queries to help you understand the data collected and inserts links to the live charts directly into each function's doc comments.
 
-<video src="https://user-images.githubusercontent.com/3262610/220152261-2ad6ab2b-f951-4b51-8d6e-855fb71440a3.mp4" autoplay loop muted width="100%"></video>
+Autometrics also provides Grafana dashboards to get an overview of instrumented functions and enables you to create powerful alerts based on Service-Level Objectives (SLOs) directly in your source code.
 
 ```rust
 use autometrics::autometrics;
 
 #[autometrics]
 pub async fn create_user() {
-  // Now this function will be producing metrics!
+  // Now this function will have metrics!
 }
 ```
 
+Here is a demo of jumping from function docs to live Prometheus charts:
+
+<video src="https://user-images.githubusercontent.com/3262610/220152261-2ad6ab2b-f951-4b51-8d6e-855fb71440a3.mp4" autoplay loop muted width="100%"></video>
+
+
 ## Features
 
 - ✨ [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro instruments any function or `impl` block to track the most useful metrics
 - 💡 Writes Prometheus queries so you can understand the data generated without knowing PromQL
 - 🔗 Injects links to live Prometheus charts directly into each function's doc comments
-- 📊 Grafana dashboards to visualize the performance of all instrumented functions
-- 🚨 Enable Prometheus alerts using SLO best practices from simple annotations in your code
-- ⚙️ Configurable metric collection library (`opentelemetry`, `prometheus`, or `metrics`)
+- [🚨 Define alerts](#alerts--slos) using SLO best practices directly in your source code
+- [📊 Grafana dashboards](#dashboards) work out of the box to visualize the performance of instrumented functions & SLOs
+- [⚙️ Configurable](#metrics-libraries) metric collection library (`opentelemetry`, `prometheus`, or `metrics`)
 - ⚡ Minimal runtime overhead
 
 See [Why Autometrics?](https://github.com/autometrics-dev#why-autometrics) for more details on the ideas behind autometrics.
@@ -53,7 +58,7 @@ Or run the example in Gitpod:
 
 ## Exporting Prometheus Metrics
 
-Prometheus works by polling a specific HTTP endpoint on your server to collect the current state of all the metrics it has in memory.
+Prometheus works by polling an HTTP endpoint on your server to collect the current values of all the metrics it has in memory.
 
 ### For projects not currently using Prometheus metrics
 
@@ -89,7 +94,7 @@ pub fn get_metrics() -> (http::StatusCode, String) {
 
 Autometrics uses existing metrics libraries (see [below](#metrics-libraries)) to produce and collect metrics.
 
-If you are already using one of these to collect and export metrics, simply configure autometrics to use the same library and the metrics it produces will be exported alongside yours. You do not need to use the Prometheus exporter functions this library provides and you do not need a separate endpoint for autometrics' metrics.
+If you are already using one of these to collect metrics, simply configure autometrics to use the same library and the metrics it produces will be exported alongside yours. You do not need to use the Prometheus exporter functions this library provides and you do not need a separate endpoint for autometrics' metrics.
 
 ## Dashboards
 
@@ -123,9 +128,7 @@ Once you've added objectives to your code, you can use the [Autometrics Service-
 
 ### Custom Prometheus URL
 
-By default, Autometrics creates Prometheus query links that point to `http://localhost:9090`.
-
-You can configure a custom Prometheus URL using a build-time environment in your `build.rs` file:
+Autometrics creates Prometheus query links that point to `http://localhost:9090` by default but you can configure it to use a custom URL using an environment variable in your `build.rs` file:
 
 ```rust
 // build.rs
@@ -138,13 +141,13 @@ fn main() {
 
 When using Rust Analyzer, you may need to reload the workspace in order for URL changes to take effect.
 
-Note that the Prometheus URL is only included in function documentation comments so changing it will have no impact on the final compiled binary.
+The Prometheus URL is only included in documentation comments so changing it will have no impact on the final compiled binary.
 
 ### Feature flags
 
 - `prometheus-exporter` - exports a Prometheus metrics collector and exporter (compatible with any of the Metrics Libraries)
-- `custom-objective-latency` - by default, Autometrics only supports a fixed set of latency thresholds for objectives. Enable this to use custom latency thresholds. Note, however, that the custom latency must match one of the buckets configured for your histogram, meaning you will not be able to use the default Prometheus exporter. This is not currently compatible with the `prometheus` or `prometheus-exporter` feature.
-- `custom-objective-percentile` by default, Autometrics only supports a fixed set of objective percentiles. Enable this to use a custom percentile. Note, however, that using custom percentiles requires generating a different recording and alerting rules file using the CLI + Sloth.
+- `custom-objective-latency` - by default, Autometrics only supports a fixed set of latency thresholds for objectives. Enable this to use custom latency thresholds. Note, however, that the custom latency **must** match one of the buckets configured for your histogram or the alerts will not work. This is not currently compatible with the `prometheus` or `prometheus-exporter` feature.
+- `custom-objective-percentile` by default, Autometrics only supports a fixed set of objective percentiles. Enable this to use a custom percentile. Note, however, that using custom percentiles requires generating a different recording and alerting rules file using the CLI + Sloth (see [here](../autometrics-cli/)).
 
 #### Metrics Libraries