Consistent naming?

[reyang]

trafficstars

What needs to be changed?

The current docs seem to use inconsistent names for different language clients.

For example:

Making it worse, the website is also different from the official project:

What is the name + path of the page that needs changed?

Almost all the docs under https://github.com/open-telemetry/opentelemetry.io/tree/main/content/en/docs/instrumentation

[alolita]

Good callout @reyang +1 on maintaining consistent naming.

[svrnm]

Thanks for bringing this up, @reyang! I am not sure if this is a sole issue for the website or for all the SIGs as well (as you called out there are differences in the repo names as well). I raised a similar topic a while back rg. the auto instrumentation where we have a similar situation: https://github.com/open-telemetry/opentelemetry.io/issues/1689

We fixed that for a few of the language index pages via this PR: https://github.com/open-telemetry/opentelemetry.io/pull/1732

Not sure if this is a decision we can solely make from the website?

[reyang]

Not sure if this is a decision we can solely make from the website?

Aha, I don't know! That's why I raised this issue to test the water 🤣🤣🤣

[cartermp]

We can certainly standardize on naming on the website, but yeah, this might be a "each SIG decides what the name is" sorta deal. Which would then lead to inconsistent naming for sure. Ah, bikesheds.

[svrnm]

Please see my lengthy comment here: https://github.com/open-telemetry/opentelemetry.io/issues/1689#issuecomment-1257698064

[svrnm]

For the initial question, I think it should be "OpenTelemetry for <Language>"? That's at least what most language pages have (especially due to #1732, where we started to use the same text for most language pages).

[cartermp]

Agreed.

[reyang]

For the initial question, I think it should be "OpenTelemetry for <Language>"? That's at least what most language pages have (especially due to #1732, where we started to use the same text for most language pages).

"For" could be confusing for clients that are targeting more than the programming language. For example:

• "OpenTelemetry for Java" sounds like it is for Java, although it can be used by Scala or any other languages targeting JVM.
• "OpenTelemetry for JavaScript" sounds like it is for JavaScript, however it can be used by TypeScript/CoffeeScript/etc.

[svrnm]

That's a point against "for" indeed. Not that I would rule it out because of that but maybe we can do better, so what are the alternatives we have?

1. OpenTelemetry for C++, OpenTelemetry for Rust
2. OpenTelemetry Java, OpenTelemetry JavaScript
3. OpenTelemetry in .NET, OpenTelemetry in Python
4. OpenTelemetry Go SDK, OpenTelemetry Ruby SDK (and ... API, etc.)

[reyang]

Maybe we can collect feedback here - vote with emoji:

1. ❤️ OpenTelemetry C++, OpenTelemetry Rust, OpenTelemetry Java, OpenTelemetry JavaScript, OpenTelemetry .NET, OpenTelemetry Python, OpenTelemetry Go, OpenTelemetry Ruby
2. 🎉 OpenTelemetry in C++, OpenTelemetry in Rust, OpenTelemetry in Java, OpenTelemetry in JavaScript, OpenTelemetry in .NET, OpenTelemetry in Python, OpenTelemetry in Go, OpenTelemetry in Ruby
3. 🚀 OpenTelemetry for C++, OpenTelemetry for Rust, OpenTelemetry for Java, OpenTelemetry for JavaScript, OpenTelemetry for .NET, OpenTelemetry for Python, OpenTelemetry for Go, OpenTelemetry for Ruby

[svrnm]

So, we have a strong preference for "OpenTelemetry <Language>"?

We can change that throughout the docs, but for consistency we should also have the same for the individual repos, and I think that's something that needs to be discussed via open-telemetry/community?

[reyang]

We can change that throughout the docs, but for consistency we should also have the same for the individual repos, and I think that's something that needs to be discussed via open-telemetry/community?

I've reached out to several groups on Slack gathering feedback:

1. OpenTelemetry Maintainers https://cloud-native.slack.com/archives/C01NJ7V1KRC/p1664914229223519
2. OpenTelemetry Community https://cloud-native.slack.com/archives/CJFCJHG4Q/p1664914268959639
3. OpenTelemetry Demo https://cloud-native.slack.com/archives/C03B4CWV4DA/p1664914257596769

[pellared]

@reyang Could we also try consistently naming the "auto-instrumentation" repositories or is it too much for this issue?

Current state:

1. OpenTelemetry Instrumentation for Java
2. OpenTelemetry .NET Automatic Instrumentation
3. OpenTelemetry auto-instrumentation extension

Proposals:

1. ❤️ OpenTelemetry ABC Auto-Instrumentation OR OpenTelemetry Auto-Instrumentation for ABC
2. 🎉 OpenTelemetry ABC Automatic Instrumentation OR OpenTelemetry Automatic Instrumentation for ABC
3. 🚀 OpenTelemetry ABC Instrumentation OR OpenTelemetry Instrumentation for ABC

[mateuszrzeszutek]

Some of the modules released as part of https://github.com/open-telemetry/opentelemetry-java-instrumentation are not really automatic instrumentation: these library instrumentations have to be added as a dependency, and then configured and installed into the instrumented framework by the user. If possible, I'd refrain from renaming the repo to "auto-instrumentation"

[svrnm]

@pellared , @mateuszrzeszutek I would prefer to have this in a separate issue, because this is a much more complicated case (see also the discussion at #1689). A layer of complexity that you called out, @mateuszrzeszutek, is that the content of the opentelemetry--(instrumentation|contrib) repositories is not consistent, so this is not a discussion that we should have here at the opentelemetry.io repo.

[reyang]

Getting back here, https://github.com/open-telemetry/opentelemetry-specification/pull/2867 is merged. Thanks everyone who contributed to the discussion and shared your opinions/votes.

[reyang]

@svrnm FYI I've done some grunt work to align the existing projects:

• https://github.com/open-telemetry/opentelemetry-php/pull/847
• https://github.com/open-telemetry/opentelemetry-java/pull/4871

I'll keep this issue open since there are still several places in the docs where we need to address.

[cartermp]

@reyang thanks for filing. I believe this can now be closed since all language index pages use the same pattern for the name.