Simplify + split out readmes (#108)

* Simplify the intro descriptions * Separate readmes for crates.io and docs.rs * Fix links
autometrics-dev · Jun 2, 2023 · 11df698 · 11df698
1 parent 208593c
commit 11df698
Show file tree

Hide file tree

Showing 4 changed files with 185 additions and 121 deletions.
diff --git a/README.md b/README.md
@@ -4,11 +4,23 @@
 [![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 is an observability micro-framework built for developers.
+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 Prometheus queries to help you identify and debug issues in production.
 
-The Rust library provides a macro that makes it easy to instrument any function with the most useful metrics: request rate, error rate, and latency. Autometrics uses instrumented function names to generate Prometheus queries so you don’t need to hand-write complicated PromQL.
+## Features
+
+- ✨ [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro instruments any function or `impl` block to track the [most useful metrics](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html#generated-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
+- [🔍 Identify commits](https://docs.rs/autometrics/latest/autometrics/#build_info-metric-labels) that introduced errors or increased latency
+- [🚨 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
+- [⚙️ 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
 
-To make it easy for you to spot and debug issues in production, Autometrics inserts links to live charts directly into each function’s doc comments and provides dashboards that work out of the box. It also enables you to create powerful alerts based on Service-Level Objectives (SLOs) directly in your source code. Lastly, Autometrics writes queries that correlate your software’s version info with anomalies in the metrics to help you quickly identify commits that introduced bugs or latency.
+See [autometrics.dev](https://docs.autometrics.dev/) for more details on the ideas behind autometrics.
+
+# Example + Demo
 
 ```rust
 use autometrics::autometrics;
@@ -50,20 +62,6 @@ 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
 
-## Features
-
-- ✨ [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro instruments any function or `impl` block to track the [most useful metrics](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html#generated-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
-- [🔍 Identify commits](https://docs.rs/autometrics/latest/autometrics/#identifying-commits-that-introduced-problems) that introduced errors or increased latency
-- [🚨 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#5-configuring-prometheus) work out of the box to visualize the performance of instrumented functions & SLOs
-- [⚙️ Configurable](https://docs.rs/autometrics/latest/autometrics/#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](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) to connect metrics with traces
-- ⚡ Minimal runtime overhead
-
-See [Why Autometrics?](https://github.com/autometrics-dev#4-why-autometrics) for more details on the ideas behind autometrics.
-
 ## Quickstart
 
 1. Add `autometrics` to your project:

diff --git a/autometrics/README.md b/autometrics/README.md
@@ -1,14 +1,26 @@
+<!-- This is used on crates.io -->
+
 ![GitHub_headerImage](https://user-images.githubusercontent.com/3262610/221191767-73b8a8d9-9f8b-440e-8ab6-75cb3c82f2bc.png)
 
 [![Documentation](https://docs.rs/autometrics/badge.svg)](https://docs.rs/autometrics)
 [![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 is an observability micro-framework built for developers.
+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 Prometheus queries to help you identify and debug issues in production.
 
-The Rust library provides a macro that makes it easy to instrument any function with the most useful metrics: request rate, error rate, and latency. Autometrics uses instrumented function names to generate Prometheus queries so you don’t need to hand-write complicated PromQL.
+## Features
 
-To make it easy for you to spot and debug issues in production, Autometrics inserts links to live charts directly into each function’s doc comments and provides dashboards that work out of the box. It also enables you to create powerful alerts based on Service-Level Objectives (SLOs) directly in your source code. Lastly, Autometrics writes queries that correlate your software’s version info with anomalies in the metrics to help you quickly identify commits that introduced bugs or latency.
+- ✨ [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro instruments any function or `impl` block to track the [most useful metrics](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html#generated-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
+- [🔍 Identify commits](https://docs.rs/autometrics/latest/autometrics/#build_info-metric-labels) that introduced errors or increased latency
+- [🚨 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
+- [⚙️ 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.
 
 ## Example Axum App
 
@@ -40,91 +52,15 @@ pub async fn main() {
 }
 ```
 
-## Features
-
-- ✨ [`#[autometrics]`](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html) macro instruments any function or `impl` block to track the [most useful metrics](https://docs.rs/autometrics/latest/autometrics/attr.autometrics.html#generated-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
-- [🔍 Identify commits](#identifying-commits-that-introduced-problems) that introduced errors or increased latency
-- [🚨 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#5-configuring-prometheus) 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](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) to connect metrics with traces
-- ⚡ Minimal runtime overhead
-
-See [Why Autometrics?](https://github.com/autometrics-dev#4-why-autometrics) for more details on the ideas behind autometrics.
-
-## Identifying commits that introduced problems
-
-Autometrics makes it easy to [spot versions and commits that introduce errors or latency](https://fiberplane.com/blog/autometrics-rs-0-4-spot-commits-that-introduce-errors-or-slow-down-your-application).
-
-It produces a `build_info` metric and uses the following labels to expose the version info of your app to Prometheus:
-
-| Label | Compile-Time Environment Variables | Default |
-|---|---|---|
-| `version` | `AUTOMETRICS_VERSION` or `CARGO_PKG_VERSION` | `CARGO_PKG_VERSION` (set by cargo by default) |
-| `commit` | `AUTOMETRICS_COMMIT` or `VERGEN_GIT_COMMIT` | `""` |
-| `branch` | `AUTOMETRICS_BRANCH` or `VERGEN_GIT_BRANCH` | `""` |
-
-### (Optional) Using [`vergen`](https://crates.io/crates/vergen) to set the Git details
-
-```toml
-# Cargo.toml
-
-[build-dependencies]
-vergen = { version = "8.1", features = ["git", "gitcl"] }
-```
-
-```rust
-// build.rs
-fn main() {
-  vergen::EmitBuilder::builder()
-      .git_sha(true)
-      .git_branch()
-      .emit()
-      .expect("Unable to generate build info");
-}
-```
-
-
-## Configuring Autometrics
-
-### Custom Prometheus URL
-
-Autometrics inserts Prometheus query links into function documentation. By default, the links point to `http://localhost:9090` but you can configure it to use a custom URL using an environment variable in your `build.rs` file:
-
-```rust
-// build.rs
-
-fn main() {
-  // Reload Rust analyzer after changing the Prometheus URL to regenerate the links
-  let prometheus_url = "https://your-prometheus-url.example";
-  println!("cargo:rustc-env=PROMETHEUS_URL={prometheus_url}");
-}
-```
-
-### Feature flags
-
-- `prometheus-exporter` - exports a Prometheus metrics collector and exporter (compatible with any of the [Metrics backends](#metrics-backends))
-- `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](https://github.com/autometrics-dev/autometrics-rs/tree/main/autometrics-cli)).
-
-#### Metrics backends
-
-**Required:** Configure which library autometrics will use to produce metrics by using one of the following feature flags:
-
-> **Note**
->
-> If you are **not** using the `prometheus-exporter`, you must ensure that you are using the exact same version of the metrics library as `autometrics` (and it must come from `crates.io` rather than git or another source). If not, the autometrics metrics will not appear in your exported metrics.
+## Quickstart
 
-- `opentelemetry`  - use the [opentelemetry](https://crates.io/crates/opentelemetry) crate for producing metrics.
-- `metrics` - use the [metrics](https://crates.io/crates/metrics) crate for producing metrics
-- `prometheus` - use the [prometheus](https://crates.io/crates/prometheus) crate for producing metrics
-- `prometheus-client` - use the official [prometheus-client](https://crates.io/crates/prometheus-client) crate for producing metrics
+See the [Github repo README](https://github.com/autometrics-dev/autometrics-rs#quickstart) to quickly add `autometrics` to your project.
 
-#### Exemplars (for integrating metrics with traces)
+## Contributing
 
-See the [exemplars module docs](https://docs.rs/autometrics/latest/autometrics/exemplars/index.html) for details about these features. Currently only supported with the `prometheus-client` backend.
+Issues, feature suggestions, and pull requests are very welcome!
 
-- `exemplars-tracing` - extract arbitrary fields from `tracing::Span`s
-- `exemplars-tracing-opentelemetry` - extract the `trace_id` and `span_id` from the `opentelemetry::Context`, which is attached to `tracing::Span`s by the `tracing-opentelemetry` crate
+If you are interested in getting involved:
+- Join the conversation on [Discord](https://discord.gg/9eqGEs56UB)
+- Ask questions and share ideas in the [Github Discussions](https://github.com/orgs/autometrics-dev/discussions)
+- Take a look at the overall [Autometrics Project Roadmap](https://github.com/orgs/autometrics-dev/projects/1)