logging

type AsyncConfig ¶

type AsyncConfig struct {
	Enabled  bool
	Queue    int
	MaxBytes int64
}

AsyncConfig enables one owned writer per sink. Records are copied into a bounded queue; a full queue drops the newest record and counts it rather than blocking the logging caller. Close drains every accepted record. Zero limits select 1,024 records and 4 MiB of pending record bytes.

func (c AsyncConfig) Validate() error

type ChannelName ¶

type ChannelName string

ChannelName selects an instance, distinct from names of other service families.

func (n ChannelName) Validate() error

type ChannelOption ¶

type ChannelOption func(*channelOptions) error

ChannelOption supplies typed Go values for configured channels.

func WithHandler(name ChannelName, handler slog.Handler) ChannelOption

type ChannelSet ¶

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

ChannelSet owns configured sinks, never a borrowed default logger. Prepare is pure; Start acquires files and Close releases them after all borrowers drain. Copying the handle keeps one lifetime owner.

func PrepareChannels(selected ChannelName, settings map[ChannelName]ChannelSettings, borrowedDefault *slog.Logger, options ...ChannelOption) (*ChannelSet, error)

func (s *ChannelSet) Channels() *Channels

func (s *ChannelSet) Close() error

func (s *ChannelSet) FileSink(name ChannelName) (*Sink, error)

func (ChannelSet) Format(s fmt.State, _ rune)

func (ChannelSet) LogValue() slog.Value

func (s *ChannelSet) Start(ctx context.Context) error

func (s *ChannelSet) Stats() []ChannelStats

type ChannelSettings ¶

type ChannelSettings struct {
	Sink  SinkConfig
	Stack []ChannelName `config:",json"`
}

ChannelSettings composes existing JSON sinks. Stack children are named channels; repeated leaves are written once per record, in declaration order.

func DefaultChannelSettings() ChannelSettings

func (s ChannelSettings) Validate() error

type ChannelSettingsConfigKeySet ¶

type ChannelSettingsConfigKeySet struct {
	Sink ChannelSettingsSinkConfigKeySet
	// Stack selects stack. Set accepts []ChannelName.
	Stack config.Key[ChannelSettings, []ChannelName]
}

ChannelSettingsConfigKeySet exposes compiler-checked configuration overrides.

func ChannelSettingsConfigKeys() ChannelSettingsConfigKeySet

type ChannelSettingsSinkAsyncConfigKeySet ¶

type ChannelSettingsSinkAsyncConfigKeySet struct {
	// Enabled selects sink.async.enabled. Set accepts bool.
	Enabled config.Key[ChannelSettings, bool]
	// Queue selects sink.async.queue. Set accepts int.
	Queue config.Key[ChannelSettings, int]
	// MaxBytes selects sink.async.max_bytes. Set accepts int64.
	MaxBytes config.Key[ChannelSettings, int64]
}

ChannelSettingsSinkAsyncConfigKeySet exposes compiler-checked configuration overrides.

type ChannelSettingsSinkConfigKeySet ¶

type ChannelSettingsSinkConfigKeySet struct {
	// Driver selects sink.driver. Set accepts SinkDriver.
	Driver config.Key[ChannelSettings, SinkDriver]
	// Path selects sink.path. Set accepts string.
	Path config.Key[ChannelSettings, string]
	// Level selects sink.level. Set accepts slog.Level.
	Level config.Key[ChannelSettings, slog.Level]
	// AddSource selects sink.add_source. Set accepts bool.
	AddSource config.Key[ChannelSettings, bool]
	Rotation  ChannelSettingsSinkRotationConfigKeySet
	// TimeZone selects sink.time_zone. Set accepts temporal.ZoneName.
	//
	// TimeZone controls timestamps and daily rotation; empty means UTC for direct
	// sinks and inherits the application timezone during configured assembly.
	//
	TimeZone config.Key[ChannelSettings, temporal.ZoneName]
	//
	// Async optionally moves destination writes to one owned bounded writer.
	//
	Async ChannelSettingsSinkAsyncConfigKeySet
	//
	// Syslog selects the daemon used by the syslog driver.
	//
	Syslog ChannelSettingsSinkSyslogConfigKeySet
}

ChannelSettingsSinkConfigKeySet exposes compiler-checked configuration overrides.

type ChannelSettingsSinkRotationConfigKeySet ¶

type ChannelSettingsSinkRotationConfigKeySet struct {
	// MaxBytes selects sink.rotation.max_bytes. Set accepts int64.
	MaxBytes config.Key[ChannelSettings, int64]
	// MaxFiles selects sink.rotation.max_files. Set accepts int.
	MaxFiles config.Key[ChannelSettings, int]
	// MaxAge selects sink.rotation.max_age. Set accepts time.Duration.
	MaxAge config.Key[ChannelSettings, time.Duration]
	// Disabled selects sink.rotation.disabled. Set accepts bool.
	Disabled config.Key[ChannelSettings, bool]
}

ChannelSettingsSinkRotationConfigKeySet exposes compiler-checked configuration overrides.

type ChannelSettingsSinkSyslogConfigKeySet ¶

type ChannelSettingsSinkSyslogConfigKeySet struct {
	// Network selects sink.syslog.network. Set accepts string.
	Network config.Key[ChannelSettings, string]
	// Address selects sink.syslog.address. Set accepts string.
	Address config.Key[ChannelSettings, string]
	// Tag selects sink.syslog.tag. Set accepts string.
	Tag config.Key[ChannelSettings, string]
	// Facility selects sink.syslog.facility. Set accepts SyslogFacility.
	Facility config.Key[ChannelSettings, SyslogFacility]
}

ChannelSettingsSinkSyslogConfigKeySet exposes compiler-checked configuration overrides.

type ChannelStats ¶

type ChannelStats struct {
	Channel ChannelName `json:"channel"`
	Sink    SinkStats   `json:"sink"`
}

ChannelStats reports one owned leaf channel. Stacks report through their leaves; a borrowed default logger belongs to its owner and is not reported.

type Channels ¶

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

Channels is immutable; default and named selection alias the same instance.

func NewChannels(selected ChannelName, entries ...NamedChannel) (*Channels, error)

func (r *Channels) Channel(name ChannelName) (*slog.Logger, error)

func (r *Channels) Default() (*slog.Logger, error)

func (r *Channels) DefaultName() ChannelName

func (r *Channels) Names() []ChannelName

type ContextFields ¶

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

ContextFields is an owned, serializable snapshot of request-scoped log fields for crossing an asynchronous boundary, such as a job payload or an outbox record. It stores only its bounded JSON object text, so it is a concrete value accepted by job payload validation. Durations and times serialize as text and decode as strings; integers and floats decode as numbers. Decoding reapplies every bound and redaction rule of WithAttrs. The zero value carries no fields.

func FieldsFromContext(ctx context.Context) ContextFields

func (f ContextFields) Attrs() []slog.Attr

func (f ContextFields) Context(ctx context.Context) context.Context

func (f ContextFields) IsZero() bool

func (f ContextFields) MarshalJSON() ([]byte, error)

func (f *ContextFields) UnmarshalJSON(data []byte) error

type FileChunk ¶

type FileChunk struct {
	File         FileInfo
	Data         []byte
	Offset, Next int64
	More         bool
}

type FileID ¶

type FileID string

FileID identifies one owned log generation. It is not a filesystem path.

type FileInfo ¶

type FileInfo struct {
	ID       FileID    `json:"id"`
	Name     string    `json:"name"`
	Active   bool      `json:"active"`
	Bytes    int64     `json:"bytes"`
	Modified time.Time `json:"modified"`
}

FileInfo never exposes an absolute server path. IDs expire on owner restart; an active ID also expires on clear or rotation.

type FileRead ¶

type FileRead struct {
	ID     FileID
	Offset int64
	Limit  int
}

FileRead bounds one byte-range read. Offset -1 requests the newest bytes. Consumers parse complete lines and use Next to continue; a range can end in the middle of a record. Data is owned by the caller and must be treated as text.

type NamedChannel ¶

type NamedChannel struct {
	Name  ChannelName
	Value *slog.Logger
}

NamedChannel borrows one existing instance. Selection never creates another owner.

type Options ¶

type Options struct {
	Level     slog.Leveler
	AddSource bool
	// Location selects log timestamps. Nil means UTC. The value is snapshotted.
	Location *time.Location
}

Options configures the standard JSON handler.

type RotationConfig ¶

type RotationConfig struct {
	MaxBytes int64
	MaxFiles int
	MaxAge   time.Duration
	Disabled bool
}

RotationConfig controls file sinks. A nonempty file rolls over before a write on a new day in the sink's timezone or when that write would exceed MaxBytes. Zero limits select defaults; Disabled explicitly opts into externally managed append-only files. MaxFiles counts archives, excluding the active file. Retention uses archive time.

func DefaultRotationConfig() RotationConfig

func (c RotationConfig) Validate() error

type Sink ¶

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

Sink is a prepared writer; it acquires its destination only in Start. Copying the handle retains one owner. It never closes process stdout/stderr.

func PrepareSink(c SinkConfig) (*Sink, error)

func (s *Sink) ClearFile(ctx context.Context, expected FileID) error

func (s *Sink) Close() error

func (s *Sink) DeleteArchive(ctx context.Context, id FileID) error

func (s *Sink) Files(ctx context.Context) (files []FileInfo, err error)

func (s *Sink) Logger() *slog.Logger

func (s *Sink) ReadFile(ctx context.Context, request FileRead) (chunk FileChunk, err error)

func (s *Sink) RotateFile(ctx context.Context, expected FileID) error

func (s *Sink) Start(ctx context.Context) error

func (s *Sink) Stats() SinkStats

func (s *Sink) Write(data []byte) (int, error)

type SinkConfig ¶

type SinkConfig struct {
	Driver    SinkDriver
	Path      string
	Level     slog.Level
	AddSource bool
	Rotation  RotationConfig
	// TimeZone controls timestamps and daily rotation; empty means UTC for direct
	// sinks and inherits the application timezone during configured assembly.
	TimeZone temporal.ZoneName
	// Async optionally moves destination writes to one owned bounded writer.
	Async AsyncConfig
	// Syslog selects the daemon used by the syslog driver.
	Syslog SyslogConfig
}

SinkConfig selects an application-owned JSON destination. File sinks append with automatic rotation/retention unless Rotation.Disabled is explicit.

func DefaultSinkConfig() SinkConfig

func (c SinkConfig) Validate() error

type SinkDriver ¶

type SinkDriver string

const (
	Stderr SinkDriver = "stderr"
	Stdout SinkDriver = "stdout"
	File   SinkDriver = "file"
	// Syslog writes each JSON record to a local or remote syslog daemon with a
	// severity derived from the record level. It is unavailable on Windows/Plan 9.
	Syslog SinkDriver = "syslog"
)

const Custom SinkDriver = "custom"

const Stack SinkDriver = "stack"

type SinkStats ¶

type SinkStats struct {
	Driver           SinkDriver `json:"driver"`
	Records          uint64     `json:"records"`
	Failures         uint64     `json:"failures"`
	Fallbacks        uint64     `json:"fallbacks"`
	Dropped          uint64     `json:"dropped"`
	Queued           int        `json:"queued"`
	RotationFailures uint64     `json:"rotation_failures"`
	PruneFailures    uint64     `json:"prune_failures"`
}

SinkStats is an owned snapshot of one destination's delivery counters. Records counts records the destination accepted. Failures counts rejected destination writes; each such record was either rewritten to stderr (Fallbacks) or lost (Dropped). Dropped also counts records refused by a full async queue. Queued is the current async backlog. Rotation and retention failures never drop a record; they are counted separately.

type SyslogConfig ¶

type SyslogConfig struct {
	Network  string
	Address  string
	Tag      string
	Facility SyslogFacility
}

SyslogConfig selects the daemon for the syslog driver. Network and Address are both empty for the platform's local daemon, or select "udp"/"tcp" with a host:port or "unix"/"unixgram" with an absolute socket path. Tag defaults to the process name; Facility defaults to user. Record severity follows the record level: debug, info, warning or err.

func (c SyslogConfig) Validate() error

type SyslogFacility ¶

type SyslogFacility string

SyslogFacility selects the syslog facility for a syslog sink.

const (
	FacilityUser   SyslogFacility = "user"
	FacilityDaemon SyslogFacility = "daemon"
	FacilityLocal0 SyslogFacility = "local0"
	FacilityLocal1 SyslogFacility = "local1"
	FacilityLocal2 SyslogFacility = "local2"
	FacilityLocal3 SyslogFacility = "local3"
	FacilityLocal4 SyslogFacility = "local4"
	FacilityLocal5 SyslogFacility = "local5"
	FacilityLocal6 SyslogFacility = "local6"
	FacilityLocal7 SyslogFacility = "local7"
)