[k8s] Fix updowncounters to follow the non-pluralization rule

[ChrsMark]

Fixes #2301

Changes

This brings names in alignment with the pluralisation guidelines: https://github.com/open-telemetry/semantic-conventions/blob/v1.37.0/docs/general/naming.md#do-not-pluralize-updowncounter-names

Renamed metrics:

• k8s.node.allocatable.pods -> k8s.node.allocatable.pod.count
• k8s.daemonset.current_scheduled_nodes -> k8s.daemonset.current_scheduled_node.count
• k8s.daemonset.desired_scheduled_nodes -> k8s.daemonset.desired_scheduled_node.count
• k8s.daemonset.misscheduled_nodes -> k8s.daemonset.misscheduled_node.count
• k8s.daemonset.ready_nodes -> k8s.daemonset.ready_node.count
• k8s.job.active_pods -> k8s.job.active_pod.count
• k8s.job.failed_pods -> k8s.job.failed_pod.count
• k8s.job.successful_pods -> k8s.job.successful_pod.count
• k8s.job.desired_successful_pods -> k8s.job.desired_successful_pod.count
• k8s.job.max_parallel_pods -> k8s.job.max_parallel_pod.count
• k8s.cronjob.active_jobs -> k8s.cronjob.active_job.count
• k8s.deployment.desired_pods -> k8s.deployment.desired_pod.count
• k8s.deployment.available_pods -> k8s.deployment.available_pod.count
• k8s.replicaset.desired_pods -> k8s.replicaset.desired_pod.count
• k8s.replicaset.available_pods -> k8s.replicaset.available_pod.count
• k8s.replicationcontroller.desired_pods -> k8s.replicationcontroller.desired_pod.count
• k8s.replicationcontroller.available_pods -> k8s.replicationcontroller.available_pod.count
• k8s.statefulset.desired_pods -> k8s.statefulset.desired_pod.count
• k8s.statefulset.ready_pods -> k8s.statefulset.ready_pod.count
• k8s.statefulset.current_pods -> k8s.statefulset.current_pod.count
• k8s.statefulset.updated_pods -> k8s.statefulset.updated_pod.count
• k8s.hpa.desired_pods -> k8s.hpa.desired_pod.count
• k8s.hpa.current_pods -> k8s.hpa.current_pod.count
• k8s.hpa.max_pods -> k8s.hpa.max_pod.count
• k8s.hpa.min_pods -> k8s.hpa.min_pod.count

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• Links to the prototypes or existing instrumentations (when adding or changing conventions)

[AlexanderWert]

Should we maybe add k8s.replicationcontroller.desired_pods as an additional deprecated metric?
(as this is the second time this metric is being renamed)

Otherwise k8s.replicationcontroller.desired_pods wouldn't be mentioned anywhere as a deprecated metric with only the original (from the first rename) name being documented here (i.e. k8s.replication_controller.desired_pods).

[ChrsMark]

I had both metrics originally, but the validation failed cause it was pointing to a non-existing metric (the first rename). Not sure if this is expected or an unhandled corner-case of our tooling 🤔

[jsuereth]

I believe the tooling expects all the previous metric names to remain around.

Given these are not "stable" I think there's less enforcement around keeping things around, although it is risky depending on whether the intermediate name was used.

If you have a caveat asking folks NOT to migrate to new metrics past version "X" then you can drop the intermediary if it's between "X" and now, as (theoretically) anyone taking a dependency there new this might be changing.

[AlexanderWert]

same as the comment above about adding additional deprecated metric

[dmitryax]

Even after #2306 is resolved, it still unclear why is this change required. Looking at these guidelines it seems like existing naming still valid.

1. They cannot be taken as namespaces
2. "value being recorded represents discrete instances of a countable quantity"

### Naming rules for counters and UpDownCounters

#### Pluralization

Metric namespaces SHOULD NOT be pluralized.

Metric names SHOULD NOT be pluralized, unless the value being recorded
represents discrete instances of a
[countable quantity](https://wikipedia.org/wiki/Count_noun).
Generally, the name SHOULD be pluralized only if the unit of the metric in
question is a non-unit (like `{fault}` or `{operation}`).

Examples:

- `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time`
  should not be pluralized, even if many data points are recorded.
- `system.paging.faults`, `system.disk.operations`, and `system.network.packets`
  should be pluralized, even if only a single data point is recorded.

#### Do not pluralize UpDownCounter names

UpDownCounter names SHOULD NOT be pluralized.

For example if we have a namespace `system.process` which contains all metrics related
to the processes then to represent the count of the processes we can have a metric named
`system.process.count` instead of `system.processes`. Similarly, `cicd.pipeline.run.active` is preferred
over the `cicd.pipeline.active_runs`.

What am I missing?

[dmitryax]

The PR introduces a significant number of breaking changes, and I’m not sure the current justification is sufficient.

[ChrsMark]

@dmitryax the guidance moves us towards consistency based on the discussions happened in the respective guidance PR and specifically #2317 (comment). The part that applies here is that UpDownCounters should not be pluralised, with the following example:

Similarly, `cicd.pipeline.run.active` is preferred
over the `cicd.pipeline.active_runs`.

Also note that those metrics are not in use yet in the Collector in the current format hence it's not really an impactful breaking change. Those metrics are already different to the Collector's ones as we can see in https://github.com/open-telemetry/semantic-conventions/pull/2822/files#diff-ba5fa96c108eca125c2c88f68cdfb0a3d0c95792912f5518eedd55666bc1c033.

I don't have a strong preference for this change either but it seems that we need it so as to be consistent with the rest of the project.

@lmolkova please chime in if we miss anything here.

[dmitryax]

Ok, but the guidelines in the spec are still not strong enough for this change. All of the existing metrics seem to follow this section:

Metric names SHOULD NOT be pluralized, unless the value being recorded
represents discrete instances of a
countable quantity.
Generally, the name SHOULD be pluralized only if the unit of the metric in
question is a non-unit (like {fault} or {operation}).

Do we need to remove that part from the spec?

In general, looking at the changed metrics names as a user, the existing ones seem to be more intuitive than to the new ones.

[dmitryax]

Is it expected that we always just add .count suffix? Looking at the discussions behind the new guidelines, should we consider something like this?

Suggested change

	- k8s.node.allocatable.pods -> k8s.node.allocatable.pod.count
	- k8s.daemonset.current_scheduled_nodes -> k8s.daemonset.current_scheduled_node.count
	- k8s.daemonset.desired_scheduled_nodes -> k8s.daemonset.desired_scheduled_node.count
	- k8s.daemonset.misscheduled_nodes -> k8s.daemonset.misscheduled_node.count
	- k8s.daemonset.ready_nodes -> k8s.daemonset.ready_node.count
	- k8s.daemonset.current_scheduled_nodes -> k8s.daemonset.node.current_scheduled
	- k8s.daemonset.desired_scheduled_nodes -> k8s.daemonset.node.desired_scheduled
	- k8s.daemonset.misscheduled_nodes -> k8s.daemonset.node.misscheduled
	- k8s.daemonset.ready_nodes -> k8s.daemonset.node.ready

Similar for other metrics. Just asking for sake of discussion.

[ChrsMark]

Yeap, adding .count is one option but what you suggest is also an option. I went for .count which looked less controversial to me (i.e. k8s.daemonset.node.ready might not be so clear?) but I would be happy to change it to what you suggest if it's preferable.

@lmolkova could you let us know what your suggestion would be here?
@open-telemetry/semconv-k8s-approvers please let us know what you think.

[jsuereth]

I believe your PR is ready to be merged. @lmolkova is OOO right now.

Personally, I like the consistency of .count you have here, but I think both options are viable

[jsuereth]

I marked the PR as ready to be merged. If the k8s SIG feels confident in this direction, please close this comment and this will be merged, otherwise please leave this open.

[jsuereth]

I believe the tooling expects all the previous metric names to remain around.

Given these are not "stable" I think there's less enforcement around keeping things around, although it is risky depending on whether the intermediate name was used.

If you have a caveat asking folks NOT to migrate to new metrics past version "X" then you can drop the intermediary if it's between "X" and now, as (theoretically) anyone taking a dependency there new this might be changing.