Rename to `otel` and `otel_sdk` to match application, package, and module names

[chulkilee]

Problems

Currently package name, application name, and module name are mixed between API and SDK.

Component	Package	Application	Module
OpenTelemetry API	opentelemetry_api	opentelemetry_api	opentelemetry, otel_*, OpenTelemetry
OpenTelemetry SDK	opentelemetry	opentelemetry	otel_*

Proposal

(Open for feedback :heart:)

Before getting to late to make significant and breaking changes... let's do this.

• otel_api for OpenTelemetry API package, application, and module name
  • All modules are named as otel_api_*
• otel_sdk for OpenTelemetry SDK package, application, and module name
  • All modules are named as otel_sdk_*

Note

From https://github.com/open-telemetry/opentelemetry-specification -

The official acronym used by the OpenTelemetry project is "OTel"

Go uses otel as package name ref

[tsloughter]

There is a related discussion happening with all SIGs around the packagin, naming and versioning. See https://docs.google.com/document/d/1QHlPsMqwrBm7-IIPef9czuM8KFiLbEDMzGhPrmHcppA/

Interested in your feedback. Until this overall spec is finalized we shouldn't change anything.

[tsloughter]

If you can, please join the Erlang SIG meeting this afternoon https://www.google.com/url?q=https://docs.google.com/document/d/1EbBiRjBc_cBf0T_B5OtNRPhbD4jdBrVYJAy8euCDrUI/edit?usp%3Dsharing&sa=D&source=calendar&usd=2&usg=AOvVaw1r5lcC0cCBmYr2HqTgW3-R

If that is a bad time for you then maybe next week when it is 7am Pacfiic time?

[tsloughter]

Forgot to mention that in my opinion the names should stay as is -- even with the changes related to getting metrics out of the main package. I think we should just have an opentelemetry_api_experimental application that metrics is moved to for the time being.

I prefer the full name opentelemetry for application names. In Go's case the "module" is go.opentelemetry.io/otel, not simply otel.

The module names I'm not as adamant about. I think it works nicely to have a single "namespace" of otel_ but can understand the desire to make the prefix more explicit or renaming opentelemetry.erl to otel_api.erl.

But I think the names are fine and renaming just breaks people's code needlessly.

[chulkilee]

Thanks a lot @tsloughter for the pointer and the invite. Unfortunately I cannot join the Erlang SIG meeting next week 😢

My opinion and questions are followings:

Why change?:

It's better to move on with breaking changes before hitting 1.0, if necessary. Then the question is.. whether it's a needed change or not.

Why package name and module name should match:

From a user point of view, I want package foo defines application foo and module foo. The current opentelemetry and opentelemetry_api does not do that - and it adds confusion and makes unnecessary overhead to understand how things work together. While working on the documentation, I has to make it clear opentelemetry is module or package/application every time.

For opentelemetry or otel

Honestly I don't have strong preference :)

I'm fine to use opentelemetry for API modules (the current status). However, to do that, we have to switch opentelemetry package to API, and move SDK to opentelemetry_sdk. This is doable change, but this is bad for the existing users as upgrading packages would break it. If that's okay (since it hasn't promised the stability yet)... then let's do that instead :)

If not.. that's a part of reason I proposed to use otel (or otel_api) and otel_sdk, and rename modules accordingly. This is also useful as prefix is shorter with the official acronym!

Please note that if we use opentelemetry for API package... then everything is super clear with minimal changes actually.

• Use opentelemetry for API package/application
• Use opentelemetry for global API module, which delegates to other modules. Most users can just use it
• Use otel_* for modules of each component

And SDK uses opentelemetry_sdk package/application name and use otel_sdk_* for component modules. Users shouldn't care anything.

For splitting metrics package

I don't think it's worth to do that. v1.0.0 package has stable tracing but experimental metrics support. Package version doesn't need to be the only way to represent the stability..

Slightly side topic (but related): I'm wondering what's the common practice in Erlang to "version" APIs - versioning at module level (otel_v1_trace), or function level (otel_trace:v1_get_tracer/1), or just do it package level. I don't think it's necessary to do it in Java way to preserve the binary compatibility (using old and new jar file) though.

[tsloughter]

OTEP for versioning and stability. The goal is to get all feedback by tomorrow. https://github.com/open-telemetry/oteps/blob/0ee804e81fdb9e208fd4da2382c0093653b7f101/text/0143-versioning-and-stability.md

[tsloughter]

As for the common practice in Erlang to version APIs, it is at the package level now, even though you'll find cases of both the module level (pg2) and function level (phash2) in OTP :)

[chulkilee]

Seems like https://github.com/open-telemetry/oteps/pull/143 is the place for discussion and https://github.com/tedsuo/rfcs/blob/versioning/text/0143-versioning-and-stability.md is readable version

But that doesn't mean we need to hold our discussion on naming app/package/module in Erlang implementation... because anyway we haven't hit 1.0!

[bryannaegele]

Just to lend some voices here from discussion on this in the SIG meeting - I'm in favor of shortening to otel and have had a number of people voice this to me through other channels.

[tsloughter]

@bryannaegele as in changing the application/project/package name to otel?

[bryannaegele]

Module names.