[API] Support environment variable context propagation

OpenTelemetry.slnx

@@ -88,6 +88,7 @@
     <File Path="docs/diagnostics/experimental-apis/OTEL1000.md" />
     <File Path="docs/diagnostics/experimental-apis/OTEL1001.md" />
     <File Path="docs/diagnostics/experimental-apis/OTEL1004.md" />
+    <File Path="docs/diagnostics/experimental-apis/OTEL1005.md" />
     <File Path="docs/diagnostics/experimental-apis/README.md" />
   </Folder>
   <Folder Name="/docs/logs/">
@@ -131,6 +132,7 @@
   <Folder Name="/examples/">
     <Project Path="examples/AspNetCore/Examples.AspNetCore.csproj" />
     <Project Path="examples/Console/Examples.Console.csproj" />
+    <Project Path="examples/EnvironmentVariables/Examples.EnvironmentVariables.csproj" />
     <Project Path="examples/FSharp/Examples.FSharp.fsproj" />
     <Project Path="examples/GrpcService/Examples.GrpcService.csproj" />
   </Folder>

build/Common.props

@@ -12,7 +12,7 @@
     <NuGetAuditMode>all</NuGetAuditMode>
     <NuGetAuditLevel>low</NuGetAuditLevel>
     <!-- Suppress warnings for repo code using experimental features -->
-    <NoWarn>$(NoWarn);OTEL1000;OTEL1001;OTEL1002;OTEL1004</NoWarn>
+    <NoWarn>$(NoWarn);OTEL1000;OTEL1001;OTEL1002;OTEL1004;OTEL1005</NoWarn>
     <AnalysisLevel>latest-All</AnalysisLevel>
   </PropertyGroup>
 

docs/diagnostics/experimental-apis/OTEL1005.md

@@ -0,0 +1,90 @@
+# OpenTelemetry .NET Diagnostic: OTEL1005
+
+## Overview
+
+This is an Experimental API diagnostic covering the following APIs:
+
+* `EnvironmentVariableCarrier`
+
+Experimental APIs may be changed or removed in the future.
+
+## Details
+
+The OpenTelemetry Specification defines a mechanism for using
+[environment variables as context propagation carriers](https://opentelemetry.io/docs/specs/otel/context/env-carriers/).
+
+When network protocols are not applicable, context and baggage can also be
+propagated through environment variables. Use
+`EnvironmentVariableCarrier.CurrentProcess` to read a normalized snapshot of the
+current process environment, and use `EnvironmentVariableCarrier.Set` to inject
+context into the environment dictionary of a child process. For a runnable
+end-to-end example, see
+[`examples/EnvironmentVariables`](../../../examples/EnvironmentVariables/Program.cs).
+
+> [!IMPORTANT]
+> A process' environment variables may contain sensitive information, like secrets
+> or credentials. Ensure that any environment variables used for context propagation
+> are not exposed to untrusted child processes.
+>
+> See [Environment Variables as Context Propagation Carriers](https://opentelemetry.io/docs/specs/otel/context/env-carriers/#security)
+> for more information about security considerations when propagating context via
+> environment variables.
+
+```csharp
+using System.Diagnostics;
+using OpenTelemetry.Context.Propagation;
+
+var propagator = new CompositeTextMapPropagator(
+[
+    new TraceContextPropagator(),
+    new BaggagePropagator(),
+]);
+
+// Child process startup: extract from the current process' environment snapshot
+var parentContext = propagator.Extract(
+    default,
+    EnvironmentVariableCarrier.CurrentProcess,
+    EnvironmentVariableCarrier.Get);
+
+using var activity = activitySource.StartActivity(
+    "RunChildProcess",
+    ActivityKind.Internal,
+    parentContext.ActivityContext);
+
+var startInfo = new ProcessStartInfo("child.exe")
+{
+    UseShellExecute = false,
+};
+
+foreach (DictionaryEntry environmentVariable in Environment.GetEnvironmentVariables())
+{
+    startInfo.Environment[(string)environmentVariable.Key] = (string?)environmentVariable.Value;
+}
+
+// Parent process: inject into the child process environment copy
+var context = new PropagationContext(activity?.Context ?? default, Baggage.Current);
+propagator.Inject(context, startInfo.Environment, EnvironmentVariableCarrier.Set);
+```
+
+`EnvironmentVariableCarrier` normalizes keys by uppercasing ASCII letters,
+replacing non-ASCII letters, non-digits, and non-underscore characters with
+underscores, and prefixing `_` when a key would otherwise start with a digit.
+Values are treated as opaque strings and are not validated or modified by the
+carrier.
+
+See [Environment Variables as Context Propagation Carriers](https://opentelemetry.io/docs/specs/otel/context/env-carriers/)
+for more information.
+
+We are exposing this APIs experimentally until it is marked as stable.
+
+**TL;DR** We want to gather feedback on the usability of the API and for the
+need(s) in general before exposing a stable API.
+
+## Provide feedback
+
+Please provide feedback on [this
+issue](https://github.com/open-telemetry/opentelemetry-dotnet/issues/7235)
+if you plan on using environment variable context propagation in your application.
+
+Any feedback will help inform decisions about when to expose the API as
+stable and when.

docs/diagnostics/experimental-apis/README.md

@@ -33,6 +33,12 @@ Description: ExemplarReservoir Support
 
 Details: [OTEL1004](./OTEL1004.md)
 
+### OTEL1005
+
+Description: Environment variable context propagation
+
+Details: [OTEL1005](./OTEL1005.md)
+
 ## Inactive
 
 Experimental APIs which have been released stable or removed:

examples/EnvironmentVariables/Examples.EnvironmentVariables.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <NoWarn>$(NoWarn);CA2007</NoWarn>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>$(DefaultTargetFrameworkForExampleApps)</TargetFramework>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="$(RepoRoot)\src\OpenTelemetry.Api\OpenTelemetry.Api.csproj" />
+  </ItemGroup>
+
+</Project>