diff --git a/docs/design/log-api.md b/docs/design/log-api.md index 9a8ef8b1053a..b8803da5be0d 100644 --- a/docs/design/log-api.md +++ b/docs/design/log-api.md @@ -1,4 +1,4 @@ -# Logs Bridge API Design +# Logs Bridge API Author: Robert PajÄ…k @@ -9,8 +9,7 @@ Tracking issue at [#4696](https://github.com/open-telemetry/opentelemetry-go/iss We propose adding a `go.opentelemetry.io/otel/log` Go module which will provide -[Logs Data Model](https://opentelemetry.io/docs/specs/otel/logs/data-model/) -and [Logs Bridge API](https://opentelemetry.io/docs/specs/otel/logs/data-model/). +[Logs Bridge API](https://opentelemetry.io/docs/specs/otel/logs/bridge-api/). ## Background @@ -18,26 +17,125 @@ and [Logs Bridge API](https://opentelemetry.io/docs/specs/otel/logs/data-model/) They key challenge is to create API which will be complaint with the specification and be as performant as possible. - Performance is seen as one of the most imporatant charactristics of logging libraries in Go. -## Proposal +## Design + +This proposed design aims to: + +- be specification compliant, +- have similar API to Trace and Metrics API, +- take advantage of both OpenTelemetry and `slog` experience to achieve acceptable performance. + +### LoggerProvider + +The [`LoggerProvider` abstraction](https://opentelemetry.io/docs/specs/otel/logs/bridge-api/#loggerprovider) +is defined as an interface. + +```go +type LoggerProvider interface{ + Logger(name string, options ...LoggerOption) Logger +} +``` + +### Logger + +The [`Logger` abstraction](https://opentelemetry.io/docs/specs/otel/logs/bridge-api/#logger) +is defined as an interface. + +```go +type Logger interface{ + Emit(context.Context, options ...RecordOption) +} +``` + +The `Logger` has `Emit(context.Context, options ...RecordOption` method. + +### Record + +The [`LogRecord` abstraction](https://opentelemetry.io/docs/specs/otel/logs/bridge-api/#logger) +is defined as a struct. + +```go +type Record struct { + Timestamp time.Time + ObservedTimestamp time.Time + Severity Severity + SeverityText string + Body string + + // Allocation optimization: an inline array sized to hold + // the majority of log calls (based on examination of open-source + // code). It holds the start of the list of Attrs. + front [nAttrsInline]Attr + + // The number of Attrs in front. + nFront int + + // The list of Attrs except for those in front. + // Invariants: + // - len(back) > 0 iff nFront == len(front) + // - Unused array elements are zero. Used to detect mistakes. + back []Attr +} + +const nAttrsInline = 5 + +type Severity int + +const ( + SeverityUndefined Severity = iota + SeverityTrace + SeverityTrace2 + SeverityTrace3 + SeverityTrace4 + SeverityDebug + SeverityDebug2 + SeverityDebug3 + SeverityDebug4 + SeverityInfo + SeverityInfo2 + SeverityInfo3 + SeverityInfo4 + SeverityWarn + SeverityWarn2 + SeverityWarn3 + SeverityWarn4 + SeverityError + SeverityError2 + SeverityError3 + SeverityError4 + SeverityFatal + SeverityFatal2 + SeverityFatal3 + SeverityFatal4 +) +``` + +`Record` has `AddAttr` and `Attr` methods, +like in [`slog.Record`](https://pkg.go.dev/log/slog#Record), +in order to achieve high-performance, +when accessing and setting attributes efficiently via `AddAttr` and `Attr` methods. + +The `NewRecord(...RecordOption) Record` is a factory function used to create records using provided options. + +`Record` has a `Clone` method to allow copying records so that the SDK can offer concurrency safety. + +## Compatibility + +The backwards compatibility is achieved using the `embedded` design pattern +that is already used in Trace API and Metrics API. + +## Benchmarking -The design and benchmarks takes inspiration from [`slog`](https://pkg.go.dev/log/slog), +The benchmarks takes inspiration from [`slog`](https://pkg.go.dev/log/slog), because for the Go team it was also critical to create API that would be fast and interoperable with existing logging packages. [^1] [^2] - - ## Rationale -## Compatibility - -The backwards compatibility is achieved using the `embedded` design pattern -that is already used in Trace API and Metrics API. - ## Implementation