Clarify boundaries of numeric env vars #4331
Conversation
|
Need a changelog entry. |
Related to #4283. A [comment](#4331 (comment)) adding a "type" column to each env var, but didn't feel appropriate to extend scope of #4331. --------- Co-authored-by: Carlos Alberto Cortez <[email protected]> Co-authored-by: Reiley Yang <[email protected]>
|
This PR was marked stale due to lack of activity. It will be closed in 7 days. |
| Timeout is a sub-classification of [duration](#duration): All timeouts are also | ||
| durations, but not all durations are timeouts. | ||
|
|
There was a problem hiding this comment.
is this important? I ask because it seems that 0 duration is defined as zero milliseconds, and so it's hard for me to think of timeouts as a "subclass" of duration since they don't have that behavior
| Timeout is a sub-classification of [duration](#duration): All timeouts are also | |
| durations, but not all durations are timeouts. | |
| Timeout is a sub-classification of [duration](#duration): All timeouts are also | |
| durations, but not all durations are timeouts. | |
There was a problem hiding this comment.
From duration we get:
Any value that represents a duration MUST be an integer representing a number of milliseconds. The value is non-negative - if a negative value is provided, the implementation MUST generate a warning, gracefully ignore the setting and use the default value if it is defined. For example, the value 12000 indicates 12000 milliseconds, i.e., 12 seconds.
From timeout's perspective, the useful bits which are inherited are:
- timeouts are integers representing a number of milliseconds
- values are non-negative, warn if negative value is given
You make a good point that the zero value semantics are different for duration and timeout. We could keep it as is, where timeout essentially overrides the duration zero value semantics. Copy the bits of duration semantics we care about into timeout.
There was a problem hiding this comment.
We could keep it as is, where timeout essentially overrides the duration zero value semantics
this would make sense to me if the timeout restricted ("narrowed") the behavior of its "super type", but that's not the case here, so it doesn't seem like a duration in my mind (a timeout can't be used in places where a duration would be used). probably I'm thinking too much OOP
| | OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | no limit | [Integer][] | Valid values are non-negative. | | ||
| | OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | [Integer][] | Valid values are non-negative. | | ||
| | OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | [Integer][] | Valid values are non-negative. | | ||
| | OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | [Integer][] | Valid values are non-negative. | | ||
| | OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | [Integer][] | Valid values are non-negative. | | ||
| | OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 | [Integer][] | Valid values are non-negative. | |
There was a problem hiding this comment.
can we say anything useful about the 0 value for these env vars?
There was a problem hiding this comment.
The zero value is valid here. Are you suggesting a change in semantics or improved phrasing to make it more clear that zero is valid?
There was a problem hiding this comment.
ah, I wasn't sure if 0 mean none or unlimited here
but re-reading it seems that none is the obvious interpretation and may not need clarification
sort of related, it's a bit odd that the default value of OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT isn't expressible as a valid value, maybe it should allow -1 for unlimited? (might be a nice general property for declarative config to always be able to "get back" the default value when someone else has overridden it)
There was a problem hiding this comment.
sort of related, it's a bit odd that the default value of OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT isn't expressible as a valid value, maybe it should allow -1 for unlimited
I don't disagree - but I'm reluctant to try to tackle that in this PR 😛.
A user can use effectively express the default config with something like the max value of a 32 bit integer (2,147,483,647). Obviously its a lot more cumbersome than -1.
Resolves #4283.
OTEL_ATTRIBUTE_*/OTEL_SPAN_ATTRIBUTE_*/OTEL_LOGRECORD_ATTRIBUTE_*,OTEL_BSP_MAX_QUEUE_SIZE,OTEL_BLRP_MAX_QUEUE_SIZE.Related PR to
opentelemetry-configuration: open-telemetry/opentelemetry-configuration#151