Severity impl TextUnmarshaler/TextMarshaler

Author: MrAlias

processors/minsev/severity.go

@@ -4,7 +4,11 @@
 package minsev // import "go.opentelemetry.io/contrib/processors/minsev"
 
 import (
+	"encoding"
+	"errors"
 	"fmt"
+	"strconv"
+	"strings"
 	"sync/atomic"
 
 	"go.opentelemetry.io/otel/log"
@@ -16,8 +20,14 @@ import (
 // as errors and critical events).
 type Severity int
 
-// Ensure Severity implements fmt.Stringer.
-var _ fmt.Stringer = Severity(0)
+var (
+	// Ensure Severity implements fmt.Stringer.
+	_ fmt.Stringer = Severity(0)
+	// Ensure Severity implements encoding.TextMarshaler.
+	_ encoding.TextMarshaler = Severity(0)
+	// Ensure Severity implements encoding.TextUnmarshaler.
+	_ encoding.TextUnmarshaler = (*Severity)(nil)
+)
 
 // Severity values defined by OpenTelemetry.
 const (
@@ -73,6 +83,10 @@ const (
 // It implements [Severitier].
 func (s Severity) Severity() log.Severity {
 	// Unknown defaults to log.SeverityUndefined.
+	//
+	// TODO: return a clamped log.Severity. If s is less than
+	// SeverityTrace1, return log.SeverityTrace1, if s is greater than
+	// SeverityFatal4, return log.SeverityFatal4.
 	return translations[s]
 }
 
@@ -147,6 +161,105 @@ func (s Severity) String() string {
 	}
 }
 
+// AppendText implements [encoding.TextAppender] by calling [Severity.String].
+func (s Severity) AppendText(b []byte) ([]byte, error) {
+	return append(b, s.String()...), nil
+}
+
+// MarshalText implements [encoding.TextMarshaler] by calling
+// [Severity.AppendText].
+func (s Severity) MarshalText() ([]byte, error) {
+	return s.AppendText(nil)
+}
+
+// UnmarshalText implements [encoding.TextUnmarshaler]. It accepts any string
+// produced by [Severity.MarshalText], ignoring case. It also accepts numeric
+// offsets that would result in a different string on output. For example,
+// "ERROR-8" will marshal as SeverityInfo.
+func (s *Severity) UnmarshalText(data []byte) error {
+	return s.parse(string(data))
+}
+
+// parse parses str into s.
+//
+// It will return an error if str is not a valid severity string.
+//
+// The string is expected to be in the format of "NAME[N][+/-OFFSET]", where
+// NAME is one of the severity names ("TRACE", "DEBUG", "INFO", "WARN",
+// "ERROR", "FATAL"), OFFSET is an optional signed integer offset, and N is an
+// optional fine-grained severity level that modifies the base severity name.
+//
+// Name is parsed in a case-insensitive way. Meaning, "info", "Info",
+// "iNfO", etc. are all equivalent to "INFO".
+//
+// Fine-grained severity levels are expected to be in the range of 1 to 4,
+// where 1 is the base severity level, and 2, 3, and 4 are more fine-grained
+// levels. However, fine-grained levels greater than 4 are also accepted, and
+// they will be treated as an 1-based offset from the base severity level.
+//
+// For example, "ERROR3" will be parsed as "ERROR" with a fine-grained level of
+// 3, which corresponds to `SeverityError3`, "FATAL+2" will be parsed as
+// "FATAL" with an offset of +2, which corresponds to `SeverityFatal2`, and
+// "INFO2+1" is parsed as INFO with a fine-grained level of 2 and an offset of
+// +1, which corresponds to `SeverityInfo3`.
+//
+// Fine-grained severity levels are based on counting numbers excluding zero.
+// If a fine-grained level of 0 is provided it is treaded as equivalent to the
+// base severity level.  For example, "INFO0" is equivalent to `SeverityInfo1`.
+func (s *Severity) parse(str string) (err error) {
+	defer func() {
+		if err != nil {
+			err = fmt.Errorf("minsev: severity string %q: %w", str, err)
+		}
+	}()
+
+	name := str
+	offset := 0
+
+	// Parse +/- offset suffix, if present.
+	if i := strings.IndexAny(str, "+-"); i >= 0 {
+		name = str[:i]
+		offset, err = strconv.Atoi(str[i:])
+		if err != nil {
+			return err
+		}
+	}
+
+	// Parse fine-grained severity level suffix, if present.
+	// This supports formats like "ERROR3", "FATAL4", etc.
+	i := len(name)
+	n, multi := 0, 1
+	for ; i > 0 && str[i-1] >= '0' && str[i-1] <= '9'; i-- {
+		n += int(str[i-1]-'0') * multi
+		multi *= 10
+	}
+	if i < len(name) {
+		name = name[:i]
+		if n != 0 {
+			offset += n - 1 // Convert 1-based to 0-based.
+		}
+	}
+
+	switch strings.ToUpper(name) {
+	case "TRACE":
+		*s = SeverityTrace1
+	case "DEBUG":
+		*s = SeverityDebug1
+	case "INFO":
+		*s = SeverityInfo1
+	case "WARN":
+		*s = SeverityWarn1
+	case "ERROR":
+		*s = SeverityError1
+	case "FATAL":
+		*s = SeverityFatal1
+	default:
+		return errors.New("unknown name")
+	}
+	*s += Severity(offset)
+	return nil
+}
+
 // A SeverityVar is a [Severity] variable, to allow a [LogProcessor] severity
 // to change dynamically. It implements [Severitier] as well as a Set method,
 // and it is safe for use by multiple goroutines.

processors/minsev/severity_go1.24.go

@@ -0,0 +1,14 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build go1.24
+// +build go1.24
+
+package minsev // import "go.opentelemetry.io/contrib/processors/minsev"
+
+import "encoding"
+
+var (
+	_ encoding.TextAppender = Severity(0)         // Ensure Severity implements encoding.TextAppender.
+	_ encoding.TextAppender = (*SeverityVar)(nil) // Ensure Severity implements encoding.TextAppender.
+)

processors/minsev/severity_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/otel/log"
 )
 
@@ -81,10 +82,128 @@ var validEncodingTests = []struct {
 	{"SeverityFatal4Plus2", SeverityFatal4 + 2, "FATAL+6"},
 }
 
+var validDecodingTests = []struct {
+	Name     string
+	Severity Severity
+	Text     string
+}{
+	{"SeverityTrace", SeverityTrace, "TRACE"},
+	{"SeverityTrace1", SeverityTrace1, "TRACE"},
+	{"SeverityTrace2", SeverityTrace2, "TRACE2"},
+	{"SeverityTrace3", SeverityTrace3, "TRACE3"},
+	{"SeverityTrace4", SeverityTrace4, "TRACE4"},
+	{"SeverityDebug", SeverityDebug, "DEBUG"},
+	{"SeverityDebug1", SeverityDebug1, "DEBUG"},
+	{"SeverityDebug2", SeverityDebug2, "DEBUG2"},
+	{"SeverityDebug3", SeverityDebug3, "DEBUG3"},
+	{"SeverityDebug4", SeverityDebug4, "DEBUG4"},
+	{"SeverityInfo", SeverityInfo, "INFO"},
+	{"SeverityInfo1", SeverityInfo1, "INFO"},
+	{"SeverityInfo2", SeverityInfo2, "INFO2"},
+	{"SeverityInfo3", SeverityInfo3, "INFO3"},
+	{"SeverityInfo4", SeverityInfo4, "INFO4"},
+	{"SeverityWarn", SeverityWarn, "WARN"},
+	{"SeverityWarn1", SeverityWarn1, "WARN"},
+	{"SeverityWarn2", SeverityWarn2, "WARN2"},
+	{"SeverityWarn3", SeverityWarn3, "WARN3"},
+	{"SeverityWarn4", SeverityWarn4, "WARN4"},
+	{"SeverityError", SeverityError, "ERROR"},
+	{"SeverityError1", SeverityError1, "ERROR"},
+	{"SeverityError2", SeverityError2, "ERROR2"},
+	{"SeverityError3", SeverityError3, "ERROR3"},
+	{"SeverityError4", SeverityError4, "ERROR4"},
+	{"SeverityFatal", SeverityFatal, "FATAL"},
+	{"SeverityFatal1", SeverityFatal1, "FATAL"},
+	{"SeverityFatal2", SeverityFatal2, "FATAL2"},
+	{"SeverityFatal3", SeverityFatal3, "FATAL3"},
+	{"SeverityFatal4", SeverityFatal4, "FATAL4"},
+
+	// Test case insensitivity.
+	{"SeverityTraceLower", SeverityTrace1, "trace"},
+	{"SeverityDebugMixed", SeverityDebug1, "Debug"},
+	{"SeverityInfoMixed", SeverityInfo1, "InFo"},
+	{"SeverityInfo3Lower", SeverityInfo3, "info3"},
+
+	// Test offset calculations.
+	{"SeverityTraceMinus2", SeverityTrace1 - 2, "TRACE-2"},
+	{"SeverityWarnPlus2", SeverityWarn3, "WARN+2"},
+	{"SeverityWarn2Plus2", SeverityWarn4, "WARN2+2"},
+	{"SeverityErrorMinus4", SeverityWarn1, "ERROR-4"},
+	{"SeverityError2Minus4", SeverityWarn2, "ERROR2-4"},
+	{"SeverityFatalPlus10", SeverityFatal1 + 10, "FATAL+10"},
+
+	// Test oversized fine-grained severity.
+	{"SeverityTrace15", SeverityWarn3, "TRACE15"},
+	{"SeverityTrace101", SeverityTrace1 + 100, "TRACE101"},
+
+	// Test fine-grained severity of zero.
+	{"SeverityTrace0", SeverityTrace, "TRACE0"},
+	{"SeverityTrace0Plus1", SeverityTrace2, "TRACE0+1"},
+}
+
+var invalidText = []string{
+	"UNKNOWN",
+	"DEBUG3+abc",
+	"INFO+abc",
+	"ERROR-xyz",
+	"not-a-level",
+}
+
 func TestSeverityString(t *testing.T) {
 	for _, test := range validEncodingTests {
 		t.Run(test.Name, func(t *testing.T) {
 			assert.Equal(t, test.Text, test.Severity.String())
 		})
 	}
 }
+
+func TestSeverityMarshalText(t *testing.T) {
+	for _, test := range validEncodingTests {
+		t.Run(test.Name, func(t *testing.T) {
+			got, err := test.Severity.MarshalText()
+			require.NoError(t, err)
+			assert.Equal(t, test.Text, string(got))
+		})
+	}
+}
+
+func TestSeverityUnmarshalText(t *testing.T) {
+	for _, test := range validDecodingTests {
+		t.Run(test.Name, func(t *testing.T) {
+			var sev Severity
+			require.NoError(t, sev.UnmarshalText([]byte(test.Text)))
+			const msg = "UnmarshalText(%q) != %d (%[2]s)"
+			assert.Equalf(t, test.Severity, sev, msg, test.Text, test.Severity)
+		})
+	}
+}
+
+func TestSeverityUnmarshalTextError(t *testing.T) {
+	for _, test := range invalidText {
+		t.Run(test, func(t *testing.T) {
+			var sev Severity
+			err := sev.UnmarshalText([]byte(test))
+			assert.Error(t, err)
+		})
+	}
+}
+
+func TestSeverityAppendText(t *testing.T) {
+	tests := []struct {
+		sev      Severity
+		prefix   string
+		expected string
+	}{
+		{SeverityInfo1, "", "INFO"},
+		{SeverityError1, "level=", "level=ERROR"},
+		{SeverityWarn3, "severity:", "severity:WARN3"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.expected, func(t *testing.T) {
+			result, err := test.sev.AppendText([]byte(test.prefix))
+			require.NoError(t, err)
+			assert.Equal(t, test.expected, string(result))
+		})
+	}
+}