From c4a305fb45080703f988080f8f5af89fd0cc288e Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 3 Jun 2025 09:55:24 +0200 Subject: [PATCH 1/7] Clarify SeverityNumber allowed values --- CHANGELOG.md | 3 +++ specification/logs/data-model.md | 5 ++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aabb68ba04b..2dec0e8cc8e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ release. ### Logs +- Clarify `SeverityNumber` allowed values. + ([#4535](https://github.com/open-telemetry/opentelemetry-specification/pull/4535)) + ### Baggage ### Resource diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index f0db90e8c41..682ff183df4 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -284,7 +284,7 @@ Type: number. Description: numerical value of the severity, normalized to values described in this document. This field is optional. -`SeverityNumber` is an integer number. Smaller numerical values correspond to +`SeverityNumber` is an integer number in range. Smaller numerical values correspond to less severe events (such as debug events), larger numerical values correspond to more severe events (such as errors and critical events). The following table defines the meaning of `SeverityNumber` value: @@ -303,6 +303,9 @@ events. Larger numerical values in each range represent more important (more severe) events. For example `SeverityNumber=17` describes an error that is less critical than an error with `SeverityNumber=20`. +Values outside of the 1..24 range are not considered valid. +0 value MAY be used to represent an unset value. + #### Mapping of `SeverityNumber` Mappings from existing logging systems and formats (or **source format** for From 15ca2236a082cc2302d9a52499c02570b4fd904b Mon Sep 17 00:00:00 2001 From: Robert Pajak Date: Tue, 3 Jun 2025 10:01:30 +0200 Subject: [PATCH 2/7] fixes --- specification/logs/data-model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 682ff183df4..1776e666433 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -284,7 +284,7 @@ Type: number. Description: numerical value of the severity, normalized to values described in this document. This field is optional. -`SeverityNumber` is an integer number in range. Smaller numerical values correspond to +`SeverityNumber` is an integer number. Smaller numerical values correspond to less severe events (such as debug events), larger numerical values correspond to more severe events (such as errors and critical events). The following table defines the meaning of `SeverityNumber` value: @@ -304,7 +304,7 @@ severe) events. For example `SeverityNumber=17` describes an error that is less critical than an error with `SeverityNumber=20`. Values outside of the 1..24 range are not considered valid. -0 value MAY be used to represent an unset value. +0 value MAY be used to represent an unspecified value. #### Mapping of `SeverityNumber` From f75fde89bdc383a468abf79182bcbce9ad2723b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 3 Jun 2025 18:26:34 +0200 Subject: [PATCH 3/7] Update supplementary-guidelines.md --- specification/logs/supplementary-guidelines.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/logs/supplementary-guidelines.md b/specification/logs/supplementary-guidelines.md index 67346488ad6..ff16e5723d3 100644 --- a/specification/logs/supplementary-guidelines.md +++ b/specification/logs/supplementary-guidelines.md @@ -198,7 +198,8 @@ type SeverityProcessor struct { // if the record's severity is greater than or equal to p.Min. // Otherwise, the record is dropped (the wrapped processor is not invoked). func (p *SeverityProcessor) OnEmit(ctx context.Context, record *sdklog.Record) error { - if record.Severity() != log.SeverityUndefined && record.Severity() < p.Min { + sev := record.Severity() + if sev >= log.SeverityTrace1 && sev <= log.SeverityFatal4 && sev < p.Min { return nil } return p.Processor.OnEmit(ctx, record) @@ -207,7 +208,7 @@ func (p *SeverityProcessor) OnEmit(ctx context.Context, record *sdklog.Record) e // Enabled returns false if the severity is lower than p.Min. func (p *SeverityProcessor) Enabled(ctx context.Context, param sdklog.EnabledParameters) bool { sev := param.Severity - if sev != log.SeverityUndefined && sev < p.Min { + if sev >= log.SeverityTrace1 && sev <= log.SeverityFatal4 && sev < p.Min { return false } if fp, ok := p.Processor.(sdklog.FilterProcessor); ok { From 30d365af32ce7488d272c13302a3ad8412939191 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 3 Jun 2025 19:54:57 +0200 Subject: [PATCH 4/7] Update specification/logs/data-model.md --- specification/logs/data-model.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 1776e666433..52364063424 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -303,7 +303,6 @@ events. Larger numerical values in each range represent more important (more severe) events. For example `SeverityNumber=17` describes an error that is less critical than an error with `SeverityNumber=20`. -Values outside of the 1..24 range are not considered valid. 0 value MAY be used to represent an unspecified value. #### Mapping of `SeverityNumber` From 08e966b90689750cce50917c11f79ec557aae5db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 3 Jun 2025 19:57:41 +0200 Subject: [PATCH 5/7] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2dec0e8cc8e..0a590e35f18 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,7 @@ release. ### Logs -- Clarify `SeverityNumber` allowed values. +- `SeverityNumber=0` MAY be used to represent an unspecified value. ([#4535](https://github.com/open-telemetry/opentelemetry-specification/pull/4535)) ### Baggage From fdb058370d84b8c357ae0bb14688790e0e1fd889 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 3 Jun 2025 19:59:26 +0200 Subject: [PATCH 6/7] Update data-model.md --- specification/logs/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 52364063424..3254a6c06f0 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -303,7 +303,7 @@ events. Larger numerical values in each range represent more important (more severe) events. For example `SeverityNumber=17` describes an error that is less critical than an error with `SeverityNumber=20`. -0 value MAY be used to represent an unspecified value. +`SeverityNumber=0` MAY be used to represent an unspecified value. #### Mapping of `SeverityNumber` From 9958772b40fa0b7b681ac47a937af5fff1ddda8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 4 Jun 2025 08:31:30 +0200 Subject: [PATCH 7/7] Revert SeverityProcessor example --- specification/logs/supplementary-guidelines.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/logs/supplementary-guidelines.md b/specification/logs/supplementary-guidelines.md index ff16e5723d3..67346488ad6 100644 --- a/specification/logs/supplementary-guidelines.md +++ b/specification/logs/supplementary-guidelines.md @@ -198,8 +198,7 @@ type SeverityProcessor struct { // if the record's severity is greater than or equal to p.Min. // Otherwise, the record is dropped (the wrapped processor is not invoked). func (p *SeverityProcessor) OnEmit(ctx context.Context, record *sdklog.Record) error { - sev := record.Severity() - if sev >= log.SeverityTrace1 && sev <= log.SeverityFatal4 && sev < p.Min { + if record.Severity() != log.SeverityUndefined && record.Severity() < p.Min { return nil } return p.Processor.OnEmit(ctx, record) @@ -208,7 +207,7 @@ func (p *SeverityProcessor) OnEmit(ctx context.Context, record *sdklog.Record) e // Enabled returns false if the severity is lower than p.Min. func (p *SeverityProcessor) Enabled(ctx context.Context, param sdklog.EnabledParameters) bool { sev := param.Severity - if sev >= log.SeverityTrace1 && sev <= log.SeverityFatal4 && sev < p.Min { + if sev != log.SeverityUndefined && sev < p.Min { return false } if fp, ok := p.Processor.(sdklog.FilterProcessor); ok {