Crate naming to indicate the purpose

[cijothomas]

We have recently agreed on the names for the "API" crate and "SDK" create as "opentelemetry", and "opentelemetry-sdk" respectively. The name "opentelemetry" is not very self-explanatory, but its following the tradition in Rust projects (like log, tracing crates).

This issue is opened to discuss the names of other crates. The crates' names are not very self-explanatory most of the cases.

ex: opentelemetry-http - it could mean an instrumentation library, but its not one as of today. Instead it has few Propagation helpers, and has nothing to do with Instrumentation Library as defined by OTel spec!

Another example: opentelemetry-jaeger - it is currently an exporter + jaeger propagator. Given we would be deprecating jaeger exporter, the crate would just be a propagator in the future, but the name does not clearly indicate so.

Proposing to follow a convention where the crate names are self-explanatory, by having the component type (instrumentation/propagator/sampler/exporter/ etc.) in the name.
Examples: opentelemetry-exporter-otlp, opentelemetry-exporter-jaeger, opentelemetry-propagator-jaeger.

^ is Just couple of example names we could use. Want to get some feedback on the general direction before proceeding further with specific names (name changes).

[cijothomas]

Adding it to Stable milestone now, as renamings (if we chose to do), must be done before 1st stable release.

[djc]

By "opentelemetrysdk", presumably you mean "opentelemetry_sdk"?

Personally I'm not completely sure the proposed renamings make sense. As someone who is not very familiar with the core spec, the component names aren't all that meaningful to me, and splitting up things I would need to work with Jaeger (for example) into multiple crates just seems like an extra barrier to throw up. Making names longer IMO isn't always a good thing, as it can make the name harder to remember and/or understand.

[cijothomas]

By "opentelemetrysdk", presumably you mean "opentelemetry_sdk"?
Yes, edited.

into multiple crates just seems like an extra barrier to throw up.

This is solvable by making helper/wrapper crates (more like Family Packs), which will bring all the required crates for a scenarios. For example: opentelemetry-aws could bring in all the requires crates (sampler, detectors, exporters) to make things work. This is usually solved by individual vendors.

Making names longer IMO isn't always a good thing, as it can make the name harder to remember and/or understand.

The opposite is also true - if the name is not self-explanatory, that is equally hard! Taking opentelemetry-jaeger as an example, a user has no knowledge from its name that it is just a propagator and won't help with exporting to jaeger. (this is after we remove exporter code from the opentelemetry-jaeger crate)

Every other language uses crate/package/nuget names that are more self-explanatory.
https://www.npmjs.com/search?q=opentelemetry&page=1&perPage=20
https://pypi.org/user/opentelemetry/
https://www.nuget.org/profiles/OpenTelemetry

[shaun-cox]

As long as the proposed taxonomy is simple and makes sense generally at first glance and reinforces important distinctions in the OpenTelemetry ecosystem, I could get behind it. If it's somewhat arbitrary or hinders the goal of separate crates which is fundamentally about dependency management, then I'm less supportive. (I don't yet have a feel for which way the above proposal falls.)

Seems like you're suggesting a crate always have one of the following in its name?

• -instrumentation
• -collector
• -sampler
• -propagator
• -exporter

and is a reference to the Components concept in the specification?

Is that the exhaustive list?

If such a taxonomy were encouraged, I would worry that yet even more crates would have to be introduced in order to break otherwise circular dependencies that might arise within some vendor-specific implementation of the above concepts.

I would also wonder that if an application commonly needs one of the SDK-centric crates above, if they'd typically need them all anyway. (I would not be a fan of introducing yet another layer of helper/wrapper/family pack crates on top of these.)

My observation is that I wonder if the concepts above are better represented as features of vendor-specific crates, if they are opt-in by a consumer anyhow?

I agree that the current opentelemetry-http might be better called opentelemetry-propagation-http, if its purpose is to implement the W3C spec for context propagation over the HTTP protocol, independent of which vendor uses it. But I also think all of the vendor-specific crates we have now, opentelemetry-jaeger, opentelemetry-prometheus, opentelemetry-datadog make perfect sense too at first glance.

[cijothomas]

Seems like you're suggesting a crate always have one of the following in its name?

Not always. Only when a crate contains one functionality. (an exporter only crate should have the name "exporter" as part of crate name.)

if opentelemetry-jaeger is the all-in-all crate for everything jaeger related, then that name is absolutely fine! The current one happens to have an exporter + propagator in it, but the exporter is about to be deprecated, at which point the name opentelemetry-jaeger is likely to confuse people.

Another example: If Azure or AWS wants to ship a custom sampler. the crate could be named "opentelemetry-sampler-azure", instead of just "opentelemetry-azure". "opentelemetry-azure" would be a good name if that crates does azure specific sampler, azure exporters, azure resource detectors.

[cijothomas]

Moving out of API milestrone as the name of API crate is settled.