Bump version 0.6.3 (#193)

* Bump version 0.6.3 Signed-off-by: Andy Lok <[email protected]> * fix Signed-off-by: Andy Lok <[email protected]> * update readme Signed-off-by: Andy Lok <[email protected]> * fix Signed-off-by: Andy Lok <[email protected]> --------- Signed-off-by: Andy Lok <[email protected]>
tikv · Jan 26, 2024 · ee49263 · ee49263
1 parent 4ff0f87
commit ee49263
Show file tree

Hide file tree

Showing 10 changed files with 175 additions and 54 deletions.
diff --git a/.github/workflows/typo.yml b/.github/workflows/typo.yml
@@ -0,0 +1,35 @@
+name: Typos Check
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+env:
+  RUST_BACKTRACE: 1
+
+jobs:
+  typos-check:
+    name: typos check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      FORCE_COLOR: 1
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          clean: "true"
+
+      - uses: baptiste0928/cargo-install@v1
+        with:
+          crate: typos-cli
+          args: --locked
+          cache-key: typos-check
+
+      - name: do typos check with typos-cli
+        run: typos
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,8 +2,11 @@
 
 ## Unreleased
 
+## v0.6.3
+
 - Add `LocalSpans::to_span_records()`.
 - Add `#[trace(properties = { "k1": "v1", "k2": "v2" })]`.
+- Add  `func_name!()`, `full_name!()`, and `file_location!()` to `minitrace::prelude`.
 
 ## v0.6.2
 

diff --git 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 every time the function is called, 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 detect the function's full name, which is used as 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]: minitrace/examples/get_started.rs
 [Examples]: minitrace/examples
 [OpenTelemetry]: https://opentelemetry.io/
 [Jaeger]: https://crates.io/crates/minitrace-jaeger

diff --git a/minitrace-datadog/Cargo.toml b/minitrace-datadog/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "minitrace-datadog"
-version = "0.6.2"
+version = "0.6.3"
 authors = ["The TiKV Project Authors"]
 license = "Apache-2.0"
 edition = "2021"
@@ -13,7 +13,7 @@ categories = ["development-tools::debugging"]
 keywords = ["tracing", "span", "datadog", "jaeger", "opentelemetry"]
 
 [dependencies]
-minitrace = { version = "0.6.2", path = "../minitrace" }
+minitrace = { version = "0.6.3", path = "../minitrace" }
 reqwest = { version = "0.11", features = ["blocking"] }
 rmp-serde = "1"
 serde = { version = "1", features = ["derive"] }

diff --git a/minitrace-jaeger/Cargo.toml b/minitrace-jaeger/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "minitrace-jaeger"
-version = "0.6.2"
+version = "0.6.3"
 authors = ["The TiKV Project Authors"]
 license = "Apache-2.0"
 edition = "2021"
@@ -14,7 +14,7 @@ keywords = ["tracing", "span", "datadog", "jaeger", "opentelemetry"]
 
 [dependencies]
 log = "0.4"
-minitrace = { version = "0.6.2", path = "../minitrace" }
+minitrace = { version = "0.6.3", path = "../minitrace" }
 thrift_codec = "0.2"
 
 [dev-dependencies]

diff --git a/minitrace-macro/Cargo.toml b/minitrace-macro/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "minitrace-macro"
-version = "0.6.2"
+version = "0.6.3"
 authors = ["The TiKV Project Authors"]
 license = "Apache-2.0"
 edition = "2021"
@@ -24,7 +24,7 @@ syn = { version = "1.0.84", features = ["full", "parsing", "extra-traits", "proc
 
 [dev-dependencies]
 logcall = "0.1.4"
-minitrace = { version = "0.6.2", path = "../minitrace" }
+minitrace = { version = "0.6.3", path = "../minitrace" }
 tokio = { version = "1", features = ["full"] }
 trybuild = "1"
 # The procedural macro `trace` only supports async-trait higher than 0.1.52

diff --git a/minitrace-opentelemetry/Cargo.toml b/minitrace-opentelemetry/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "minitrace-opentelemetry"
-version = "0.6.2"
+version = "0.6.3"
 authors = ["The TiKV Project Authors"]
 license = "Apache-2.0"
 edition = "2021"
@@ -15,7 +15,7 @@ keywords = ["tracing", "span", "datadog", "jaeger", "opentelemetry"]
 [dependencies]
 futures = { version = "0.3", features = ["executor"] }
 log = "0.4"
-minitrace = { version = "0.6.2", path = "../minitrace" }
+minitrace = { version = "0.6.3", path = "../minitrace" }
 opentelemetry = { version = "0.21", features = ["trace"] }
 opentelemetry_sdk = { version = "0.21", features = ["trace"] }
 

diff --git a/minitrace/Cargo.toml b/minitrace/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "minitrace"
-version = "0.6.2"
+version = "0.6.3"
 authors = ["The TiKV Project Authors"]
 license = "Apache-2.0"
 edition = "2021"
@@ -17,7 +17,7 @@ enable = []
 
 [dependencies]
 futures = "0.3"
-minitrace-macro = { version = "0.6.2", path = "../minitrace-macro" }
+minitrace-macro = { version = "0.6.3", path = "../minitrace-macro" }
 minstant = "0.1"
 parking_lot = "0.12"
 pin-project = "1"
@@ -37,9 +37,9 @@ futures-timer = "3"
 log = "0.4"
 logcall = "0.1.4"
 minitrace = { path = ".", features = ["enable"] }
-minitrace-datadog = { version = "0.6.2", path = "../minitrace-datadog" }
-minitrace-jaeger = { version = "0.6.2", path = "../minitrace-jaeger" }
-minitrace-opentelemetry = { version = "0.6.2", path = "../minitrace-opentelemetry" }
+minitrace-datadog = { version = "0.6.3", path = "../minitrace-datadog" }
+minitrace-jaeger = { version = "0.6.3", path = "../minitrace-jaeger" }
+minitrace-opentelemetry = { version = "0.6.3", path = "../minitrace-opentelemetry" }
 mockall = "0.11"
 once_cell = "1"
 opentelemetry = { version = "0.21", features = ["trace"] }