Tracing GA tracking

[jtescher]

Spec compliance:

• Align Value with the spec (api::Value is much more loosely typed than the spec #317)
• ShouldSample's parent context parameter (Update ShouldSample's parent parameter to be Context #290)
• New trace config max defaults (Update trace config max defaults #268)
• Ensure is_recording is false after span ends (Ensure is_recording is false after span ends #265)
• Add configuration options from environment variables (Add configuration options from environment variables #168)
• Update the default propagator to be noop (Update the default propagator to be noop #221)
• Update ExportResult: use std::result::Result type (Update ExportResult: use std::result::Result type #331)
• Decide on experimental non-specified propagators (Consider moving base64 and binary propagators to contrib #336)
• Consider moving exporters module to sdk (Consider moving exporters module to sdk #340)
• Implement SpanProcessor::force_flush (Implement SpanProcessor::force_flush #349)
• Don't send status unless ok or error in zipkin (Zipkin: Do not send status unless ok or error #355)

API ergonomics:

• Allow &str and String as parameters where possible

Backwards compatibility:

• Ensure all pub items should be exposed
• Ensure dependencies in public APIs are 1.0
• consider dropping serde feature Serde support #576

[TommyCpp]

Ensure dependencies are 1.0

Feels like would be a difficult criteria to meet now as most of the crates in Rust are pre 1.0

[jtescher]

@TommyCpp good point, clarified it to only include ones in public interfaces

[TommyCpp]

The spec around tracing has stabilized and I see they are checking with language SIG on their progress to GA on tracing in the maintainer meeting logs. We might want to review the spec and see what we are missing. I can tell we still need to add http/json and http/protobuf support for opentelemetry-otlp.

Also, we might need to add logs in our API and SDK. Now that the opentelemetry log spec has decided that they will respect log facade from languages. I think we can just use Rust's log facade to instrument the logs for now and figure out if we want to use env_logger or our otlp log SDK later.

Rust also provides a guideline on library https://rust-lang.github.io/api-guidelines/checklist.html, we could walk through this and see if there are improvements we should make.

[djc]

I think we should probably use tracing instead of log?

[TommyCpp]

I think we should probably use tracing instead of log?

@djc I am a little worried that we would have cycle dependency if we want to use opentelemetry-log for log SDK and tracing for logging API because tracing-opentelemetry depends on opentelemetry

[LukeMathWalker]

Related to @TommyCpp - have you considered splitting out the sdk module in its own crate?
It would be ideal to be able to isolate the instrumentation side (e.g. most of the traits) in a module moving faster towards 1.0 while keep iterating on the sdk side.

[TommyCpp]

have you considered splitting out the sdk module in its own crate?

That could work, but we need to first make sure the api doesn't use anything from SDK part otherwise there will be a circular dependency. Another problem is I believe there is a crate called opentelemetry-sdk already 😞

On the other hand, we can still declare API stable while working on the SDK if I understand the VERSIONING.md correctly.

[LukeMathWalker]

If they are all part of the same crate and you break the public API of the sdk sub-module you are forced to publish a new major (if you are past 1.0) of the whole crate - api included.
If you have two incompatible versions of opentelemetry around (e.g. 1.0 and 2.0) stuff like

opentelemetry-rust/opentelemetry/src/global/trace.rs

Line 237 in 76b6ec9

static ref GLOBAL_TRACER_PROVIDER: RwLock<GlobalTracerProvider> = RwLock::new(GlobalTracerProvider::new(trace::NoopTracerProvider::new()));

stops working and it becomes very cumbersome for users of the crate to get traces propagation working correctly (i.e. everything that uses OpenTelemetry MUST be on the same version of opentelemetry).

I have just gone through this exciting exercise for 20+ applications and 10+ libraries (REST APIs, gRPC APIs, AMQP consumers, REST clients, etc.) - it takes a long time.
That's why I am suggesting, if it reduces the chances of breaking changes in the past, to separate the api module from the sdk one - it would make it much easier for libraries in the Rust ecosystem to start bundling OpenTelemetry instrumentation (relying mostly on api) without having to do regular new releases.

[TommyCpp]

Yeah, you have a good point. I think we should review our status on backward compatibility and how far we are towards tracing GA. If we decided we still need a while to stable the SDK public API after we stabilized tracing API, maybe it's a good idea to separate the SDK from API. @jtescher / @djc / @frigus02 any thoughts?

[jtescher]

A lot of these are now done, could make sense to do another pass to see what changes are needed before GA, if the majority of the changes are in the SDK only then we may make life easier for some folks by separating them.

[TommyCpp]

Docs:

• Add more context for how to choose runtime and why we need runtime SIGINT ignored when using .install_batch(opentelemetry::runtime::Tokio) #731

[hdost]

Didn't realize this existed when I created #977, but I have been keeping it updated there. So going to close this here. Please follow in #977