Make suppress instrumentation APIs less prone to introducing bugs

[alanwest]

Refactoring our SuppressInstrumentation APIs to be less likely to cause problems.

Prior to this PR it was possible to do:

using (var scope = Sdk.SuppressInstrumentation)
{
    if (Sdk.SuppressInstrumentation) ... // false
}

while what was intended was:

using (var scope = Sdk.SuppressInstrumentation.Begin())
{
    if (Sdk.SuppressInstrumentation) ... // true
}

The former would have caused the static SuppressInstrumentationScope instance to be disposed, and furthermore it would not have actually suppressed instrumentation as intended.

Now the usage is:

using (var scope = Sdk.BeginSuppressInstrumentationScope())
{
    if (Sdk.SuppressInstrumentation) ... // true
}

@reyang @CodeBlanch

[alanwest]

There's more to the API now, but I think it is simpler to understand by decoupling the disposable object from the boolean check. Should we apply AggresiveInlining on these APIs?

[reyang]

I guess AggresiveInlining is not going to help here :)

[reyang]

LGTM, that's a good improvement to avoid pitfalls.

[reyang]

Need to update the CHANGELOG.

[codecov]

Codecov Report

Merging #1067 into master will not change coverage.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##           master    #1067   +/-   ##
=======================================
  Coverage   77.40%   77.40%           
=======================================
  Files         220      220           
  Lines        6080     6080           
=======================================
  Hits         4706     4706           
  Misses       1374     1374           

Impacted Files	Coverage Δ
src/OpenTelemetry/Sdk.cs	94.73% <100.00%> (ø)
src/OpenTelemetry/SuppressInstrumentationScope.cs	100.00% <100.00%> (ø)

[CodeBlanch]

I think return should just be IDisposable. It's not like you can do anything with the class. More closely matches log scope that way too.

[alanwest]

Yep! Good call.

[CodeBlanch]

How do you feel about leaving this in?

public static IDisposable Begin(bool value = true)

Because I kind of like this way better:
using (var scope = SuppressInstrumentationScope.Begin())

But I'm OK also having the helper too 😁

There's no more danger of using (SuppressInstrumentationScope) because the static is gone right?

[alanwest]

I feel great about this. I actually decided to remove the helper in favor of this idea. Though, happy to revert and put the helper back if others find it useful. I personally like your idea better.

[CodeBlanch]

LGTM