From c2fdbcaea88641e4c98d44a1c443495826b937f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 21 Feb 2024 07:02:08 +0100 Subject: [PATCH] design: log value accessors must not panic (#4948) --- log/DESIGN.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/log/DESIGN.md b/log/DESIGN.md index f08de5d8431..2a342bd53f7 100644 --- a/log/DESIGN.md +++ b/log/DESIGN.md @@ -362,6 +362,18 @@ and the API is mostly inspired by The benchmarks[^1] show that the implementation is more performant than [`attribute.Value`](https://pkg.go.dev/go.opentelemetry.io/otel/attribute#Value). +The value accessors (`func (v Value) As[Kind]` methods) must not panic, +as it would violate the [specification](https://opentelemetry.io/docs/specs/otel/error-handling/): + +> API methods MUST NOT throw unhandled exceptions when used incorrectly by end +> users. The API and SDK SHOULD provide safe defaults for missing or invalid +> arguments. [...] Whenever the library suppresses an error that would otherwise +> have been exposed to the user, the library SHOULD log the error using +> language-specific conventions. + +Therefore, the value accessors should return a zero value +and log an error when a bad accessor is called. + The `Severity`, `Kind`, `Value`, `KeyValue` may implement the [`fmt.Stringer`](https://pkg.go.dev/fmt#Stringer) interface. However, it is not needed for the first stable release