Upgrade Semantic Convention handling in AWS libraries.

[ppittle]

Fixes #
Design discussion issue #

NOTE: This PR is built on top of #2363, #2363 should be merged first.

Updates 2

This PR will contain -no- change in Semantic Convention by default. Users can opt-in to SemanticConventionVersions.1.28, but default is SemanticConventionVersions.Legacy.

Once merged, this PR will be released as a beta - allowing users a non-breaking way to test opting in-to 1.28.

There will be a fast follow up PR that removes SemanticConventionVersions.Legacy and changes the default to SemanticConventionVersions.V1_28_0. That PR will be merged and released as a Release Candidate.

This follows the release strategy for other contrib packages that have made similar breaking changes around Semantic Convention stabilization.

Updates 1

• The original design of having SemanticConventionVersions track the version of the OpenTelemetry.*.AWS Libraries has been scrapped in favor of tracking Semantic Convnetion repo release versions.
• To simplify communications and development, all OpenTelemetry.*.AWS Libraries will be upgraded to use
  Semantic Convention 1.28.
• To demonstrate how new Semantic Convention versions will be added in the future, this PR also includes Semantic Convention 1.29.
• To promote stability for users, OpenTelemetry..AWS Libraries will default to Semantic Convnetion 1.28 until all conventions used by the libraries are stabalized. This means future versions of the OpenTelemetry..AWS Library will not change AWSSemanticConvention.DefaultSemanticConventionVersion
  • Users can opt-in to any version of Semantic Convention supported the current (or future) versions of OpenTelemetry.*.AWS Libraries.

Changes

Implementation of the design discussed in the Nov 26th OpenTelemetry .NET SIG meeting. This design allows releasing the AWS OTel Contrib libraries as GA while still informing users that underlying Semantic Conventions are experimental.

This is exposed via the SemanticConventionVersion enum:

/// <summary>
/// <para>
/// Collection of the Open Telemetry Semantic Conventions supported by the OpenTelemetry.*.AWS libraries.
/// Can be used to pin the version of Semantic Convention emitted.
/// </para>
/// <para>
/// While these libraries are intended for production use, they rely on several Semantic Conventions that are
/// still considered Experimental, meaning they may undergo additional changes before becoming Stable.  This can
/// impact the aggregation and analysis of telemetry signals in environments with multiple applications or microservices.
/// For example, a microservice using an older version of the Semantic Conventions for Http Attributes may emit
/// <c>"http.method"</c> with a value of GET,while a different microservice, using a new version of Semantic Convention may instead emit the GET as
/// <c>"http.request.method"</c>.
/// </para>
/// <para>
/// Future versions the OpenTelemetry.*.AWS libraries will include updates to the Semantic Convention, which may break compatibility with a previous version.
/// To opt-out of automatic upgrades, you can pin to a specific version:
/// <code>
/// <![CDATA[
///  using (var tracerProvider = Sdk.CreateTracerProviderBuilder()
///     .AddAWSLambdaConfigurations(opt =>
///     {
///         opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
///     })
///     .Build()!)
/// ]]>
/// </code>
/// </para>
/// <para>
/// For additional details, see:
/// https://opentelemetry.io/docs/specs/otel/versioning-and-stability/.
/// </para>
/// </summary>
/// <remarks>
/// Once a Semantic Convention becomes Stable, OpenTelemetry.*.AWS libraries
/// will remain on that version until the next major version bump.
/// </remarks>
public enum SemanticConventionVersion
{
    /// <summary>
    /// Use Experimental Conventions until they become stable and then
    /// pin to stable.
    /// </summary>
    Latest = 0,

    /// <summary>
    /// Pin to the specific state of all Semantic Conventions as of the 1.28.0
    /// release. See:
    /// https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.28.0.
    /// </summary>
    V1_28_0_Experimental = 1,

    /// <summary>
    /// Pin to the specific state of all Semantic Conventions as of the 1.29.0
    /// release. See:
    /// https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.29.0.
    /// </summary>
    V1_29_0_Experimental = 2,
}

Users can choose how to handle this for their applications by either pinning to a specific Semantic Convention version or automatically getting updates the next time they upgrade the AWS Otel nuget packages.

Selection is made by updating the Options object in the builder method.

using (var tracerProvider = Sdk.CreateTracerProviderBuilder()
           .AddAWSLambdaConfigurations(opt =>
           {
               // Added in this PR
               opt.SemanticConventionVersion = SemanticConventionVersion.V1_29_0_Experimental;
           })
           .AddInMemoryExporter(exportedItems)
           .Build()!)

Merge requirement checklist

• CONTRIBUTING guidelines followed (license requirements, nullable enabled, static analysis, etc.)
• Unit tests added/updated
• Appropriate CHANGELOG.md files updated for non-trivial changes
• Changes in public API reviewed (if applicable)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 0.00%. Comparing base (71655ce) to head (8d75bfd).
Report is 664 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #2367       +/-   ##
==========================================
- Coverage   73.91%       0   -73.92%     
==========================================
  Files         267       0      -267     
  Lines        9615       0     -9615     
==========================================
- Hits         7107       0     -7107     
+ Misses       2508       0     -2508     

see 263 files with indirect coverage changes

[alanwest]

Discussed this PR at length with @ppittle today.

The plan is to release one more beta version of these instrumentations that supports the existing conventions they emit. By default the telemetry they emits does not change with this PR, but a user can now opt in to specific versions of the semantic conventions.

A release candidate will ship shortly after the last beta version. The release candidate will default to the new semantic conventions and remove support for the "legacy" conventions.

There are some active reviewers of this PR that have not had a opportunity to approve it yet (@Oberon00 and @Kielek). Since this PR should not be changing any behavior by default, I've decided to approve and merge it so that we can release the next beta version. @ppittle will open up the follow up PR in preparation of the release candidate soon. That should give folks the chance to weigh in with any additional feedback on this plan.