Added Getting Started section in the README #403

lunchboxav · 2019-10-24T09:17:54Z

This PR addresses #384.

Motivation

I'm adding a Getting Started section in the README, which includes code and explanation. Hopefully, this will ease new users of tracing to get up to speed. The current doc is amazing, but adding an explicit Getting Started section might also be useful.

Solution

a Getting Started section with code example and a brief explanation of what the code does.

hawkw

This seems like a good start, thanks for working on this! Here are some suggestions for improving the docs.

I've not had the chance to review the entire PR yet, so I'll probably have more notes later today.

hawkw · 2019-10-24T15:59:48Z

README.md

+
+```
+[dependencies]
+tracing = "0.1.5"


This should probably be the latest release version:

Suggested change

tracing = "0.1.5"

tracing = "0.1.10"

hawkw · 2019-10-24T16:06:57Z

README.md

@@ -34,12 +34,93 @@ Application-level tracing for Rust.
 structured, event-based diagnostic information. `tracing` is maintained by the
 Tokio project, but does _not_ require the `tokio` runtime to be used.

+## Getting Started
+
+To get started, configure `Cargo.toml` to include `tracing` and `tracing-subscriber` as dependencies. `tracing` is the core library, while `tracing-subscriber` is the part that implements `Subscriber`, which will record the trace. Take a look at the [Project layout](#Project layout) section.


How about:

Suggested change

To get started, configure `Cargo.toml` to include `tracing` and `tracing-subscriber` as dependencies. `tracing` is the core library, while `tracing-subscriber` is the part that implements `Subscriber`, which will record the trace. Take a look at the [Project layout](#Project layout) section.

To get started, add dependencies on `tracing` and `tracing-subscriber` to your `Cargo.toml`. The `tracing` crate provides the _instrumentation_ APIs for emitting traces, while `tracing-subscriber` provides implementations of the `Subscriber` trait, which will record the trace. For more information on the crates that make up the `tracing` project, take a look at the [Project layout](#Project layout) section.

hawkw · 2019-10-24T16:07:17Z

README.md

+
+Next, in our `main.rs` file, we will start by adding the libraries
+
+```


Add

Suggested change

```

```rust

to get Rust syntax highlighting here.

hawkw · 2019-10-24T16:07:31Z

README.md

+
+To get started, configure `Cargo.toml` to include `tracing` and `tracing-subscriber` as dependencies. `tracing` is the core library, while `tracing-subscriber` is the part that implements `Subscriber`, which will record the trace. Take a look at the [Project layout](#Project layout) section.
+
+```


Add

Suggested change

```

```toml

to get toml syntax highlighting.

hawkw · 2019-10-24T16:07:54Z

README.md

+
+For this simple example, we will create a function that prints sequence of numbers and we will instrument that cod to enable tracing. Tracing is enabled by initiating a span and the `#[instrument]` attribute, implicitly create a span for that function.
+
+```


Suggested change

```

```rust

hawkw · 2019-10-24T16:17:04Z

README.md

+
+```
+fn main() {
+ // this creates subscriber with an environment filter


Personally, I'd prefer to start by introducing how to create and set a subscriber with the default filter

let subscriber = fmt::Subscriber::default(); tracing::subscriber::with_default(subscriber, || { // ... });

and then introduce customizing the filter after we demonstrate the default...

hawkw · 2019-10-24T16:17:22Z

README.md

+
+Then, in our `main()` function, we can create a subscriber, that records the trace. The subscriber employs an environment filter that we can utilize to filter the level of tracing message.
+
+```


Suggested change

```

```rust

hawkw · 2019-10-24T16:17:29Z

README.md

+
+Finally, we can run the function that prints out the tracing message while it's being run
+
+```


Suggested change

```

```rust

hawkw · 2019-10-24T16:18:15Z

README.md

+ let filter = tracing_subscriber::EnvFilter::try_from_default_env()
+ .unwrap_or_else(|_| DEFAULT_FILTER.into());
+ let subscriber = fmt::Subscriber::builder().with_env_filter(filter).finish();
+ ...


it would be nice if this was valid rust code that actually compiles...we could make the "..." a comment so it's not a syntax error:

Suggested change

...

// ...

hawkw · 2019-10-24T16:18:31Z

README.md

+
+```
+fn main() {
+ ...


again, consider:

Suggested change

...

// ...

lunchboxav · 2019-10-25T03:51:47Z

Thank you very much for the thorough comments @hawkw. I'll improve the PR :)

hawkw · 2019-11-07T22:28:03Z

hi @lunchboxav, now that the "batteries-included" init and try_init functions in tracing-subscriber::fmt have been released in version 0.1.6, can we use them in the introductory docs when applicable? should be more ergonomic for simple tasks

lunchboxav · 2019-11-08T00:03:13Z

sure thing @hawkw . I'll play around with init and try-init and I'll update the doc. Should be good for setting up subscriber for getting started.

Signed-off-by: Adityo Pratomo <adityo@tetrate.io>

lunchboxav · 2019-11-09T03:45:18Z

PTAL @hawkw. I'm torn between keeping example of using subscriber's default or just remove it since we have init. I'm keeping both for now, but I'm open to the idea of just use init as a preferred way to get started with tracing.

lunchboxav · 2020-01-08T23:40:41Z

Should I close this PR as well @hawkw? Considering that the issue this PR wanted to solve has already solved.

hawkw · 2020-01-09T00:41:55Z

@lunchboxav hmm... sorry about that! i'll have to take a closer look at the examples in this PR vs the ones added in #496, as we may still want to add some of the examples in this branch as well!

lunchboxav · 2020-01-09T01:04:39Z

That’s completely fine @hawkw. I haven’t had the time too keep up with the recent movement in this repo, so I may missed some significant bits. Just let me know what I can help in this PR :)

added Getting Started section in the README

2872c89

hawkw reviewed Oct 24, 2019

View reviewed changes

addressed review on README

f1ff04e

hawkw mentioned this pull request Oct 28, 2019

Implemented Default trait for Dispatch in tracing-core #411

Merged

lunchboxav requested a review from hawkw October 30, 2019 05:53

add information about subscriber's init

8b4aa9e

Signed-off-by: Adityo Pratomo <adityo@tetrate.io>

hawkw added the meta/finish-line PRs that need just a bit more work to be ready to merge. label Dec 20, 2019

hawkw closed this Feb 6, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added Getting Started section in the README #403

Added Getting Started section in the README #403

lunchboxav commented Oct 24, 2019

hawkw left a comment

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

hawkw Oct 24, 2019

lunchboxav commented Oct 25, 2019

hawkw commented Nov 7, 2019

lunchboxav commented Nov 8, 2019

lunchboxav commented Nov 9, 2019

lunchboxav commented Jan 8, 2020

hawkw commented Jan 9, 2020

lunchboxav commented Jan 9, 2020


		Next, in our `main.rs` file, we will start by adding the libraries

		```


		To get started, configure `Cargo.toml` to include `tracing` and `tracing-subscriber` as dependencies. `tracing` is the core library, while `tracing-subscriber` is the part that implements `Subscriber`, which will record the trace. Take a look at the [Project layout](#Project layout) section.

		```


		For this simple example, we will create a function that prints sequence of numbers and we will instrument that cod to enable tracing. Tracing is enabled by initiating a span and the `#[instrument]` attribute, implicitly create a span for that function.

		```


		Then, in our `main()` function, we can create a subscriber, that records the trace. The subscriber employs an environment filter that we can utilize to filter the level of tracing message.

		```


		Finally, we can run the function that prints out the tracing message while it's being run

		```

Added Getting Started section in the README #403

Added Getting Started section in the README #403

Conversation

lunchboxav commented Oct 24, 2019

Motivation

Solution

hawkw left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lunchboxav commented Oct 25, 2019

hawkw commented Nov 7, 2019

lunchboxav commented Nov 8, 2019

lunchboxav commented Nov 9, 2019

lunchboxav commented Jan 8, 2020

hawkw commented Jan 9, 2020

lunchboxav commented Jan 9, 2020