Skip to content

Commit dc9268b

Browse files
chimchim89xrmx
andauthored
docs: document why map_to_index assumes value is not 0, inf, or NaN (open-telemetry#4930)
Co-authored-by: Riccardo Magliocchetti <riccardo.magliocchetti@gmail.com>
1 parent a9a1718 commit dc9268b

File tree

1 file changed

+18
-1
lines changed
  • opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/exponential_histogram/mapping

1 file changed

+18
-1
lines changed

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/exponential_histogram/mapping/exponent_mapping.py

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,24 @@ def map_to_index(self, value: float) -> int:
122122

123123
# In summary, correction will be -1 if value is a power of 2, 0 if not.
124124

125-
# FIXME Document why we can assume value will not be 0, inf, or NaN.
125+
# map_to_index requires value to be a finite, positive real number.
126+
# 0, inf, and NaN violate this precondition.
127+
128+
# Zero is represented in IEEE 754 with all exponent bits set to 0,
129+
# giving get_ieee_754_exponent a result of -1023. Since -1023 is less
130+
# than MIN_NORMAL_EXPONENT (-1022), zero is caught by the guard above
131+
# and returned early.
132+
133+
# Inf is represented in IEEE 754 with all 11 exponent bits set to 1
134+
# and a mantissa of 0, giving get_ieee_754_exponent a result of 1024
135+
# and correction a value of -1.
136+
137+
# NaN is represented in IEEE 754 with all 11 exponent bits set to 1
138+
# and a non-zero mantissa of unspecified bit pattern, producing an
139+
# unspecified correction value.
140+
141+
# Inf and NaN are not caught by the guard above. Callers must ensure
142+
# that only finite, positive values are passed to map_to_index.
126143
correction = (get_ieee_754_mantissa(value) - 1) >> MANTISSA_WIDTH
127144

128145
return (exponent + correction) >> -self._scale

0 commit comments

Comments
 (0)