Document the design

docs/design/log-api.md

@@ -1,4 +1,4 @@
-# Logs Bridge API Design
+# Logs Bridge API
 
 Author: Robert Pająk
 
@@ -9,35 +9,103 @@ Tracking issue at [#4696](https://github.com/open-telemetry/opentelemetry-go/iss
 <!-- A short summary of the proposal. -->
 
 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
 
 <!-- An introduction of the necessary background and the problem being solved by the proposed change. -->
 
 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
 
-The design and 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]
+This proposed design aims to:
 
-<!-- A precise statement of the proposed change. -->
+- be specification compliant,
+- have similar API to Trace and Metrics API,
+- take advantage of both OpenTelemetry and `slog` experience to achieve acceptable performance.
 
-## Rationale
+### LoggerProvider
 
-<!-- A discussion of alternate approaches and the trade offs, advantages, and disadvantages of the specified approach. -->
+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
+```
+
+`Record` has `AddAttr` and `Attr` methods,
+like in [`slog.Record`](https://pkg.go.dev/log/slog#Record),
+in order to achieve high-preformance,
+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 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
+
+<!-- A discussion of alternate approaches and the trade offs, advantages, and disadvantages of the specified approach. -->
+
 ## Implementation
 
 <!-- A description of the steps in the implementation, who will do them, and when. -->