Naming conventions confusion

Question

Hey, first I want to say that you people are doing great job with OT 😃 I really appreciate all the effort.

I have few questions though. Reading the documentation and going through examples I’m getting more and more confused on which API I should be using.

I’m not really super familiar with ActivitySource etc so the terminology coming from open telemetry speaks a bit more to me (especially that it is language-agnostic - I can go to someone doing OT in Go, nodejs etc and speak about spans and traces but we would not understand each other if I started speaking about ActivitySource, Activities and so on).

So I wonder…why do we drag the old names into implementation of OT in .net? Wouldn’t it help if we had one unified API with names as in specification?

For instance, in the documentation for Baggage it states:

Baggage API allows users to add context to metric, traces, and logs. Baggage can be propagated out of proc using Propagators. OpenTelemetry SDK ships a BaggagePropagator and enables it by default.

So I started using Baggage.Current.SetBaggage etc…but then I saw somewhere that someone else was using Activity.Current?.Baggage and I started wondering…is it the same baggage or something different, that I shouldn’t use? In fact if I set something in Baggage.Current.SetBaggage it’s not being propagated to Activity.Current?.Baggage…ok then, so I should be using the Baggage.Current?

Then we have the ActivitySource which from my understanding is equal to Tracer from OT library (?) and with instance of that Tracer I can create TelemetrySpan, right? Which in fact is just wrapping Activity?

I don’t know if it’s only me - being so confused about it, but it really seems like by dragging activity source into these libraries it makes everything blurry, especially for newbies when it comes to OT like me 😃

[cartermp]

@cijothomas So in this case the expectation is that .NET adds APIs for otel-compliant baggage and context propagation in the runtime?

Long term, there will be no shim in this repo, instead we expect every API to be covered by .NET runtime itself. (as .NET will keep adding features to limit the gaps with Otel.)

That won’t be portable unless it’s done as an out-of-band package, in which case it’s just needless code churn. But frankly I think it’s also a little concerning that removing the shim is being considered now that everything is 1.0.

Happy to get more feedback on how to make the docs better.

The chief problem to consider here is that modern .NET developers work in systems that use more than .NET. Any .NET services instrumented with Activity-based APIs now has an additional learning curve, where all team members need to remember the “.NET version” of OTel concepts. Not to mention that most OTel backends use terminology like “span” and “trace”, and so .NET developers will have to make that mental leap each time they use a tool.

[mdrgeniebelt]

I’d just like to emphasise how much I agree with both @cartermp and @ericsampson.

I started my journey with OTEL by reading the spec (not all of it course) and it made sense to me, then I moved to this repository and its documentation and I got very confused. Working with other team members that use nodejs I had issues constantly switching between spans, traces, activities, baggage (‘which one are we talking about? Activity baggage or the other one?’).

So like @ericsampson mentioned, the fact that .NET otel package is using activities - is an implementation detail, something that would be ‘interesting’ for people writing their own otel libraries but not really interesting for consumers of these libraries.