What's the best way for Rust developers to get started?

[cartermp]

I was re-learning Rust last evening with aims to figure out how to write a decent Getting Started article. But I realized pretty quickly that there's some decision points to make about such an article, and I'm not equipped to make those decisions:

• What's the best web server framework to center the guide around? E.g., what's "Flask but for Rust"?
• As far as I can tell there's no automatic instrumentation packages (like for Actix). Should the guide still center around creating a span on an incoming request?
• The otel-rust API has two ways to create spans - tracer.in_span which takes care of the span lifecycle and borrowing semantics at the cost of nesting code, and tracer.start which requires you to manage the span more intricately. Which is better for beginners? Why?
• OTel for Rust also provides bindings for the Tokio Tracing framework, letting you use those APIs and then making the data OTel-compatible. Is this the best way for people to start instead?

Would definitely appreciate @open-telemetry/rust-approvers and anyone who uses Rust with OTel to weigh in here 🙂

[marcusradell]

I think https://github.com/lukemathwalker/tracing-actix-web could be worth exploring.

We are setting up a Rust backend against Honeycomb right now and will open source our progress here: https://github.com/deversify/dev_api/blob/main/src/tracing.rs

When we solved a few kinks, we can document it more if it's of value to the community.

The best guide for me so far has been Luca Palmieri's Zero to Prod book and the articles. I know that there are links to some of his content via tracing-actix-web.

[marcusradell]

The best way to log things seem to be to add the #[tracing::instrument(...)] attribute on top of different functions. Especially for async functions.

[djc]

Yeah, I definitely think going through tracing (with opentelemetry-tracing) is the easiest/most idiomatic way to get going.

[TommyCpp]

• What's the best web server framework to center the guide around? E.g., what's "Flask but for Rust"?

I don't think there is a most famous/widely used web server framework in Rust. actix web and axum maybe two that worthing looking.

• As far as I can tell there's no automatic instrumentation packages (like for Actix). Should the guide still center around creating a span on an incoming request?

We do have integration with actix in https://github.com/OutThereLabs/actix-web-opentelemetry

• The otel-rust API has two ways to create spans - tracer.in_span which takes care of the span lifecycle and borrowing semantics at the cost of nesting code, and tracer.start which requires you to manage the span more intricately. Which is better for beginners? Why?

Personally, I think tracer.in_span may be easier. I have seen cases where the span gets dropped immediately because users didn't name them(something like let _ = tracer.start())

• OTel for Rust also provides bindings for the Tokio Tracing framework, letting you use those APIs and then making the data OTel-compatible. Is this the best way for people to start instead?

Rust is unique as it already has tracing before opentelemetry developed. Thus, it's easier for Rust developers to use tracing-opentelemetry so that they don't have to understand too much about opentelemetry. But I also find that if you are working with multiple languages and you want to compare the behavior of different languages instrumentation. At some point, you will have to understand the mapping between the tracing API and opentelemetry API.

[svrnm]

We have a rust getting started now, so some requirements for this issue have been resolved. But I think there is some more that needs to be done (e.g. how much we need to write something about tracing, etc.)

[cartermp]

@cijothomas has the rust sig come to a consensus on how to get started? I'm fine with keeping this open since we do have a getting started page now, although it does not use the tracing crate.

[cijothomas]

@cijothomas has the rust sig come to a consensus on how to get started? I'm fine with keeping this open since we do have a getting started page now, although it does not use the tracing crate.

Not really :-( We are trying to resolve the fundamental question of using OTel Tracing API vs the tracing one!
open-telemetry/opentelemetry-rust#1571

I didn't see this particular issue until now. Will share an update here once we resolve open-telemetry/opentelemetry-rust#1571. It'll be ~1-2 months before a decision is made (the actual implementation, could take more time, depending on the decided path)

https://opentelemetry.io/docs/languages/rust/getting-started/ is a reasonable start using only OTel Tracing API. It doesn't look like its taking care of context propagation/restoration. If the intention was for the getting-started guide to showcase context propagation/restoration, then https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples/tracing-http-propagator is a good source to adopt from.
if the intention is to just act as a minimal "hello world" style, then the current state is okay.

[cartermp]

Sounds good!

[svrnm]

https://opentelemetry.io/docs/languages/rust/getting-started/ is a reasonable start using only OTel Tracing API. It doesn't look like its taking care of context propagation/restoration. If the intention was for the getting-started guide to showcase context propagation/restoration, then https://github.com/open-telemetry/opentelemetry-rust/tree/main/examples/tracing-http-propagator is a good source to adopt from.

if the intention is to just act as a minimal "hello world" style, then the current state is okay.

I wrote that getting started guide for rust without having that much experience with rust, so it's basic and needs some love and attention, so if it can be made better in any way let's go for it. For the context propagation we could take that existing example and create an additional page on that topic similar to the pages on that subject we have for other languages.