Use UCUM units in Metrics Semantic Conventions

[pichlermarc]

As outlined in #2186 and #1794, the General Metric Semantic Conventions suggest that UCUM units should be used.

This PR addresses this by changing the Units in

• specification/metrics/semantic_conventions/faas-metrics.md
• specification/metrics/semantic_conventions/http-metrics.md
• specification/metrics/semantic_conventions/rpc-metrics.md

to these UCUM-compliant units while still retaining the original semantics.

Resolves #1794, resolves #2186

[yurishkuro]

While ms is easily understood, By for bytes is much worse for readability. Also, why 1 in one case and {count} in others?

[jsuereth]

Looks good, except for the quesiton around 1 vs. {count}. Should these all be 1 according to UCUM?

[pichlermarc]

While ms is easily understood, By for bytes is much worse for readability.

I agree. This is not really optimal in terms of readability. However, the System Metrics Semantic Conventions already use this notation. One possible solution would be to add another column for UCUM units.

Also, why 1 in one case and {count} in others?

For some I used {count} as the document specified the unit as count. However, faas-metrics.md specified some units as default unit which translates to 1 according to UCUM.

Should these all be 1 according to UCUM?

Yes, {count} and 1 both mean "default unit". Anything in curly braces is an annotation. Annotations are used for further explanation in UCUM and they always imply the "default unit".

On the UCUM site, this example is provided:

...one can write “%{vol}”, “kg{total}”, or “{RBC}” (for “red blood cells”) as pseudo-units. However, these annotations do not have any effect on the semantics, which is why these example expressions are equivalent to “%”, “kg”, and “1” respectively.

[yurishkuro]

Personally, I don't like this change. I've never heard of UCUM before. It's home page says 'has already been adopted by some standard organizations such as DICOM, HL7" - great, never heard of those either. So why choose this specific notation?

But more importantly, the wikipedia says "Its primary purpose is machine-to-machine communication rather than communication between humans". What is the value of using it in the spec that is supposed to be human readable?

[pichlermarc]

As far as I am aware, the choice of adopting UCUM in the General Metric Semantic Conventions was made to keep naming consistent and is a carry-over from OpenCensus, where UCUM was used in in the Specification as well. ([1], [2], [3])

I would be open to change this to include a column for the UCUM-compliant unit, which would both avoid ambiguity and follow the recommendation in the General Metric Semantic Conventions. Another option of course would be to drop this recommendation from the General Metric Semantic Conventions altogether.

[tigrannajaryan]

Personally, I don't like this change. I've never heard of UCUM before. It's home page says 'has already been adopted by some standard organizations such as DICOM, HL7" - great, never heard of those either. So why choose this specific notation?

UCUM is already a recommended by this spec and by OTLP spec.

I think this PR adds precision to the semantic conventions and it is a desirable improvement (unless we somehow want to get rid of UCUM altogether) if we can ensure we don't make the readability worse.

Perhaps we add an extra column to show the human readable version of the unit or maybe include the unit in the description, e.g. change:
measures size of RPC request messages (uncompressed)
to:
measures size of RPC request messages in bytes (uncompressed).

[pichlermarc]

Thanks for the feedback! I added a human-readable version to the description as @tigrannajaryan suggested.

[jsuereth]

I'm not sure we should duplicate the unit in the description like this. The descriptions and units are actually carried over the wire when we report metrics.

[pichlermarc]

I'm not sure we should duplicate the unit in the description like this. The descriptions and units are actually carried over the wire when we report metrics.

I see. You're right, having redundancy like that does not make sense when the description is also carried over the wire. I will update the PR to introduce another column.

[tigrannajaryan]

I'm not sure we should duplicate the unit in the description like this. The descriptions and units are actually carried over the wire when we report metrics.

I see. You're right, having redundancy like that does not make sense when the description is also carried over the wire. I will update the PR to introduce another column.

This is a good point. I totally forgot the description is also on the wire. I withdraw my suggestion.

[jmacd]

💯