Update documentation and add documentation to README files

src/OpenTelemetry.Instrumentation.AWS/README.md

@@ -33,3 +33,45 @@ public void ConfigureServices(IServiceCollection services)
         .AddOtlpExporter());
 }
 ```
+
+## Semantic Conventions
+
+_For an overview on Semantic Conventions, see
+https://opentelemetry.io/docs/concepts/semantic-conventions/_.
+
+While this library is intended for production use, it relies 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 `"http.method"` with a value of GET, while a
+different microservice, using a new version of Semantic Convention may instead
+emit the GET as `"http.request.method"`.
+
+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:
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.AWS;
+using OpenTelemetry.Contrib.Extensions.AWSXRay.Trace;
+using OpenTelemetry.Trace;
+
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddControllers();
+    services.AddOpenTelemetryTracing((builder) => builder
+        .AddAWSInstrumentation(opt => {
+            // pin to a specific Semantic Convention version
+            opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
+        });
+}
+```
+
+__NOTE:__ Once a Semantic Convention becomes Stable, OpenTelemetry.*.AWS
+libraries will remain on that version until the
+next major version bump.

src/OpenTelemetry.Instrumentation.AWSLambda/README.md

@@ -140,6 +140,41 @@ public class Function
 }
 ```
 
+## Semantic Conventions
+
+_For an overview on Semantic Conventions, see
+https://opentelemetry.io/docs/concepts/semantic-conventions/_.
+
+While this library is intended for production use, it relies 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 `"http.method"` with a value of GET, while a
+different microservice, using a new version of Semantic Convention may instead
+emit the GET as `"http.request.method"`.
+
+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:
+
+```csharp
+ using (var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .AddAWSLambdaConfigurations(opt =>
+    {
+        // pin to a specific Semantic Convention version
+        opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
+    })
+    .Build()!);
+```
+
+__NOTE:__ Once a Semantic Convention becomes Stable, OpenTelemetry.*.AWS
+libraries will remain on that version until the
+next major version bump.
+
 ## Reference
 
 * [OpenTelemetry Project](https://opentelemetry.io/)

src/OpenTelemetry.Resources.AWS/README.md

@@ -64,6 +64,46 @@ log group ids, log stream names, log stream ids.
 - **AWSEKSDetector**: cloud provider, cloud platform, cluster name,
 container id.
 
+## Semantic Conventions
+
+_For an overview on Semantic Conventions, see
+https://opentelemetry.io/docs/concepts/semantic-conventions/_.
+
+While this library is intended for production use, it relies 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 `"http.method"` with a value of GET, while a
+different microservice, using a new version of Semantic Convention may instead
+emit the GET as `"http.request.method"`.
+
+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:
+
+```csharp
+using OpenTelemetry;
+using OpenTelemetry.Resources;
+
+using var tracerProvider = Sdk.CreateTracerProviderBuilder()
+    .ConfigureResource(resource => resource.AddAWSEC2Detector(
+        opt => {
+            // pin to a specific Semantic Convention version
+            opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
+        }
+    ))
+    // other configurations
+    .Build();
+```
+
+__NOTE:__ Once a Semantic Convention becomes Stable, OpenTelemetry.*.AWS
+libraries will remain on that version until the
+next major version bump.
+
 ## References
 
 - [OpenTelemetry Project](https://opentelemetry.io/)

src/Shared/AWS/SemanticConventionVersion.cs

@@ -13,7 +13,7 @@ namespace OpenTelemetry.AWS;
 /// 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.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>
@@ -26,7 +26,7 @@ namespace OpenTelemetry.AWS;
 ///     {
 ///         opt.SemanticConventionVersion = SemanticConventionVersion.v1_10_EXPERIMENTAL;
 ///     })
-///     .Build()!)
+///     .Build()!);
 /// ]]>
 /// </code>
 /// </para>