Provide ability to carry State(Object) with Telemetry

[cijothomas]

Proposing to provide an ability to store a raw object/state in any ITelemetry item inside the TelemetryContext, which can be used by TelemetryInitializers (for enrichment) or by TelemetryProcessors (filtering)/Channel.

The state/object is not meant to be serialized and sent to backend.
If multiple sinks are configured, the state will be shared between them. Sinks are expected to treat this state as read-only. If any of the sinks wants to modify the state clone the object, and modify so as to not affect the shared state.

Use Cases:
Similar discussion here: microsoft/ApplicationInsights-dotnet-server#900 DependencyTelemetry was modified to provide the ability to carry additional state.(via SetOperationDetail(string key, object detail) and TryGetOperationDetail(string key, out object detail))
We can modify the above to make use of the new state sharing mechanism being proposed here.

ProposedAPI:

TelemetryContext.StoreRawObject(string key, Object rawObject, bool keepForInitializationOnly = true)
bool TelemetryContext.TryGetRawObject(string key, out Object rawObject)

Details:
StoreRawObject will let users store any state (i.e any object) into the TelemetryContext. The 3rd boolean parameter indicates whether this state is to be used only till TelemetryInitializers or not.
True - the entry will be cleared after all TelemetryInitializers are run. i.e TelemetryProcessors/Channels won't have access to this object.
Use this, if storing memory intensive objects like HTTPResponse, HttpContext etc. for use by TelemetryInitializers. This has negligible memory overhead, as its cleared immediately after initializers.

False - SDK will not clean it up explicitly. Once telemetry is send from the channel, objects are GC'ed as usual.
Use this if storing custom states which are needed in TelemetryProcessors. Since the object is not explicitly cleaned up by SDK, storing memory intensive objects like HttpResponse etc. can cause memory overheads.

TryGetRawObject - to retrieve the state for the given key.

[cijothomas]

#939 Closed with.

[cijothomas]

Example usage:

class MyProcessor : ITelemetryProcessor
{
    private ITelemetryProcessor next;

    public MyProcessor(ITelemetryProcessor next)
    {
        this.next = next;
    }

    public void Process(ITelemetry item)
    {
       // The following will not find the value set in MyInitializer1 into "key"
        var tempKeyExists = item.Context.TryGetRawObject("key", out object myvalue);

       // The following will successfully retrieve the value set in MyInitializer2 into "keyperm"
        var permKeyExists = item.Context.TryGetRawObject("keyperm", out object myvalueperm);

        this.next.Process(item);
    }
}

class MyInitializer1 : ITelemetryInitializer
{
    public void Initialize(ITelemetry telemetry)
    {
        // Stores something for access by TelemetryInitializers only
        telemetry.Context.StoreRawObject("key", "cijothomas");
    }
}

class MyInitializer2 : ITelemetryInitializer
{
    public void Initialize(ITelemetry telemetry)
    {
        // Stores something for access by TelemetryInitializers, TelemetryProcessors
        telemetry.Context.StoreRawObject("keyperm", "cijothomas", false);
        
        // If MyInitializer2 is added after MyInitializer1, then the following will successfully retrieve the value set in MyInitializer1
        var result = telemetry.Context.TryGetRawObject("key", out object myval);            
    }
}