processor

package
v1.21.0 Latest Latest
Warning

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

 Go to latest Published: Jul 13, 2026 License: MIT Imports: 14 Imported by: 2

Documentation

Overview

Package processor provides the building blocks to create processors, which are used to process messages before they are printed. It also provides a collection of built-in processors.

NOTES: - Processors are executed in the order they are added to the pipeline. - It's the implementator's responsibility to check if the message has content. Sypl doesn't touch the message's content - it pass thru as it's, raw - as any logger. Only processors are able to change the message's content. Use the `IsEmpty` help method to check if the message has content.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewProcessingError 

func NewProcessingError(m message.IMessage, e error) error

NewProcessingError returns a new `ProcessingError`.

Types

type Casing 

type Casing string

Casing definition, e.g.: Upper, Lower, Title, etc. 

const (
	// Lowercase casing.
	Lowercase Casing = "lowercase"

	// Uppercase casing.
	Uppercase Casing = "uppercase"
)

type DedupOption added in v1.21.0 

type DedupOption func(*dedupConfig)

DedupOption allows to specify optional `Dedup` configuration.

func DedupWithCounter added in v1.21.0 

func DedupWithCounter(counter func(key string, suppressed uint64)) DedupOption

DedupWithCounter sets a suppression-count callback, invoked when a key re-passes after the window, with the number of messages suppressed meanwhile. It's only invoked if at least one message was suppressed.

Notes:

  • The callback runs synchronously, on the logging goroutine that re-passed the key - keep it fast.
  • It runs outside the deduper's lock, so it may safely log - even through the same pipeline.
  • Suppressions of a key that never re-passes are never reported.

func DedupWithKeyFn added in v1.21.0 

func DedupWithKeyFn(keyFn func(m message.IMessage) string) DedupOption

DedupWithKeyFn sets the deduplication key function. Defaults to the message's content-based hash ID - `GetContentBasedHashID` - which is level-agnostic. Use a custom key function to, for example, include the level.

type IProcessor 

type IProcessor interface {
	meta.IMeta

	// String interface.
	String() string

	// Run the processor, if enabled.
	Run(m message.IMessage) error
}

IProcessor specifies what a processor does.

func ChangeFirstCharCase 

func ChangeFirstCharCase(casing Casing) IProcessor

ChangeFirstCharCase changes message content's first char to the specified case.

Notes: - `casing` because `case` is a reserved word. - Order matters! If this comes after another processor like the Prefixer, it will change the case of the first char of the Prefix mask, not the message content!

func ColorizeBasedOnLevel 

func ColorizeBasedOnLevel(levelColorMap map[level.Level]color.Color) IProcessor

ColorizeBasedOnLevel colorize messages based on the specified levels.

func ColorizeBasedOnWord 

func ColorizeBasedOnWord(wordColorMap map[string]color.Color) IProcessor

ColorizeBasedOnWord colorize a messages with the specified colors if a message contains a specific word.

func Decolourizer 

func Decolourizer() IProcessor

Decolourizer removes any colour.

func Dedup added in v1.21.0 

func Dedup(window time.Duration, opts ...DedupOption) IProcessor

Dedup is a "log once per window" processor: it mutes - `flag.Mute` - messages whose key was already logged within the window. When the window elapses, the key logs again.

Notes:

  • `window <= 0` means a single infinite window: duplicates are muted forever.
  • The default key is the message's content-based hash ID. See `DedupWithKeyFn`, and `DedupWithCounter` for options.
  • State is per-instance: attach a given instance to exactly ONE output - messages are copied, and processed per output, so a shared instance would count each logical message once per output. Create one instance per output instead.
  • The internal key map is bounded (`dedupMaxKeys`). On overflow, ALL entries are evicted - evicted keys log again, so a few extra messages may pass. This is the documented, safe failure mode.

func ErrorSimulator 

func ErrorSimulator(msg string) IProcessor

ErrorSimulator simulates an error in the pipeline.

func Flagger added in v1.9.10 

func Flagger(f flag.Flag) IProcessor

Flagger flags a message.

func ForceBasedOnLevel 

func ForceBasedOnLevel(levels ...level.Level) IProcessor

ForceBasedOnLevel force messages to be printed based on the specified levels.

func MuteBasedOnLevel 

func MuteBasedOnLevel(levels ...level.Level) IProcessor

MuteBasedOnLevel mute messages based on the specified levels.

func New 

func New(name string, f RunFunc) IProcessor

New is the Processor factory.

func PrefixBasedOnMask 

func PrefixBasedOnMask(timestampFormat string) IProcessor

PrefixBasedOnMask prefixes messages with the predefined mask.

Example: 2021-06-22 12:51:46.089 [80819] [CLI] [Info].

func PrefixBasedOnMaskExceptForLevels 

func PrefixBasedOnMaskExceptForLevels(timestampFormat string, levels ...level.Level) IProcessor

PrefixBasedOnMaskExceptForLevels is a specialized version of the `PrefixBasedOnMask`. It prefixes all messages, except for the specified levels.

func Prefixer 

func Prefixer(prefix string) IProcessor

Prefixer prefixes a message with the specified `prefix`.

func PrintOnlyAtLevel 

func PrintOnlyAtLevel(levels ...level.Level) IProcessor

PrintOnlyAtLevel prints only if message is at the specified level.

func PrintOnlyIfNotTaggedWith added in v1.6.6 

func PrintOnlyIfNotTaggedWith(tags ...string) IProcessor

PrintOnlyIfNotTaggedWith prints only if message contains the specified tag.

func PrintOnlyIfTagged 

func PrintOnlyIfTagged(tag string) IProcessor

PrintOnlyIfTagged prints only if message contains the specified tag.

func RateLimit added in v1.21.0 

func RateLimit(maxPerWindow uint64, window time.Duration, opts ...RateLimitOption) IProcessor

RateLimit is a global - NOT per-key - token-window limiting processor. Within each window, the first `maxPerWindow` messages pass - the rest is muted (`flag.Mute`). When the window elapses, counting restarts.

Notes:

  • `window <= 0` means a single infinite window: only the first `maxPerWindow` messages EVER pass.
  • `maxPerWindow = 0` mutes everything.
  • State is per-instance: attach a given instance to exactly ONE output - messages are copied, and processed per output, so a shared instance would count each logical message once per output. Create one instance per output instead.
  • See `RateLimitWithCallback` for muted-message reporting.

func Sample added in v1.21.0 

func Sample(cfg SampleConfig) IProcessor

Sample is a zap-style sampling processor. Per key, within each window, the first `First` messages pass; afterwards, only every `Thereafter`-th message passes - the rest is muted (`flag.Mute`). See `SampleConfig` for defaults, and edge cases.

Notes:

  • State is per-instance: attach a given instance to exactly ONE output - messages are copied, and processed per output, so a shared instance would count each logical message once per output. Create one instance per output instead.
  • The internal key map is bounded (`sampleMaxKeys`). On overflow, ALL entries are evicted - counting restarts, so a few extra messages may pass. This is the documented, safe failure mode.

func Suffixer 

func Suffixer(suffix string) IProcessor

Suffixer suffixes a message with the specified `suffix`.

func Tagger added in v1.9.2 

func Tagger(tag ...string) IProcessor

Tagger tags a message with the specified `tags`.

type ProcessingError 

type ProcessingError struct {
	// Cause is the underlying case of the failure.
	Cause error

	// Message when the failured happened.
	Message message.IMessage

	// OutputName is the name of the output in-use.
	OutputName string

	// ProcessorName is the name of the processor in-use.
	ProcessorName string
}

ProcessingError is thrown when a processor fails.

func (*ProcessingError) Error 

func (p *ProcessingError) Error() string

Error interface implementation.

type RateLimitOption added in v1.21.0 

type RateLimitOption func(*rateLimitConfig)

RateLimitOption allows to specify optional `RateLimit` configuration.

func RateLimitWithCallback added in v1.21.0 

func RateLimitWithCallback(callback func(dropped uint64)) RateLimitOption

RateLimitWithCallback sets an overflow callback, invoked at window rollover with the number of messages muted in the elapsed window. It's only invoked if at least one message was muted.

Notes:

  • The callback runs synchronously, on the logging goroutine that triggered the rollover - keep it fast.
  • It runs outside the limiter's lock, so it may safely log - even through the same pipeline.
  • Messages muted in the FINAL window are never reported - reporting only happens at rollover.

type RunFunc 

type RunFunc func(m message.IMessage) error

RunFunc specifies the function used to process a message.

type SampleConfig added in v1.21.0 

type SampleConfig struct {
	// First is the number of messages, per key, that always pass within a
	// window.
	First uint64

	// Thereafter, after the first `First` messages, only every
	// `Thereafter`-th message passes - the rest is muted. `0` drops all
	// messages after `First`.
	Thereafter uint64

	// Window is the sampling window. Counters reset when it elapses. `<= 0`
	// means a single infinite window - counters never reset.
	Window time.Duration

	// KeyFn derives the sampling key from a message. Defaults to level +
	// processed content.
	KeyFn func(m message.IMessage) string
	// contains filtered or unexported fields
}

SampleConfig configures the `Sample` processor.

Source Files

View all Source files

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.
⌂ 换网址