Clarify log record severity comparison

[pellared]

Follows:

• SeverityNumber=0 MAY be used to represent an unspecified value #4535

Why

Related to #4540

Supersedes #4541 per #4541 (comment) and discussions from the last OTel Specification and Logs SIG meetings.

Some comments that were already expressed as comments.

From #4541 (comment):

I'd be in favor of treating 0 as yet another severity when it comes to filtering and comparison, i.e. logs with unspecified/0 severity are dropped when threshold > 0 and are recorded otherwise.

From #4541 (comment):

I think I like the simplicity of

if sev < p.Min {
// drop
}

it provides a very reasonable default behavior, which is to drop logs that don't have any severity

This is also inline with

opentelemetry-specification/specification/logs/data-model.md

Lines 323 to 329 in 7e7c0bd

	If the source format has only a single severity that matches the meaning of the
	range then it is recommended to assign that severity the smallest value of the
	range.
	For example if the source format has an "Informational" log level and no other
	log levels with similar meaning then it is recommended to use
	`SeverityNumber=9` for "Informational".

From #4540 (comment):

Relying on int comparison seems to be the most natural option

We agreed that this PR does conflict proposal to allow only allow/support 0..24 SeverityNumber values.

What

Removal of

SeverityNumber can be compared to another SeverityNumber or to numbers in the 1..24 range (or to the corresponding short names).

as I find that this sentence is more confusing than clarifying:

1. why comparing values of different types?
2. why can we compare only with integers between 1..24?
3. what about SeverityNumber that are greater than 24 or lesser than 1?
4. are the short names normative?

Removal of duplicated description

Smaller numerical values in each range represent less important (less severe) events. Larger numerical values in each range represent more important (more severe) events.

Moving the comparison example to a better place where the SeverityNumber comparison is described

For example SeverityNumber=17 describes an error that is less critical than an error with SeverityNumber=20.

Simplify SeverityProcessor example.

Prototype

This is exactly how https://pkg.go.dev/go.opentelemetry.io/contrib/processors/minsev currently works.

[pellared]

This applied suggestion makes this PR blocked by:

• SeverityNumber=0 MAY be used to represent an unspecified value #4535

[pellared]

SIG meeting notes:
Because of e.g. https://protobuf.dev/programming-guides/enum/#java it is safer to allow only 0..24 values.
I am going to propose a separate issues/PRs to address it.

[pellared]

Because of e.g. https://protobuf.dev/programming-guides/enum/#java it is safer to allow only 0..24 values.
I am going to propose a separate issues/PRs to address it.

I feel that this PR does not contradict with the proposal to allow only 0..24 when exporting via OTLP.
Therefore, I am planing to reopen this PR once #4535 is merged.

[pellared]

Logs SIG meeting:
We agreed that this PR does conflict proposal to allow only allow/support 0..24 SeverityNumber values and that this PR polishes and clarifies the specification.

We also agreed that, due to the current state of Logs language implementations and the OTLP proto definition, we can only RECOMMEND using values between 0 and 24.

[carlosalberto]

How do you know whether SeverityNumberr=0 if used as unspecified value or not?

[pellared]

This is applicable for language implementations where SeverityNumber=0 represents unspecified value. For them SeverityNumber=0 is always used to say that the value is unspecified.

I am not sure if we need to say anything for languages like Rust or Swift.
@open-telemetry/rust-maintainers, @open-telemetry/swift-maintainers: WDYT?

Reference: #4535