modules

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 18, 2026 License: MIT Imports: 14 Imported by: 0

README

modules

modules 子系统已完成去历史化，当前仅保留可维护的核心能力。

当前稳定能力

  • formatter：属性格式化链
  • multi：Fanout 多路分发
  • output/net：通用 TCP/UDP 输出（codec 可扩展）
  • syslog：CEE 前缀输出（codec 可扩展）
  • webhook：HTTP 输出（codec + transport）

注册与使用

模块统一通过 modules.RegisterFactory 注册，通过 modules.CreateModule 创建，最终通过：

logger := slog.Default().Use(module)

设计约束

  • 不再保留旧 Converter 兼容路径
  • 不再保留反射式 formatter 适配分支
  • 新扩展统一走强类型接口与可测试的最小抽象

Async 执行器配置

模块内的 RunAsync 使用有界队列 + worker 池，默认配置为：

  • WorkerCount=4
  • QueueSize=256

可在运行时调整：

modules.SetAsyncExecutorOptions(modules.AsyncExecutorOptions{
    WorkerCount: 8,
    QueueSize:   1024,
})

读取当前配置：

opts := modules.GetAsyncExecutorOptions()

队列满时采用 non-blocking 丢弃策略，不阻塞日志主链路。

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultAttrFromContext added in v0.2.0 

func DefaultAttrFromContext(fns []func(ctx context.Context) []slog.Attr) []func(ctx context.Context) []slog.Attr

DefaultAttrFromContext 规范化上下文属性提取函数列表。

func DefaultTimeout added in v0.2.0 

func DefaultTimeout(timeout, fallback time.Duration) time.Duration

DefaultTimeout 返回默认超时时间。

func EnableAsyncErrorLogging added in v0.2.0 

func EnableAsyncErrorLogging(enabled bool)

EnableAsyncErrorLogging 开关模块异步任务错误日志输出。

func Frame added in v0.1.3 

func Frame(pc uintptr) runtime.Frame

Frame 获取调用帧。

func RegisterFactory 

func RegisterFactory(name string, factory ModuleFactory) error

RegisterFactory 全局注册工厂

func RegisterModule 

func RegisterModule(module Module) error

RegisterModule 全局注册模块

func ReportAsyncError added in v0.2.0 

func ReportAsyncError(component string, err error)

ReportAsyncError 统一上报模块中的异步任务错误。

func RunAsync added in v0.2.0 

func RunAsync(component string, task func() error)

RunAsync 统一执行模块异步任务并处理 panic/error 上报。

func SetAsyncErrorWriter added in v0.2.0 

func SetAsyncErrorWriter(w io.Writer)

SetAsyncErrorWriter 设置模块异步任务错误输出目标；传入 nil 会恢复为 stderr。

func SetAsyncExecutorOptions added in v0.2.0 

func SetAsyncExecutorOptions(options AsyncExecutorOptions)

SetAsyncExecutorOptions updates async executor workers/queue at runtime. Existing queued tasks are drained by old workers before old executor exits.

func SourceLabel added in v0.1.3 

func SourceLabel(f runtime.Frame) string

SourceLabel 将 frame 转为短路径标签。

func UpdateModuleConfig added in v0.1.2 

func UpdateModuleConfig(name string, config Config) error

UpdateModuleConfig 重新配置现有模块

Types

type AsyncExecutorOptions added in v0.2.0 

type AsyncExecutorOptions struct {
	WorkerCount int
	QueueSize   int
}

AsyncExecutorOptions controls module async task execution behavior. Values <= 0 fallback to built-in defaults.

func GetAsyncExecutorOptions added in v0.2.0 

func GetAsyncExecutorOptions() AsyncExecutorOptions

GetAsyncExecutorOptions returns current async executor settings.

type BaseModule 

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

BaseModule 基础模块实现

func NewBaseModule 

func NewBaseModule(name string, typ ModuleType, priority int) *BaseModule

NewBaseModule 创建基础模块

func (*BaseModule) Configure 

func (m *BaseModule) Configure(config Config) error

func (*BaseModule) Enabled 

func (m *BaseModule) Enabled() bool

func (*BaseModule) Handler 

func (m *BaseModule) Handler() slog.Handler

func (*BaseModule) Name 

func (m *BaseModule) Name() string

func (*BaseModule) Priority 

func (m *BaseModule) Priority() int

func (*BaseModule) SetEnabled 

func (m *BaseModule) SetEnabled(enabled bool)

func (*BaseModule) SetHandler 

func (m *BaseModule) SetHandler(handler slog.Handler)

func (*BaseModule) Type 

func (m *BaseModule) Type() ModuleType

type Config 

type Config map[string]any

Config 通用配置接口

func (Config) Bind added in v0.1.1 

func (c Config) Bind(target any) error

Bind 将通用 Config 映射到强类型结构体或其他合法的 JSON 目标对象。

它通过标准库的 JSON 编解码器完成类型转换，避免在业务代码中散布显式的类型断言。 使用示例： 

var opts struct {
    Endpoint string        `json:"endpoint"`
    Timeout  time.Duration `json:"timeout"`
}
if err := cfg.Bind(&opts); err != nil { ... }

任何实现了 json.Unmarshaler / encoding.TextUnmarshaler 的类型，都会被透明支持。

type Configurable 

type Configurable interface {
	Configure(config Config) error
}

Configurable 可配置接口 - 只负责配置管理。 与 Module.Configure 保持一致。

type Enableable 

type Enableable interface {
	Enabled() bool
	Enable()
	Disable()
}

Enableable 可启用接口 - 只负责启用状态管理。 与 Module.Enabled 保持一致，并补充开关能力。

type FormatterProvider added in v0.1.2 

type FormatterProvider interface {
	FormatterFunctions() []func([]string, slog.Attr) (slog.Value, bool)
}

FormatterProvider 提供格式化函数，避免使用反射适配。

type HandlerProvider 

type HandlerProvider interface {
	Handler() slog.Handler
	SetHandler(handler slog.Handler)
}

HandlerProvider 处理器提供者接口 - 只负责提供 slog.Handler。 与 Module.Handler 保持一致，并补充动态替换能力。

type Healthable 

type Healthable interface {
	HealthCheck() error
	IsHealthy() bool
}

Healthable 健康检查接口 - 用于诊断聚合。

type Measurable 

type Measurable interface {
	GetMetrics() map[string]interface{}
	ResetMetrics()
}

Measurable 可度量接口 - 用于诊断聚合。

type Module 

type Module interface {
	// Name 返回模块名称
	Name() string
	// Type 返回模块类型
	Type() ModuleType
	// Configure 配置模块
	Configure(config Config) error
	// Handler 返回slog处理器
	Handler() slog.Handler
	// Priority 返回优先级，数字越小优先级越高
	Priority() int
	// Enabled 返回模块是否启用
	Enabled() bool
}

Module 定义模块接口。

func CreateModule 

func CreateModule(name string, config Config) (Module, error)

CreateModule 全局创建模块

func GetModule 

func GetModule(name string) (Module, bool)

GetModule 全局获取模块

func NewHandlerModule added in v0.1.3 

func NewHandlerModule(name string, handler slog.Handler) Module

NewHandlerModule 便捷创建处理器模块，默认优先级 100。

type ModuleConfig 

type ModuleConfig struct {
	Type     string `json:"type"`
	Name     string `json:"name"`
	Enabled  bool   `json:"enabled"`
	Priority int    `json:"priority"`
	Config   Config `json:"config"`
}

ModuleConfig 模块配置

type ModuleFactory 

type ModuleFactory func(config Config) (Module, error)

ModuleFactory 模块工厂函数

type ModuleType 

type ModuleType int

ModuleType 定义模块类型 

const (
	TypeFormatter ModuleType = iota // 格式化器
	TypeHandler                     // 处理器
	TypeSink                        // 日志接收器
)

func (ModuleType) String 

func (mt ModuleType) String() string

type Named 

type Named interface {
	Name() string
}

Named 命名接口 - 只负责提供名称。 与 Module.Name 保持一致。

type Registry 

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

Registry 模块注册中心

func GetRegistry 

func GetRegistry() *Registry

GetRegistry 获取全局注册中心

func NewRegistry 

func NewRegistry() *Registry

NewRegistry 创建新的注册中心

func (*Registry) Create 

func (r *Registry) Create(name string, config Config) (Module, error)

Create 通过工厂创建模块

func (*Registry) Get 

func (r *Registry) Get(name string) (Module, bool)

Get 获取模块

func (*Registry) GetByType 

func (r *Registry) GetByType(moduleType ModuleType) []Module

GetByType 按类型获取模块列表

func (*Registry) List 

func (r *Registry) List() []Module

List 列出所有模块

func (*Registry) ListFactories 

func (r *Registry) ListFactories() []string

ListFactories 列出所有已注册的工厂名称

func (*Registry) Register 

func (r *Registry) Register(module Module) error

Register 注册模块实例

func (*Registry) RegisterFactory 

func (r *Registry) RegisterFactory(name string, factory ModuleFactory) error

RegisterFactory 注册模块工厂

func (*Registry) Remove 

func (r *Registry) Remove(name string) error

Remove 移除模块

func (*Registry) Update added in v0.1.2 

func (r *Registry) Update(name string, config Config) error

Update 重新配置已注册模块

type Typed 

type Typed interface {
	Type() ModuleType
}

Typed 类型接口 - 只负责提供类型信息。 与 Module.Type 保持一致。

type WriteSyncer added in v0.1.3 

type WriteSyncer interface {
	io.Writer
}

WriteSyncer 兼容 io.Writer，用于输出 handler。

func NewStdWriter added in v0.1.3 

func NewStdWriter() WriteSyncer

NewStdWriter 返回标准输出 writer。

Source Files

View all Source files

Directories

Path Synopsis
output
gelf
logfmt
net

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.