crate/log/log.go

// log 实现了全局的日志处理
//
// 这个包里定义的函数都是对全局的 [logsdk.Logger] 对象的封装.
// 全局的 Logger 不能重新赋值,
// Logger 的配置方法和日志方法可以并发调用.

package log

import (
	"context"
	"fmt"
	"time"

	"git.blauwelle.com/go/crate/log/logsdk"
)

type (
	Level = logsdk.Level
)

const (
	LevelPanic = logsdk.LevelPanic
	LevelFatal = logsdk.LevelFatal
	LevelError = logsdk.LevelError
	LevelWarn  = logsdk.LevelWarn
	LevelInfo  = logsdk.LevelInfo
	LevelDebug = logsdk.LevelDebug
	LevelTrace = logsdk.LevelTrace
)

// Field 返回键值对
func Field(key string, value any) logsdk.KV {
	return logsdk.KV{
		Value: value,
		Key:   key,
	}
}

// AddCallerSkip 增加调用 [runtime.Callers] 时的 skip 参数,
// 当通过装饰器等方式封装 Entry 导致增加调用 Entry 方法的深度时使用 AddCallerSkip 调整 skip,
// 直接在需要日志的地方调用 Entry 的方法时不需要 AddCallerSkip.
func AddCallerSkip(n int) logsdk.Entry {
	return globalLogger.AddCallerSkip(n)
}

// WithField 增加1组键值对
func WithField(key string, value any) logsdk.Entry {
	return globalLogger.WithField(key, value)
}

// WithFields 增加键值对
func WithFields(fields ...logsdk.KV) logsdk.Entry {
	return globalLogger.WithFields(fields...)
}

// WithTime 设置日志的时间,
// Entry 默认使用调用 Log 等最终方法的时间作为日志的时间.
func WithTime(t time.Time) logsdk.Entry {
	return globalLogger.WithTime(t)
}

// WithReportCaller 设置 [logsdk.Entry] 是否收集调用记录
func WithReportCaller(reportCaller bool) logsdk.Entry {
	return globalLogger.WithReportCaller(reportCaller)
}

// WithReportStack 设置 [logsdk.Entry] 是否收集调用栈
func WithReportStack(reportStack bool) logsdk.Entry {
	return globalLogger.WithReportStack(reportStack)
}

// Log 输出日志
func Log(ctx context.Context, level Level, args ...any) {
	globalLogger.AddCallerSkip(1).Log(ctx, level, fmt.Sprint(args...))
}

// Trace 输出 LevelTrace 等级的日志
func Trace(ctx context.Context, args ...any) {
	globalLogger.AddCallerSkip(1).Trace(ctx, args...)
}

// Debug 输出 LevelDebug 等级的日志
func Debug(ctx context.Context, args ...any) {
	globalLogger.AddCallerSkip(1).Debug(ctx, args...)
}

// Info 输出 LevelInfo 等级的日志
func Info(ctx context.Context, args ...any) {
	globalLogger.AddCallerSkip(1).Info(ctx, args...)
}

// Warn 输出 LevelWarn 等级的日志
func Warn(ctx context.Context, args ...any) {
	globalLogger.AddCallerSkip(1).Warn(ctx, args...)
}

// Error 输出 LevelError 等级的日志
func Error(ctx context.Context, args ...any) {
	globalLogger.AddCallerSkip(1).Error(ctx, args...)
}

// Fatal 输出 LevelFatal 等级的日志并调用 Logger.Exit
func Fatal(ctx context.Context, args ...any) {
	globalLogger.AddCallerSkip(1).Fatal(ctx, args...)
}

// Panic 输出 LevelPanic 等级的日志后执行 panic,
// 即使 Logger 日志等级高于 LevelPanic 也会 panic.
func Panic(ctx context.Context, args ...any) {
	globalLogger.AddCallerSkip(1).Panic(ctx, args...)
}

// Logf 格式化输出日志
func Logf(ctx context.Context, level Level, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Logf(ctx, level, format, args...)
}

// Tracef 格式化输出 LevelTrace 等级的日志
func Tracef(ctx context.Context, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Tracef(ctx, format, args...)
}

// Debugf 格式化输出 LevelDebug 等级的日志
func Debugf(ctx context.Context, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Debugf(ctx, format, args...)
}

// Infof 格式化输出 LevelInfo 等级的日志
func Infof(ctx context.Context, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Infof(ctx, format, args...)
}

// Warnf 格式化输出 LevelWarn 等级的日志
func Warnf(ctx context.Context, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Warnf(ctx, format, args...)
}

// Errorf 格式化输出 LevelError 等级的日志
func Errorf(ctx context.Context, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Errorf(ctx, format, args...)
}

// Fatalf 格式化输出 LevelFatal 等级的日志并调用 Logger.Exit
func Fatalf(ctx context.Context, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Fatalf(ctx, format, args...)
}

// Panicf 格式化输出 LevelPanic 等级的日志
func Panicf(ctx context.Context, format string, args ...any) {
	globalLogger.AddCallerSkip(1).Panicf(ctx, format, args...)
}

// Exit 调用全局 logger 的 Exit
func Exit(code int) {
	globalLogger.Exit(code)
}

// Logger 返回全局 logger, 通常用来在程序启动时对全局 logger 进行配置,
// 业务代码处理日志时直接使用这个包里定义的日志函数.
func Logger() *logsdk.Logger {
	return globalLogger
}