Documentation
¶
Index ¶
- Variables
- func Close() error
- func FromContext(ctx context.Context) *zap.Logger
- func GetWriteSyncer2(filename string) io.Writer
- func GologHandler(component string) golog.Handler
- func GologWriter(component string) io.Writer
- func Init() error
- func NewGormLogger(config GormLoggerConfig) gormlogger.Interface
- func RequestIDFromContext(ctx context.Context) string
- func SetLevel(level string) error
- func Sync() error
- func WithComponent(component string) *zap.SugaredLogger
- func WithRequestID(ctx context.Context, requestID string) context.Context
- type GormLoggerConfig
- type Zap
Constants ¶
This section is empty.
Variables ¶
var ( // Logger 是脚手架全局结构化 Logger；Init 前使用无输出实现避免 nil panic。 Logger = zap.NewNop() // SugaredLogger 是兼容现有 printf 风格调用的全局 Logger。 SugaredLogger = Logger.Sugar() )
var CONFIG = Zap{ Level: "debug", Format: "console", Prefix: "[go-blackbox]", Director: ".", LinkName: "latest_log", ShowLine: true, EncodeLevel: "LowercaseColorLevelEncoder", StacktraceKey: "stacktrace", LogInConsole: true, MaxAge: 7 * 24, WithRotationTime: 24, }
CONFIG 保存兼容旧调用方的全局日志配置。 应用应在启动阶段单线程修改配置，并在 Init 成功后停止写入该变量。
Functions ¶
func Close ¶
func Close() error
Close 刷新日志缓冲区并关闭全部轮转日志文件，释放底层文件句柄。 该函数幂等；关闭后再次调用 Init 会创建新的写入器。多个关闭错误会聚合返回。
func FromContext ¶
FromContext 返回附加 request_id 字段的结构化 Logger。 context 中不存在 request_id 时返回全局 Logger，保证日志调用方无需判空。
func GetWriteSyncer2 ¶
GetWriteSyncer2 保留旧版直接获取 io.Writer 的公开入口。 Deprecated: 新代码应由 Init 统一创建日志核心并处理初始化错误。
func GologHandler ¶ added in v1.48.0
GologHandler 把 Iris(kataras/golog)日志统一接入 gbx zap 体系。 参考 golog 的 Log 结构设计:Message 为 zap message,Fields 键值对展开为 zap 字段,Stacktrace[0] 作为调用点 caller,级别按 golog→zap 映射。 用法:app.Logger().Handle(zaplog.GologHandler("iris"))
func GologWriter ¶ added in v1.48.0
GologWriter 返回 io.Writer 适配器,把 golog Printer 直写输出(如 iris 路由表、 监听地址)收编进 zap(info 级,component 标识来源)。每行一条,自动剥离 ANSI 颜色码。 用法:app.Logger().SetOutput(zaplog.GologWriter("iris")) 注意:iris 的路由表有意绕过 golog handler 直写 Printer(源码注释明确), 只有 SetOutput 能拦截;Handler 负责结构化日志,Writer 负责 Printer 兜底,不双写。
func Init ¶
func Init() error
Init 根据 CONFIG 创建完整日志目录和严格单级文件 Logger。 初始化失败时保留现有 Logger，不会注册半初始化日志实例。
func NewGormLogger ¶ added in v1.48.0
func NewGormLogger(config GormLoggerConfig) gormlogger.Interface
NewGormLogger 创建接入 gbx zap 体系的 GORM 日志器。 SQL 详情按级别分流:Info(SQL+参数+行数+耗时,开发期)、 Warn(慢查询)、Error(SQL 错误),字段结构化(sql/rows/elapsed/component)。
func RequestIDFromContext ¶
RequestIDFromContext 从 context 读取 request_id；不存在时返回空字符串。
func Sync ¶
func Sync() error
Sync 刷新全局 Logger 的缓冲区。 macOS 和终端标准输出不支持 fsync 时产生的 EINVAL、ENOTTY 会被安全忽略。
func WithComponent ¶
func WithComponent(component string) *zap.SugaredLogger
WithComponent 返回携带 component 字段的 SugaredLogger。 component 为空时使用 unknown，确保日志始终可以按功能模块筛选。
Types ¶
type GormLoggerConfig ¶ added in v1.48.0
type GormLoggerConfig struct {
// SlowThreshold 超过该耗时的查询按 Warn 输出(慢查询告警),默认 200ms。
SlowThreshold time.Duration
// LogLevel 过滤最低级别,默认 Warn(生产只留慢查询与错误)。
LogLevel gormlogger.LogLevel
// IgnoreRecordNotFoundError 忽略 ErrRecordNotFound(常见于 First 探测查询)。
IgnoreRecordNotFoundError bool
// ParameterizedQueries 以 $1 占位符隐藏 SQL 参数值。
ParameterizedQueries bool
}
GormLoggerConfig 定义 GORM SQL 日志接入 zap 的策略。 配置理念吸收 gorm 官方 logger.Config: SlowThreshold 慢查询阈值、IgnoreRecordNotFoundError 忽略未找到记录、 ParameterizedQueries 参数化 SQL(防敏感数据进日志)。
func DefaultGormLoggerConfig ¶ added in v1.48.0
func DefaultGormLoggerConfig() GormLoggerConfig
DefaultGormLoggerConfig 返回生产友好的 GORM 日志默认配置。
type Zap ¶
type Zap struct {
// Level 是允许输出的最低日志级别。
Level string `mapstructure:"level" json:"level" yaml:"level"`
// Format 支持 console 和 json。
Format string `mapstructure:"format" json:"format" yaml:"format"`
// Prefix 是兼容旧配置的应用标识，初始化后会规范化为结构化 service 字段。
Prefix string `mapstructure:"prefix" json:"prefix" yaml:"prefix"`
// Director 是日志根目录，等级文件写入其 zap 子目录。
Director string `mapstructure:"director" json:"director" yaml:"director"`
// LinkName 为旧版配置字段保留；新版每个等级使用独立软链接名称。
LinkName string `mapstructure:"link-name" json:"link-name" yaml:"link-name"`
// ShowLine 控制是否记录调用文件和行号。
ShowLine bool `mapstructure:"show-line" json:"show-line" yaml:"show-line"`
// EncodeLevel 为旧版编码器名称保留。
EncodeLevel string `mapstructure:"encode-level" json:"encode-level" yaml:"encode-level"`
// StacktraceKey 是堆栈字段名称。
StacktraceKey string `mapstructure:"stacktrace-key" json:"stacktrace-key" yaml:"stacktrace-key"`
// LogInConsole 控制是否同时输出到标准输出。
LogInConsole bool `mapstructure:"log-in-console" json:"log-in-console" yaml:"log-in-console"`
// MaxAge 是轮转日志最大保留小时数。
MaxAge int `mapstructure:"max-age" json:"max-age" yaml:"max-age"`
// WithRotationTime 是日志文件轮转间隔小时数。
WithRotationTime int `mapstructure:"rotation-time" json:"rotation-time" yaml:"rotation-time"`
}
Zap 定义日志编码、输出目录和文件轮转策略。
Source Files