Context Propagation: use simpler words and better examples

[SrinivasuluCB]

URL

https://opentelemetry.io/docs/concepts/context-propagation/

Description

Still there is room for using the simple words and better examples

[SrinivasuluCB]

Still there is room for using the simple words and better examples.

[svrnm]

thank you for your feedback @SrinivasuluCB

[jdougan]

In general, anything to do with Contexts is super confusing, even after having read some of the sdk impmentations. maybe concrete examples with nothing implicit.

[svrnm]

In general, anything to do with Contexts is super confusing, even after having read some of the sdk impmentations. maybe concrete examples with nothing implicit.

thanks for the additional feedback, @jdougan

[jdougan]

Thinking about it some more, a skeletal implementation in C89 (or something at a similar semantic level), where you have to implement contexts manually and pass them around explicitly would probably give a better idea of the desired data flow.

/* C89 implementation */

// initialized elsewhere
TracerProvider tpRoot;

void exampleApiCall(ApiResult *apiResult)
{
	// fns have output on the left of the empty comment, input on the
	// right.
	Tracer tr;
	Context trCtx, innerCtx, outerCtx;
	Span spanOuter, spanInner;
	ApiQuery apiQuery;

	getTracer(&tr, &trCtx,/**/ &tp, "example:ApiCall:");

	startSpan(&spanOuter, &outerCtx,/**/ &trCtx, "outer-span-apicall");

	setupApiCall(&apiquery, "queryString", &outerCtx);

	startSpan(&spanInner, &innerCtx,/**/ &outSpanCtx, "inner-span-apicall");

	someApiCall(apiResult, /**/ apiQuery, &innerCtx);

	endSpan(&spanInner);
	cleanupSpan(&spanInner);

	teardownApiCall(&apiQuery, /**/ &outerCtx);

	endSpan(&spanOuter);
	cleanupSpan(&spanOuter);

	cleanupTracer(&tr);
}

[svrnm]

We have some example code in the language specific documentation, e.g.

https://opentelemetry.io/docs/languages/js/propagation/#manual-context-propagation

We could copy from that, or link to it