logger

type AttrValue struct {
	// Key identifies the attribute in the output line.
	Key string
	// Value carries the typed payload; handlers dispatch on Value.Kind().
	Value Value
}

type Encoder interface {
	// Name returns the canonical encoder identifier ("text", "ndjson",
	// "json"). Useful for diagnostic dumps and metrics tagging.
	Name() (name string)
	// Append serialises r onto dst and returns the (possibly re-allocated)
	// buffer. groups carries the active group prefix stack — encoders are
	// responsible for rendering it as their format-specific prefix
	// ("g1.g2.key" for text, nested objects for JSON).
	Append(dst []byte, groups []string, r RecordEvent) (out []byte)
}

type Handler interface {
	// Enabled reports whether the handler would emit a record at the given
	// level, allowing callers to skip expensive attribute construction.
	Enabled(ctx context.Context, r RecordEvent) (enabled bool)
	// Handle formats and writes a RecordEvent. Returning a non-nil error
	// signals a sink failure; the Logger may drop the record regardless.
	Handle(ctx context.Context, r RecordEvent) (err error)
	// WithAttrs returns a derived Handler that prepends the given attrs to
	// every subsequent RecordEvent. The receiver MUST NOT be mutated.
	WithAttrs(attrs []AttrValue) (child Handler)
	// WithGroup returns a derived Handler that namespaces every subsequent
	// attribute key under the given group name (rendered as "group.key"
	// for text handlers, or as a nested object for structured handlers).
	// An empty name MUST be treated as a no-op so callers can pass user
	// input without guarding it.
	WithGroup(name string) (child Handler)
}

type Kind int8

type Logger interface {
	// Log emits a RecordEvent at the given level with the supplied message
	// and attrs. Implementations SHOULD short-circuit when Enabled returns
	// false to avoid unnecessary formatting work.
	Log(ctx context.Context, lv level.Level, msg string, attrs ...AttrValue)
	// With returns a derived Logger whose emitted records always include the
	// supplied attrs. The receiver MUST NOT be mutated.
	With(attrs ...AttrValue) (child Logger)
	// WithGroup returns a derived Logger whose subsequent attributes are
	// namespaced under the given group name. Empty names MUST be a no-op.
	WithGroup(name string) (child Logger)
	// Enabled reports whether a record at the given level would be emitted.
	Enabled(ctx context.Context, lv level.Level) (enabled bool)
}

type RecordEvent struct {
	// Time is the instant the event occurred; zero means "fill in at handle time".
	Time time.Time
	// Level is the severity of the event.
	Level level.Level
	// Message is the human-readable description of the event.
	Message string
	// PC is the program counter captured at the Log call site (via
	// runtime.Callers). Zero means "no caller information available";
	// handlers SHOULD resolve PC into a frame lazily at format time.
	PC uintptr
	// Attrs carries the structured key/value pairs attached to this event.
	Attrs []AttrValue
	// TraceContext is the identity of the span this event was emitted
	// inside; the zero value means "no trace here" and MUST render nothing.
	// It is a FIELD rather than two entries in Attrs because the Encoder
	// port receives no context.Context — the identity has to travel on the
	// record to reach the formatter at all — and because OpenTelemetry
	// prescribes trace_id / span_id as TOP-LEVEL keys of the log object,
	// which an attribute cannot be: WithGroup would prefix it. See ADR 0062.
	TraceContext TraceContextValue
}

type Sink interface {
	// Write delivers the formatted byte payload p plus the originating record
	// to the underlying transport. Sinks MAY ignore p and re-serialise from
	// r when their wire protocol differs from the encoder's output (e.g. a
	// CloudWatch sink reads r.Time directly to populate the AWS request).
	Write(ctx context.Context, r RecordEvent, p []byte) (n int, err error)
	// Flush forces any buffered records out. A no-op for synchronous sinks.
	Flush(ctx context.Context) (err error)
	// Close releases any resources held by the sink (file descriptors, AWS
	// clients, network connections). Sinks MAY refuse subsequent Writes
	// after Close returns; callers MUST NOT use the sink after closing it.
	Close() (err error)
}

type TraceContextSource func(ctx context.Context) (trace TraceContextValue)

type TraceContextValue struct {
	// TraceID identifies the whole trace; rendered as 32 lowercase hex digits.
	TraceID [TraceIDLen]byte
	// SpanID identifies the span within the trace; 16 lowercase hex digits.
	SpanID [SpanIDLen]byte
}

type Value struct {
	// contains filtered or unexported fields
}