loggerapi

type EventTracingCounters []int

type IEvent interface {
	GetTraceContext() *TraceContext
	GetUserObject() (uo any)

	// Attach any user object to the event object, to be used later
	// inside the callback hooks. Intended to pass user-level runtime data to the
	// hook(s). Doesn't add anything to the logline serializations.
	// Normally, the UO must be a pointer, and at the receiving side in the hook
	// you do something along the lines:
	//
	//	myObject, _ := e.GetUserObject().(*MyObject)
	//	if myObject !=  nil {
	//		...
	//	}
	//
	// Only works if you created a chain with SubLoggerInitChain()
	AddUserObject(uo any) IEvent

	// Inactivation applies to real events only, all data set ops will be bypassed.
	// However, if applied to sub-logger init chain, nothing is bypassed.
	Inactive() IEvent

	// This is useful to do some work only if the event is activated, e.g. do some data prep
	// or JSON marshalling, and waste no time otherwise.
	//
	//	     logger.InfoEvent().Inactive().Msgtag().IfActive(func(ev IEvent) {
	//				// do some heavy work, then
	//				ev.RawJSON(b)
	//			}).Title("my event").Send()
	IfActive(func(IEvent)) IEvent

	Caller(skip ...int) IEvent
	Str(string, string) IEvent
	Strf(string, string, ...any) IEvent
	Strs(string, []string) IEvent
	Time(string, time.Time) IEvent
	Int(string, int) IEvent
	Ints(string, []int) IEvent
	Float64(string, float64) IEvent
	Floats64(string, []float64) IEvent
	Array(k string, v *zerolog.Array) (e IEvent)
	Dict(k string, v *zerolog.Event) (e IEvent)

	// Must not be used on sub-logger init chains.
	SendMsgf(string, ...any)

	// Must not be used on sub-logger init chains.
	SendMsg(string)

	// It's like Msg(), but sets the value to "title" field, and also
	// can be used to report to metrics. Must be low-cardinality string.
	// DO NOT put in it any variable strings, e.g. Sprintf()-formatted or
	// containing requestId or any other Id or counters!
	// Can't be applied for sub-logger chains, only for events.
	// In typical idiom, must be used BEFORE the Msgtag() - it's specififcally
	// designed to not bypass in inactive events.
	Title(string) IEvent

	// The same as Title().Send()
	// Must not be used on sub-logger init chains.
	SendTitle(string)

	// Also must be reported to metrics.
	SubSystem(string) IEvent
	RequestId(string) IEvent
	RawJSON(string, []byte) IEvent
	Bytes(string, []byte) IEvent

	// Must not be used on sub-logger init chains.
	Send()

	// Only works if you created a chain with SubLoggerInitChain()
	WithClonedRootContext(optFuncs ...func(rctx *RootContext)) IEvent
	ILogger() ILogger
}

type ILogger interface {
	TraceEvent(msgtag string) IEvent
	DiagnosticEvent(msgtag string) IEvent
	InfoEvent(msgtag string) IEvent
	WarnEvent(msgtag string) IEvent
	ErrorEvent(msgtag string) IEvent
	ErrEvent(err error, msgtag string) IEvent

	// Can be used if you intend to call ILogger() on it later.
	// By default, all new sub-loggers are active, even if parent was inactivated.
	SubLoggerInitChain(msgtag string) IEvent

	SetLevel(zerolog.Level) ILogger
}

type Msgtags []string

type RootContext struct {
	MainWriter      io.Writer
	PanicOnMisuse   bool
	MsgtagKey       string
	XUIdKey         string // XU logger root id
	ETCKey          string // event tracing counters
	IfSendHook      func(e IEvent) (doSend bool)
	EventOnWireHook func(p []byte)
	ActivationHook  func(e IEvent) (inactivate bool) // If the ActicationHook is set, it is called, and it can reactivate the event.
}

type TraceContext struct {
	ETC     EventTracingCounters
	Msgtags Msgtags
}