Split out advanced features from benefits section

README.md

@@ -4,19 +4,26 @@
 [![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)
 
-Autometrics provides a macro that makes it easy to instrument any function with the most useful metrics: request rate, error rate, and latency. It then uses the instrumented function names to generate powerful Prometheus queries to help you identify and debug issues in production.
+Metrics are a powerful and cost-efficient tool for understanding the health and performance of your code in production. But it's hard to decide what metrics to track and even harder to write queries to understand the data.
 
-## Features
+Autometrics provides a macro that makes it trivial to instrument any function with the most useful metrics: request rate, error rate, and latency. It standardizes these metrics and then generates powerful Prometheus queries based on your function details to help you quickly identify and debug issues in production.
 
-- ✨ [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro instruments any function or `impl` block to track the [most useful metrics](https://github.com/autometrics-dev/autometrics-shared/blob/main/SPEC.md#metrics)
-- 💡 Writes Prometheus queries so you can understand the data generated without knowing PromQL
+## Benefits
+
+- [✨ `#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro adds useful metrics to any function or `impl` block, without you thinking about what metrics to collect
+- 💡 Generates powerful Prometheus queries to help quickly identify and debug issues in production
 - 🔗 Injects links to live Prometheus charts directly into each function's doc comments
-- [🔍 Identify commits](https://docs.rs/autometrics/latest/autometrics/#identifying-faulty-commits-with-the-build_info-metric) that introduced errors or increased latency
+- [📊 Grafana dashboards](https://github.com/autometrics-dev/autometrics-shared#dashboards) work without configuration to visualize the performance of functions & [SLOs](https://docs.rs/autometrics/latest/autometrics/objectives/index.html)
+- 🔍 Correlates your code's version with metrics to help [identify commits](https://docs.rs/autometrics/latest/autometrics/#identifying-faulty-commits-with-the-build_info-metric) that introduced errors or latency
+- 📏 Standardizes metrics across services and teams to improve debugging
+- ⚖️ Function-level metrics provide useful granularity without exploding cardinality
+- [⚡ Minimal runtime overhead](#benchmarks)
+
+## Advanced Features
+
 - [🚨 Define alerts](https://docs.rs/autometrics/latest/autometrics/objectives/index.html) using SLO best practices directly in your source code
-- [📊 Grafana dashboards](https://github.com/autometrics-dev/autometrics-shared#dashboards) work out of the box to visualize the performance of instrumented functions & SLOs
+- [📍 Attach exemplars](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) automatically to connect metrics with traces
 - [⚙️ Configurable](https://docs.rs/autometrics/latest/autometrics/#metrics-backends) metric collection library ([`opentelemetry`](https://crates.io/crates/opentelemetry), [`prometheus`](https://crates.io/crates/prometheus), [`prometheus-client`](https://crates.io/crates/prometheus-client) or [`metrics`](https://crates.io/crates/metrics))
-- [📍 Attach exemplars](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) to connect metrics with traces
-- ⚡ Minimal runtime overhead
 
 See [autometrics.dev](https://docs.autometrics.dev/) for more details on the ideas behind autometrics.
 
@@ -27,37 +34,10 @@ use autometrics::autometrics;
 
 #[autometrics]
 pub async fn create_user() {
-  // Now this function has metrics! 📈
+  // Now this function produces metrics! 📈
 }
 ```
 
-<details>
-<summary>See an example of a PromQL query generated by Autometrics</summary>
-
-<br />
-
-  _If your eyes glaze over when you see this, don't worry! Autometrics writes complex queries like this so you don't have to!_
-
-  ```promql
-    (
-      sum by (function, module, commit, version) (
-          rate({__name__=~"function_calls(_count)?(_total)?",function="create_user",result="error"}[5m])
-        * on (instance, job) group_left (version, commit)
-          last_over_time(build_info[1s])
-      )
-    )
-  /
-    (
-      sum by (function, module, commit, version) (
-          rate({__name__=~"function_calls(_count)?(_total)?",function="create_user"}[5m])
-        * on (instance, job) group_left (version, commit)
-          last_over_time(build_info[1s])
-      )
-    )
-  ```
-
-</details>
-
 Here is a demo of jumping from function docs to live Prometheus charts:
 
 https://github.com/autometrics-dev/autometrics-rs/assets/3262610/966ed140-1d6c-45f3-a607-64797d5f0233
@@ -70,6 +50,27 @@ https://github.com/autometrics-dev/autometrics-rs/assets/3262610/966ed140-1d6c-4
     ```
 2. Instrument your functions with the [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro
 
+    ```rust
+    use autometrics::autometrics;
+
+    // Just add the autometrics annotation to your functions
+    #[autometrics]
+    pub async fn my_function() {
+      // Now this function produces metrics!
+    }
+
+    struct MyStruct;
+
+    // You can also instrument whole impl blocks
+    #[autometrics]
+    impl MyStruct {
+      pub fn my_method() {
+        // This method produces metrics too!
+      }
+    }
+    ```
+
+
     <details>
 
     <summary> Tip: Adding autometrics to all functions using the <a href="https://docs.rs/tracing/latest/tracing/instrument/trait.Instrument.html"><code>tracing::instrument</code></a> macro

autometrics/README.md

@@ -6,19 +6,26 @@
 [![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)
 
-Autometrics provides a macro that makes it easy to instrument any function with the most useful metrics: request rate, error rate, and latency. It then uses the instrumented function names to generate powerful Prometheus queries to help you identify and debug issues in production.
+Metrics are a powerful and cost-efficient tool for understanding the health and performance of your code in production. But it's hard to decide what metrics to track and even harder to write queries to understand the data.
 
-## Features
+Autometrics provides a macro that makes it trivial to instrument any function with the most useful metrics: request rate, error rate, and latency. It standardizes these metrics and then generates powerful Prometheus queries based on your function details to help you quickly identify and debug issues in production.
 
-- ✨ [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro instruments any function or `impl` block to track the [most useful metrics](https://github.com/autometrics-dev/autometrics-shared/blob/main/SPEC.md#metrics)
-- 💡 Writes Prometheus queries so you can understand the data generated without knowing PromQL
+## Benefits
+
+- [✨ `#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro adds useful metrics to any function or `impl` block, without you thinking about what metrics to collect
+- 💡 Generates powerful Prometheus queries to help quickly identify and debug issues in production
 - 🔗 Injects links to live Prometheus charts directly into each function's doc comments
-- [🔍 Identify commits](https://docs.rs/autometrics/latest/autometrics/#identifying-faulty-commits-with-the-build_info-metric) that introduced errors or increased latency
+- [📊 Grafana dashboards](https://github.com/autometrics-dev/autometrics-shared#dashboards) work without configuration to visualize the performance of functions & [SLOs](https://docs.rs/autometrics/latest/autometrics/objectives/index.html)
+- 🔍 Correlates your code's version with metrics to help [identify commits](https://docs.rs/autometrics/latest/autometrics/#identifying-faulty-commits-with-the-build_info-metric) that introduced errors or latency
+- 📏 Standardizes metrics across services and teams to improve debugging
+- ⚖️ Function-level metrics provide useful granularity without exploding cardinality
+- [⚡ Minimal runtime overhead](#benchmarks)
+
+## Advanced Features
+
 - [🚨 Define alerts](https://docs.rs/autometrics/latest/autometrics/objectives/index.html) using SLO best practices directly in your source code
-- [📊 Grafana dashboards](https://github.com/autometrics-dev/autometrics-shared#dashboards) work out of the box to visualize the performance of instrumented functions & SLOs
+- [📍 Attach exemplars](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) automatically to connect metrics with traces
 - [⚙️ Configurable](https://docs.rs/autometrics/latest/autometrics/#metrics-backends) metric collection library ([`opentelemetry`](https://crates.io/crates/opentelemetry), [`prometheus`](https://crates.io/crates/prometheus), [`prometheus-client`](https://crates.io/crates/prometheus-client) or [`metrics`](https://crates.io/crates/metrics))
-- [📍 Attach exemplars](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) to connect metrics with traces
-- ⚡ Minimal runtime overhead
 
 See [autometrics.dev](https://docs.autometrics.dev/) for more details on the ideas behind autometrics.
 

autometrics/src/README.md

@@ -6,19 +6,26 @@
 [![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)
 
-Autometrics provides a macro that makes it easy to instrument any function with the most useful metrics: request rate, error rate, and latency. It then uses the instrumented function names to generate powerful Prometheus queries to help you identify and debug issues in production.
+Metrics are a powerful and cost-efficient tool for understanding the health and performance of your code in production. But it's hard to decide what metrics to track and even harder to write queries to understand the data.
 
-## Features
+Autometrics provides a macro that makes it trivial to instrument any function with the most useful metrics: request rate, error rate, and latency. It standardizes these metrics and then generates powerful Prometheus queries based on your function details to help you quickly identify and debug issues in production.
 
-- ✨ [`#[autometrics]`](autometrics) macro instruments any function or `impl` block to track the [most useful metrics](https://github.com/autometrics-dev/autometrics-shared/blob/main/SPEC.md#metrics)
-- 💡 Writes Prometheus queries so you can understand the data generated without knowing PromQL
+## Benefits
+
+- [✨ `#[autometrics]`](autometrics) macro adds useful metrics to any function or `impl` block, without you thinking about what metrics to collect
+- 💡 Generates powerful Prometheus queries to help quickly identify and debug issues in production
 - 🔗 Injects links to live Prometheus charts directly into each function's doc comments
-- [🔍 Identify commits](#identifying-faulty-commits-with-the-build_info-metric) that introduced errors or increased latency
+- [📊 Grafana dashboards](https://github.com/autometrics-dev/autometrics-shared#dashboards) work without configuration to visualize the performance of functions & [SLOs](objectives)
+- 🔍 Correlates your code's version with metrics to help [identify commits](#identifying-faulty-commits-with-the-build_info-metric) that introduced errors or latency
+- 📏 Standardizes metrics across services and teams to improve debugging
+- ⚖️ Function-level metrics provide useful granularity without exploding cardinality
+- [⚡ Minimal runtime overhead](https://github.com/autometrics-dev/autometrics-rs#benchmarks)
+
+## Advanced Features
+
 - [🚨 Define alerts](objectives) using SLO best practices directly in your source code
-- [📊 Grafana dashboards](https://github.com/autometrics-dev/autometrics-shared#dashboards) work out of the box to visualize the performance of instrumented functions & SLOs
-- [⚙️ Configurable](#metrics-libraries) metric collection library ([`opentelemetry`](https://crates.io/crates/opentelemetry), [`prometheus`](https://crates.io/crates/prometheus), [`prometheus-client`](https://crates.io/crates/prometheus-client) or [`metrics`](https://crates.io/crates/metrics))
-- [📍 Attach exemplars](exemplars) to connect metrics with traces
-- ⚡ Minimal runtime overhead
+- [📍 Attach exemplars](exemplars) automatically to connect metrics with traces
+- [⚙️ Configurable](#metrics-backends) metric collection library ([`opentelemetry`](https://crates.io/crates/opentelemetry), [`prometheus`](https://crates.io/crates/prometheus), [`prometheus-client`](https://crates.io/crates/prometheus-client) or [`metrics`](https://crates.io/crates/metrics))
 
 See [autometrics.dev](https://docs.autometrics.dev/) for more details on the ideas behind autometrics.