[API] Environment Variables as Context Propagation Carriers

[perhapsmaple]

Fixes #3817

Written with inspiration from: Go PR

Changes

Need help from maintainers on below:

• I have followed the Go implementation of having a single class. The Python implementation on the other hand uses two separate classes: Python PR
• Is the raw pointer correct for this use case? From my view, the carrier shouldn't own the map. Should we use nostd::shared_ptr for safety?
• I believe Windows has a character limit? Do we need to handle this?
• Keys() only returns known OTel variables (traceparent, tracestate, baggage), not all environment variables. The Go Implementation returns all environment variables.
• Carrier is NOT thread-safe. Do we need to handle this?

For significant contributions please make sure you have completed the following items:

• CHANGELOG.md updated for non-trivial changes
• Unit tests have been added
• Changes in public API reviewed

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.02%. Comparing base (3143f93) to head (dcce272).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3834      +/-   ##
==========================================
+ Coverage   89.98%   90.02%   +0.05%     
==========================================
  Files         225      226       +1     
  Lines        7170     7193      +23     
==========================================
+ Hits         6451     6475      +24     
+ Misses        719      718       -1     

Files with missing lines	Coverage Δ
...elemetry/context/propagation/environment_carrier.h	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[marcalff]

@perhapsmaple

Thanks for the feature.

Need help from maintainers on below:

* I have followed the Go implementation of having a single class. The Python implementation on the other hand uses two separate classes: [Python PR](https://github.com/open-telemetry/opentelemetry-python/pull/4609)

The spec proposes either a single interface (Propagator), or two separate interfaces (Injector, Extractor) for propagation.

Given that opentelemetry-cpp uses a single interface with a TextMapCarrier, I think keeping a single class makes sense.

* Is the raw pointer correct for this use case? From my view, the carrier shouldn't own the map. Should we use nostd::shared_ptr for safety?

A shared pointer is better, to avoid misuse.

* I believe Windows has a character limit? Do we need to handle this?

Every operating system will have a character limit, not only windows.

Given that the code does not do a setenv() itself, but produces a map of environment variables to set, I propose to leave this to the code making the actual call to fork/exec/etc, so no limits to check preemptively.

* Keys() only returns known OTel variables (traceparent, tracestate, baggage), not all environment variables. The Go Implementation returns all environment variables.

The Carrier is supposed to be ignorant of which propagator is used, only propagators will know the keys.

Conceptually, the environment variable carrier is supposed to work with any propagator, including B3, so it should not hard code any known keys.

Notice how none of the carriers, including the HttpTextMapCarrier, implement the Keys() method, the only supported pattern is set/get with a known key name.

I propose to not implement Keys(), used to inspect the whole container, either.

* Carrier is NOT thread-safe. Do we need to handle this?

For HTTP, when two threads make an http call and need to inject keys to talk to two different services, each thread will use its own carrier to inject into its own http message.

For environment variables, the pattern should be the same, the EnvironmentCarrier object will be per thread, not shared, so there should be no thread safety issue.

---

This PR is looking good already.

A great addition will be an example with a parent process that forks a child, so people can see in practice how to implement the whole thing.

[perhapsmaple]

Thanks for the review. I have added a basic example that should work in unix environments. Do we need an example for windows as well?

[marcalff]

Also map:

• my-key to MY_KEY
• my.complex.key to MY_COMPLEX_KEY

so any character that does not fit an environment variable name should be replaced by underscore.

[marcalff]

LGTM, thanks for the feature.

See a minor comment.

[marcalff]

Thanks for the review. I have added a basic example that should work in unix environments. Do we need an example for windows as well?

Thanks for the example added. It looks good as is, it shows how to use the environment carrier.

[marcalff]

@lalitb

Could you review as well, given that this change touches the API ? Thanks.

[ThomsonTan]

nit: std::toupper(c) needs header file #include <cctype>.

[ThomsonTan]

Get is marked as const, but it does mutate the internal state cache_. Perhaps this should be documented in the API doc?