cortex Uniform tenant/org/user naming

Cortex interchangeably uses the terms "tenant", "org", "user" and their derived forms "tenant ID", "org ID", "user ID" . This generates quite a lot of confusion to newcomers and I would like to propose to standardise it, converging to a single naming.

We could adopt a soft approach to begin with:

Uniform the documentation
Introduce a policy to always use the decided term for future changes
[lower priority] Eventually consider to rename usage in existing logs, metrics, code

Thoughts?

Aug 06 '20 12:08 pracucci

Agreed, I saw someone confused over this yesterday.

"user" is perhaps justifiable but confusing; "org" is better but confusing if one organisation runs multiple systems, e.g. dev and prod.

The API has "X-Scope-OrgID", which might also need changing.

Aug 06 '20 12:08 bboreham

I think tenant would be the best option, because:

It's a multi-tenant system :)
An organization entity could have multiple tenants
An user is usually associated with authentication (out of the scope of Cortex) and a tenant could have multiple users

However, in logs and metrics especially we do a large use of user: renaming them would be a pain for the final user, and start using "tenant" there along with the existing "user" could introduce even more confusion. I'm puzzled.

Aug 06 '20 12:08 pracucci

As a new user to Cortex that's been going though the often steep learning curve and trying to understand the terminology could the confusion not be solved by firstly having some clear documentation about what each means and how each part of the system uses them and then look at writing some of them out of future releases?

Aug 06 '20 13:08 simon71

As a new user to Cortex that's been going though the often steep learning curve and trying to understand the terminology could the confusion not be solved by firstly having some clear documentation about what each means and how each part of the system uses them and then look at writing some of them out of future releases?

The main problem is that within Cortex these 3 terms are just synonymous and I believe uniforming it (just pick 1) could help simplifying it.

Aug 06 '20 13:08 pracucci

You said

However, in logs and metrics especially we do a large use of user: renaming them would be a pain for the final user, and start using "tenant" there along with the existing "user" could introduce even more confusion.

In the mean time would documenting the current state of play and how thing will change in the future not help?

Aug 06 '20 13:08 simon71

Some places you will see "user" vs "org" was copy-paste four years ago from code where those two things mean something; however in Cortex today they are never used to mean anything different from "tenant".

Aug 06 '20 14:08 bboreham

You said

However, in logs and metrics especially we do a large use of user: renaming them would be a pain for the final user, and start using "tenant" there along with the existing "user" could introduce even more confusion.

In the mean time would documenting the current state of play and how thing will change in the future not help?

Definitely. Uniforming the documentation and mentioning that logs and metrics may use these terms interchangeably is good starting point 👍

Aug 06 '20 14:08 pracucci

A good feedback received from @weeco on Slack:

Adding a glossary could be an idea as well. It may help new users to describe the meaning of churn, metric series etc. even though they are rather prometheus specific

Aug 07 '20 06:08 pracucci

+1 for tenant

Aug 07 '20 20:08 jtlisi

However, in logs and metrics especially we do a large use of user: renaming them would be a pain for the final user, and start using "tenant" there along with the existing "user" could introduce even more confusion. I'm puzzled.

I think we should roadmap a hard switch for our next major release. In the meantime we can standardize on tenant.

We don't currently have a major release planned. However, I think it would make sense to start compiling a list of breaking changes that can be reserved for a major release.

Aug 07 '20 20:08 jtlisi