Standardization of Units needed

[MrAlias]

Looking across language implementation the unit field for the metric instrument definition is implemented differently.

In some cases it is implemented as a definite type, restricting it to well defined values:

• https://github.com/open-telemetry/opentelemetry-go/blob/master/api/unit/unit.go

But, in most cases it is an unconstrained string:

• https://github.com/open-telemetry/opentelemetry-python/blob/master/opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py#L151
• https://github.com/open-telemetry/opentelemetry-java/blob/master/sdk/src/main/java/io/opentelemetry/sdk/metrics/AbstractInstrument.java#L102
• https://github.com/open-telemetry/opentelemetry-js/blob/master/packages/opentelemetry-metrics/src/export/types.ts#L83

I wasn't able to find a part of the specification that specifies a unit. Given the metric SDK is still a work in progress, I'm guessing that it would eventually at least be referenced there.

However, the proto does give some specification on what values a unit can have: https://github.com/open-telemetry/opentelemetry-proto/blob/b54688569186e0b862bf7462a983ccf2c50c0547/opentelemetry/proto/metrics/v1/metrics.proto#L117-L119

This uses the Unified Code For Units of Measure.

Questions

1. Should implementation of units be standardized similar to semantic conventions and be supported as canonical strings? Or, should they be specified as distinct types? Could they be specified so that either implementation would suffice, meaning that languages that support a strong type system could used a dedicated type, and weaker typing systems could have a more flexible implementation?
2. Should we stick with this UCUM standards body like in the proto to specify the unit structure we expect? What about IEEE, or SI? Should we specify our own and have a subset of these standards?
3. Should the prefix be decoupled from the unit? If the unit is to be it's own type, should the prefix just be a dedicated field?
4. How should the extensibility of the unit system be handled? Does it need to be specified?
5. Should things like count, total, or sum be included in the unit specification?

Additional context.

This is all motivated by a need for interoperability between instrumentation and exporters. An exporter needs to know how instrumentation will define its units so it can identify, display, and possibly convert values correctly.

For example, if instrumentation sends time data and the exporter wants all time data in milliseconds. If the unit of time is unspecified and instrumentation sends data as microseconds, micro-sec, us, and μs the will have an insurmountable problem to solve doing this interpretation and conversion.

Additionally, if instrumentation records in one unit (say mmhg) but the exporter exports in another (i.e. kPa) the end user will not have their data interpreted appropriately.

[tigrannajaryan]

@MrAlias in the spirit of limiting the 1.0 GA scope do you think this is necessary for GA or can be postponed?

[MrAlias]

@MrAlias in the spirit of limiting the 1.0 GA scope do you think this is necessary for GA or can be postponed?

Will it be possible to change the units of the OTLP after GA? If so I think it would be reasonable to postpone.

[tigrannajaryan]

The current wording in the proto is pretty specific in what should be in the unit field. It is a string complying with UCUM standard. That's all it says. If you envision a change that contradicts this statement then we cannot change it after we GA. I am not quite sure what changes would be needed though. The current wording sounds good enough to my unsophisticated eye.

Some of the nuanced topics that you touched, such as aggregation of unit seem to fit, e.g. count deletes the unit, sum preserve the unit.

I haven't put much thought into this, that's probably why I cannot foresee any possible breaking changes needed. That's also the reason I asked if you see reasons since I assume you know more about this topic than I do :-)

[MrAlias]

It seems like we should make a decision on what unit standard we want to use prior to GA then. I think we should use the UCUM standard.

The UCUM standard is designed with the goal to facilitate machine-to-machine communication. It uses a 7-bit US-ASCII character set exclusively for encoding, includes all units defined in ISO 1000, ISO 2955-1983, ANSI X3.50-1986, HL7 and ENV 12435, addresses the naming conflicts and ambiguities in those standards to resolve them, and through its use of annotations provides a way to deal with total or count as analogous to a base unit of 1 but without losing syntactic information. While it diverges from the SI base units it is compatible.

If we can agree to this standard for the specification the other details (e.g. how to encode count, total, or sum, how to structure typing, how to design units for usability, the coupling of prefixes to metric units) of implementation can be either left to the language SIG themselves or more universally defined in the specification post GA.

Based on this agreement a PR to the metric API to capture this decision is all that is needed for the GA work.

[tigrannajaryan]

Based on this agreement a PR to the metric API to capture this decision is all that is needed for the GA work.

Works for me.

@MrAlias if you or one of @open-telemetry/specs-metrics-approvers want to submit a PR or would like to have a closer look at it it would be great. Let's try to either make this happen quickly or postpone to after GA.

[jkwatson]

I'm curious how the API/SDK would be expected to enforce this. For example, would this mean that the Java API would gain a dependency on an external unit library that defines all the possibilities? Or, would there be some subset that we would put into the API code as an enum?

[MrAlias]

I'm curious how the API/SDK would be expected to enforce this. For example, would this mean that the Java API would gain a dependency on an external unit library that defines all the possibilities? Or, would there be some subset that we would put into the API code as an enum?

I think this enforcement is the part we would be punting on. I think the addition to the spec would be of the form "the API will accept units that can be represented in a format compliant with the UCUM standard".

@MrAlias if you or one of @open-telemetry/specs-metrics-approvers want to submit a PR or would like to have a closer look at it it would be great. Let's try to either make this happen quickly or postpone to after GA.

Yeah, this sounds like something I can take on. Should be doable in the near term to get something in.

[jmacd]

the API will accept units that can be represented in a format compliant with the UCUM standard

@MrAlias can you clarify what is different between this statement ^^^ and "Follows the format
described by [UCUM]" in the current .proto?

[jmacd]

I would not try to constrain the set of units to a large set or make them types. Having unit be a free string is fine and low-dependency, but I think OpenCensus struck the right balancing in both specifying UCUM strings and providing a few predefined values in the libraries. I think it would be nice to specify modestly larger default set, with common bytes and timing measurements spelled out (question 1).

If we ever need to support more than UCUM in the future, I imagine we could prefix the unit name with the schema (question 2, question 4).

My impression is that UCUM aims to make the translation from a single string into the prefix and base unit format unambiguous. This means we don't need to separate units and prefixes (question 3).

Should things like count, total, or sum be included in the unit specification?

I don't think so. The UCUM spec talks about some non-units named like these (e.g., "total"), but the unit is "1" in these case. It uses the term "pseudo-unit".

I feel there's still more for me to digest in UCUM, but it looks solid to me and I feel we can safely postpone pinning this down until post GA.

Getting back to my first statement, "I would not try to constrain the set of units", I think the SDKs themselves should just pass a string provided by the user, who may have used one of the common predefined unit names or may have passed something more obscure. Hopefully I will not have to pass "ns" in Go, e.g., I'd like that to be predefined. 😀