okit/api.go

// Copyright (C) 2022 The OKit Authors
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
// OR OTHER DEALINGS IN THE SOFTWARE.

package okit

import (
	"context"
	"strings"
)

// Logger defines common operations for writing log messages.
type Logger interface {
	// Debug adds a debug message to the event stream, if configured.
	Debug(msg string, tags ...Tag)
	// Info adds an informational message to the event stream.
	Info(msg string, tags ...Tag)
	// Warn adds a warning to the event stream.
	Warn(msg string, tags ...Tag)
	// Error adds an error to the event stream.
	Error(msg string, tags ...Tag)
}

// Emitter is used to send multidimensional events to the underlying stream.
type Emitter interface {
	// Emit sends the named event along the underlying stream.
	Emit(event string, tags ...Tag)
}

// Observer allows metrics to be captured and emit from the system.
type Observer interface {
	// Observe records the associated metric and value.
	Observe(metric string, value float64, tags ...Tag)
}

// DoneFunc represents a function that is called when a trace is complete.
type DoneFunc func()

// Tracer allows method calls to be instrumented for debugging.
type Tracer interface {
	// Trace captures the method calling context and returns a function that can be invoked to complete the trace.
	Trace(ctx context.Context, tags ...Tag) (context.Context, DoneFunc)
}

// Span defines an internal structure for tracking traces across an application. This structure is only used for
// tracking purposes and direct modifications will not be reflected.
type Span struct {
	// TraceID specifies an identifier for the overall trace event. This value is often inherited from a parent.
	TraceID string
	// ID uniquely identifies a span within a trace.
	ID string
	// ParentID points to the id of the wrapping span.
	ParentID string
}

// Wither allows tags to be appended to any implementing client.
type Wither[T any] interface {
	With(tags ...Tag) T
}

// Interface defines an abstraction that contains all the user-facing functions.
type Interface[T any] interface {
	Logger
	Emitter
	Observer
	Tracer
	Wither[T]
}

type Level int8

const (
	UnknownLevel = 0
	TraceLevel   = 1
	DebugLevel   = 2
	InfoLevel    = 3
	WarnLevel    = 4
	ErrorLevel   = 5
)

func (l *Level) String() string {
	switch *l {
	case TraceLevel:
		return "trace"
	case DebugLevel:
		return "debug"
	case InfoLevel:
		return "info"
	case WarnLevel:
		return "warn"
	case ErrorLevel:
		return "error"
	}

	return "unknown"
}

func (l *Level) Set(val string) error {
	switch {
	case strings.EqualFold("trace", val):
		*l = TraceLevel
	case strings.EqualFold("debug", val):
		*l = DebugLevel
	case strings.EqualFold("info", val):
		*l = InfoLevel
	case strings.EqualFold("warn", val):
		*l = WarnLevel
	case strings.EqualFold("error", val):
		*l = ErrorLevel
	}

	*l = UnknownLevel
	return nil
}