PREVIEW: Upgrade semantic convention

[ppittle]

Fixes #.

Changes

PREVIEW: 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.10 release of this library.
    /// https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.27.0.
    /// </summary>
    v1_10_Experimental = 1,

    /// <summary>
    /// Pin to the specific state of all Semantic Conventions as of the 1.10.1 release of this library.
    /// https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.29.0.
    /// </summary>
    v1_10_1_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_10_Experimental ;
           })
           .AddInMemoryExporter(exportedItems)
           .Build()!)

[birojnayak]

Please add a test to ensure switch across different semantic conventions version works and default semantic version also work.

Thank you for iterating on feedback offline PJ.

[birojnayak]

Can we take a dependency on version (NUGET) rather than project ?

[ppittle]

The dependency is only for documentation on internal classes. I want to ask the OTel org the best way to to do this, there's pro's and con's either way.

[birojnayak]

may be move to readme

[ppittle]

good point - I think I want to keep it here, but this information should also be in the readme.md files

[ppittle]

Please add a test to ensure switch across different semantic conventions version works and default semantic version also work.

Thank you for iterating on feedback offline PJ.

Added unit test.

[normj]

Not new to your PR but the work to get the container id seems expensive to do for every request when the container id can't change within a process. This might be true for other properties that requiring going to the metadata but are immutable for the environment.

[normj]

Don't you need to check if attributeName is null or empty?

[normj]

Is the pattern forcing us to create a new SemanticConventions every time we add a new service? Seems like if we are being additive that shouldn't require us to define a new semantic conventions version.

[normj]

Do the enums need the Experimental suffix? Seems like the version defines what the convention is and isn't going to change.