github.com/qioalice/ekago/v3@v3.3.2-0.20221202205325-5c262d586ee4/ekalog/integrator.go (about)

     1  // Copyright © 2018-2021. All rights reserved.
     2  // Author: Ilya Stroy.
     3  // Contacts: iyuryevich@pm.me, https://github.com/qioalice
     4  // License: https://opensource.org/licenses/MIT
     5  
     6  package ekalog
     7  
     8  import (
     9  	"github.com/qioalice/ekago/v3/internal/ekaletter"
    10  )
    11  
    12  // Integrator is the way, an Entry must be encoded how and written to.
    13  //
    14  // It also allows to drop an Entry at the earlier steps if it's Level less than
    15  // level is returned by MinLevelEnabled().
    16  //
    17  // Main two methods are PreEncodeField() that allows to encode some fields once
    18  // and then use them for each Entry.
    19  type Integrator interface {
    20  
    21  	// PreEncodeField allows to encode ekaletter.LetterField once
    22  	// and then use them for each Entry.
    23  	// Using this method you will spent less resources at the ekaletter.LetterField's
    24  	// encoding, doing it only once for each that field.
    25  	PreEncodeField(f ekaletter.LetterField)
    26  
    27  	// EncodeAndWrite encodes Entry and then writes to some destination
    28  	// (integrator determines what and how it will be).
    29  	//
    30  	// Thus, EncodeAndWrite does the main thing of Integrator:
    31  	// "Integrates your log messages with your log destination service".
    32  	//
    33  	// WARNING.
    34  	// Integrator MUST NOT to hold an Entry or its parts after this method is done.
    35  	// The Logger will return Entry to its pool after this method is complete,
    36  	// so accessing to it or its parts is unsafe and WILL lead to UB.
    37  	EncodeAndWrite(entry *Entry)
    38  
    39  	// MinLevelEnabled returns minimum Level an integrator will handle Entry with.
    40  	// E.g. if minimum level is LEVEL_WARNING, LEVEL_DEBUG logs will be dropped
    41  	// at the most earlier moment - even before parsing.
    42  	MinLevelEnabled() Level
    43  
    44  	// MinLevelForStackTrace must return a minimum level starting with a stacktrace
    45  	// must be generated and added to the Logger's Entry only if it's not presented
    46  	// yet by attached ekaerr.Error object.
    47  	MinLevelForStackTrace() Level
    48  
    49  	// Sync flushes all pending log entries to integrator destination.
    50  	// It useful when integrator does async work and sometimes you need to make sure
    51  	// all pending entries are flushed.
    52  	//
    53  	// Logger type has the same name's method that just calls this method.
    54  	Sync() error
    55  }