Documentation fixes (autometrics-dev#11)

* Add description and license to macros crate

* Fix typo in dependency

* Use unicode emojis

* Remove git link from readme

* Show prometheus exporter on docs.rs

* Add module doc comments

* Use github link in docs

Author: emschwartz

Cargo.toml

@@ -18,7 +18,7 @@ prometheus-exporter = ["once_cell", "opentelemetry-prometheus", "prometheus"]
 autometrics-macros = { version = "0.1.0", path = "./macros" }
 const_format = { version = "0.2", features = ["rust_1_51"] }
 opentelemetry_api = { version = "0.18", default-features = false, features = ["metrics"] }
-opentelemetry_sdk = { verison = "0.18", default-features = false, features = ["metrics"] }
+opentelemetry_sdk = { version = "0.18", default-features = false, features = ["metrics"] }
 
 # Used for prometheus-exporter feature
 once_cell = { version = "1.17", optional = true }

README.md

@@ -1,20 +1,20 @@
-# Autometrics :chart_with_upwards_trend: :sparkles:
+# Autometrics 📈✨
 > Easily add metrics to your system -- and actually understand them using automatically customized Prometheus queries.
 
 [![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)
 
 Metrics are powerful and relatively inexpensive, but they are still hard to use. Developers need to:
-- Think about what metrics to track and which metric type to use (counter, gauge... :confused:)
-- Figure out how to write PromQL or another query language to get some data :confounded:
-- Verify that the data returned actually answers the right question :tired_face:
+- Think about what metrics to track and which metric type to use (counter, gauge... 😕)
+- Figure out how to write PromQL or another query language to get some data 😖
+- Verify that the data returned actually answers the right question 😫
 
 Autometrics makes it easy to add metrics to any function in your codebase.
-Then, automatically generates common Prometheus for each function to help you easily understand the data.
+Then, it automatically generates common Prometheus for each function to help you easily understand the data.
 Explore your production metrics directly from your editor/IDE.
 
-### :one: Add `#[autometrics]` to your code
+### 1️⃣ Add `#[autometrics]` to your code
 
 ```rust
 #[autometrics]
@@ -23,15 +23,15 @@ async fn create_user(Json(payload): Json<CreateUser>) -> Result<Json<User>, ApiE
 }
 ```
 
-### :two: Hover over the function name to see the generated queries
+### 2️⃣ Hover over the function name to see the generated queries
 
 <img src="./assets/vs-code-example.png" alt="VS Code Hover Example" width="500">
 
-### :three: Click a query link to go directly to the Prometheus chart for that function
+### 3️⃣ Click a query link to go directly to the Prometheus chart for that function
 
 <img src="./assets/prometheus-chart.png" alt="Prometheus Chart" width="500">
 
-### :four: Go back to shipping features :rocket:
+### 4️⃣ Go back to shipping features 🚀
 
 ## See it in action
 
@@ -95,21 +95,21 @@ Autometrics includes optional functions to help collect and prepare metrics to b
 In your `Cargo.toml` file, enable the optional `prometheus-exporter` feature:
 
 ```toml
-autometrics = { git = "ssh://[email protected]/fiberplane/autometrics-rs.git", branch = "main", features = ["prometheus-exporter"] }
+autometrics = { version = "*", features = ["prometheus-exporter"] }
 ```
 
 Then, call the `global_metrics_exporter` function in your `main` function:
 ```rust
 pub fn main() {
-  let _exporter = global_metrics_exporter();
+  let _exporter = autometrics::global_metrics_exporter();
   // ...
 }
 ```
 
 And create a route on your API (probably mounted under `/metrics`) that returns the following:
 ```rust
 pub fn get_metrics() -> (StatusCode, String) {
-  match encode_global_metrics() {
+  match autometrics::encode_global_metrics() {
     Ok(metrics) => (StatusCode::OK, metrics),
     Err(err) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{:?}", err))
   }

macros/Cargo.toml

@@ -2,6 +2,14 @@
 name = "autometrics-macros"
 version = "0.1.0"
 edition = "2021"
+authors = ["Fiberplane <[email protected]>", "Evan Schwartz <[email protected]>"]
+description = "Macros for the autometrics crate"
+documentation = "https://docs.rs/autometrics"
+readme = "../README.md"
+repository = "https://github.com/fiberplane/autometrics-rs"
+license = "MIT OR Apache-2.0"
+keywords = ["metrics", "prometheus", "opentelemetry"]
+categories = ["development-tools::profiling"]
 
 [lib]
 proc-macro = true

macros/src/lib.rs

@@ -21,7 +21,7 @@ const DEFAULT_PROMETHEUS_URL: &str = "http://localhost:9090";
 ///
 /// For all of the generated metrics, Autometrics attaches the following labels:
 /// - `function` - the name of the function
-/// - `module` - the module path of the function (with `::` replaced by `_`)
+/// - `module` - the module path of the function (with `::` replaced by `.`)
 ///
 /// For the function call counter, Autometrics attaches these additional labels:
 /// - `result` - if the function returns a `Result`, this will either be `ok` or `error`

src/lib.rs

@@ -1,10 +1,54 @@
+//! # Autometrics
+//!
+//! Autometrics is a library that makes it easy to collect metrics for any function
+//! -- and easily understand the data with automatically generated Prometheus queries for each function.
+//!
+//! ## Example
+//! See the [example](https://github.com/fiberplane/autometrics-rs/blob/main/examples/axum.rs) for a full example of how to use Autometrics.
+//!
+//! ## Usage
+//! 1. Annotate any function with `#[autometrics]` to collect metrics for that function:
+//!
+//! ```rust
+//! #[autometrics]
+//! async fn create_user(Json(payload): Json<CreateUser>) -> Result<Json<User>, ApiError> {
+//!   // ...
+//! }
+//! ```
+//!
+//! 2. Call the `global_metrics_exporter` function in your `main` function:
+//! ```rust
+//! pub fn main() {
+//!   let _exporter = autometrics::global_metrics_exporter();
+//!   // ...
+//! }
+//! ```
+//!
+//! 3. Create a route on your API (probably mounted under `/metrics`) for Prometheus to scrape:
+//! ```rust
+//! pub fn get_metrics() -> (StatusCode, String) {
+//!   match autometrics::encode_global_metrics() {
+//!     Ok(metrics) => (StatusCode::OK, metrics),
+//!     Err(err) => (StatusCode::INTERNAL_SERVER_ERROR, format!("{:?}", err))
+//!   }
+//! }
+//! ```
+//!
+//! 4. Hover over any autometrics-enabled function to see the links to graphs of the generated metrics
+//! 5. Click on the link to see the graph of the live metrics for that function
+//!
+//! ## Feature flags
+//!
+//! - `prometheus-exporter`: Exports a Prometheus metrics collector and exporter
+//!
 mod labels;
 #[cfg(feature = "prometheus-exporter")]
 mod prometheus;
 mod task_local;
 mod tracker;
 
 #[cfg(feature = "prometheus-exporter")]
+#[cfg_attr(docsrs, doc(cfg(feature = "prometheus-exporter")))]
 pub use self::prometheus::*;
 pub use autometrics_macros::autometrics;