Please document effect of trace_flags in SpanContext (must set sampled to process trace)

[joshtriplett]

I was trying to do some distributed tracing using SpanContext. The trace_flags field is just documented as:

Returns details about the trace. Unlike TraceState values, these are present in all traces. Currently, the only option is a boolean sampled flag.

This is slightly inaccurate; there are several constants defined at https://docs.rs/opentelemetry/0.14.0/opentelemetry/trace/index.html#constants . It'd be helpful to have a link to those constants.

But also, this documentation does not explain the net effect of the flags. I spent quite a long time trying to debug why I didn't get any traces out after setting a parent context based on a remote span. Finally, I discovered that a trace with trace_flags set to 0 would always be ignored. Setting trace_flags to opentelemetry::trace::TRACE_FLAG_SAMPLED caused the traces to be emitted again.

Please consider adding some documentation about this, to help people building distributed trace systems.

[TommyCpp]

We probably want to remove those constants as the only valid flag in trace_flag is sampled according to the spec.

The current version of the specification only supports a single flag called sampled.

Other flags(debug and deferred) are there to propagate Jaeger and B3 tracing info, which probably shouldn't propagate via trace_flags. Those flags should also live in Jaeger and B3 propagators rather than the main crate. What do you think @jtescher 😬 ?