From f4f82548399e6602e01b117c9d8da4932934b1af Mon Sep 17 00:00:00 2001
From: Andy Lok <andylokandy@hotmail.com>
Date: Fri, 26 Jan 2024 01:42:20 +0800
Subject: [PATCH] update readme

Signed-off-by: Andy Lok <andylokandy@hotmail.com>
---
 README.md            | 69 ++++++++++++++++++++++++++++++++++++++++++--
 minitrace/src/lib.rs |  8 ++---
 2 files changed, 71 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 0aefcdc2..db218886 100644
--- a/README.md
+++ b/README.md
@@ -26,10 +26,76 @@ Features:
 ## Resources
 
 - [Docs]
-- [Getting Started]
 - [Examples]
 - [FAQ](#faq)
 
+## Getting Started
+
+## In Libraries
+
+Libraries should include `minitrace` as a dependency without enabling any extra features.
+
+```toml
+[dependencies]
+minitrace = "0.6"
+```
+
+Add a `trace` attribute to the function you want to trace. In this example, a `SpanRecord` will be collected everytime the function is alled, if a tracing context is set up by the caller.
+
+```rust
+#[minitrace::trace]
+pub fn send_request(req: HttpRequest) -> Result<(), Error> {
+    // ...
+}
+```
+
+Libraries are able to set up an individual tracing context, regardless of whether the caller has set up a tracing context or not. This can be achieved by using `Span::root()` to start a new trace and `Span::set_local_parent()` to set up a local context for the current thread.
+
+The `full_name!()` macro can auto detect the function's full name, which is usedas the name of the root span.
+
+```rust
+use minitrace::prelude::*;
+
+pub fn send_request(req: HttpRequest) -> Result<(), Error> {
+    let root = Span::root(full_name!(), SpanContext::random());
+    let _guard = root.set_local_parent();
+
+    // ...
+}
+```
+
+## In Applications
+
+Applications should include `minitrace` as a dependency with the `enable` feature set. To disable `minitrace` statically, simply remove the `enable` feature.
+
+```toml
+[dependencies]
+minitrace = { version = "0.6", features = ["enable"] }
+```
+
+Applications should initialize a `Reporter` implementation early in the program's runtime. Span records generated before the reporter is initialized will be ignored. Before terminating, `flush()` should be called to ensure all collected span records are reported.
+
+When the root span is dropped, all of its children spans and itself will be reported at once. Since that, it's recommended to create root spans for short tasks, such as handling a request, just like the example below. Otherwise, an endingless trace will never be reported.
+
+```rust
+use minitrace::collector::Config;
+use minitrace::collector::ConsoleReporter;
+use minitrace::prelude::*;
+
+fn main() {
+    minitrace::set_reporter(ConsoleReporter, Config::default());
+
+    loop {
+        let root = Span::root("worker-loop", SpanContext::random());
+        let _guard = root.set_local_parent();
+
+        handle_request();
+    }
+
+    minitrace::flush();
+}
+```
+
 ## Benchmarks
 
 **By different architectures:**
@@ -108,7 +174,6 @@ Note that we always prioritize performance over features, so that not all tracin
 **Code base Tested**: minitrace has been tested with high coverage. However, applications utilizing minitrace have not been widely deployed, so that minitrace is currently **NOT** regarded as battle-tested. 
 
 [Docs]: https://docs.rs/minitrace/
-[Getting Started]: https://docs.rs/minitrace/latest/minitrace/#getting-started
 [Examples]: minitrace/examples
 [OpenTelemetry]: https://opentelemetry.io/
 [Jaeger]: https://crates.io/crates/minitrace-jaeger
diff --git a/minitrace/src/lib.rs b/minitrace/src/lib.rs
index 70f9c547..d9ed1f8c 100644
--- a/minitrace/src/lib.rs
+++ b/minitrace/src/lib.rs
@@ -10,7 +10,7 @@
 //!
 //! # Getting Started
 //!
-//! ## Libraries
+//! ## In Libraries
 //!
 //! Libraries should include `minitrace` as a dependency without enabling any extra features.
 //!
@@ -55,9 +55,9 @@
 //! }
 //! ```
 //!
-//! ## Executables
+//! ## In Applications
 //!
-//! Executables should include `minitrace` as a dependency with the `enable` feature
+//! Applications should include `minitrace` as a dependency with the `enable` feature
 //! set. To disable `minitrace` statically, simply remove the `enable` feature.
 //!
 //! ```toml
@@ -65,7 +65,7 @@
 //! minitrace = { version = "0.6", features = ["enable"] }
 //! ```
 //!
-//! Executables should initialize a [`Reporter`] implementation early in the program's runtime.
+//! Applications should initialize a [`Reporter`] implementation early in the program's runtime.
 //! Span records generated before the reporter is initialized will be ignored. Before
 //! terminating, [`flush()`] should be called to ensure all collected span records are reported.
 //!