From 94ad13c846a9e8a71b64d8560abc4643cd98a850 Mon Sep 17 00:00:00 2001 From: FuXiaoHei Date: Mon, 30 Dec 2013 23:32:57 +0800 Subject: [PATCH] add comments in logs package --- logs/conn.go | 9 +++++++++ logs/console.go | 7 +++++++ logs/file.go | 21 ++++++++++++++++++--- logs/log.go | 24 ++++++++++++++++++++++-- logs/smtp.go | 18 +++++++++++++++++- 5 files changed, 73 insertions(+), 6 deletions(-) diff --git a/logs/conn.go b/logs/conn.go index a5bc75c5..eed9ae2f 100644 --- a/logs/conn.go +++ b/logs/conn.go @@ -7,6 +7,8 @@ import ( "net" ) +// ConnWriter implements LoggerInterface. +// it writes messages in keep-live tcp connection. type ConnWriter struct { lg *log.Logger innerWriter io.WriteCloser @@ -17,12 +19,15 @@ type ConnWriter struct { Level int `json:"level"` } +// create new ConnWrite returning as LoggerInterface. func NewConn() LoggerInterface { conn := new(ConnWriter) conn.Level = LevelTrace return conn } +// init connection writer with json config. +// json config only need key "level". func (c *ConnWriter) Init(jsonconfig string) error { err := json.Unmarshal([]byte(jsonconfig), c) if err != nil { @@ -31,6 +36,8 @@ func (c *ConnWriter) Init(jsonconfig string) error { return nil } +// write message in connection. +// if connection is down, try to re-connect. func (c *ConnWriter) WriteMsg(msg string, level int) error { if level < c.Level { return nil @@ -49,10 +56,12 @@ func (c *ConnWriter) WriteMsg(msg string, level int) error { return nil } +// implementing method. empty. func (c *ConnWriter) Flush() { } +// destroy connection writer and close tcp listener. func (c *ConnWriter) Destroy() { if c.innerWriter == nil { return diff --git a/logs/console.go b/logs/console.go index 0c7fc1e9..c5fa2380 100644 --- a/logs/console.go +++ b/logs/console.go @@ -6,11 +6,13 @@ import ( "os" ) +// ConsoleWriter implements LoggerInterface and writes messages to terminal. type ConsoleWriter struct { lg *log.Logger Level int `json:"level"` } +// create ConsoleWriter returning as LoggerInterface. func NewConsole() LoggerInterface { cw := new(ConsoleWriter) cw.lg = log.New(os.Stdout, "", log.Ldate|log.Ltime) @@ -18,6 +20,8 @@ func NewConsole() LoggerInterface { return cw } +// init console logger. +// jsonconfig like '{"level":LevelTrace}'. func (c *ConsoleWriter) Init(jsonconfig string) error { err := json.Unmarshal([]byte(jsonconfig), c) if err != nil { @@ -26,6 +30,7 @@ func (c *ConsoleWriter) Init(jsonconfig string) error { return nil } +// write message in console. func (c *ConsoleWriter) WriteMsg(msg string, level int) error { if level < c.Level { return nil @@ -34,10 +39,12 @@ func (c *ConsoleWriter) WriteMsg(msg string, level int) error { return nil } +// implementing method. empty. func (c *ConsoleWriter) Destroy() { } +// implementing method. empty. func (c *ConsoleWriter) Flush() { } diff --git a/logs/file.go b/logs/file.go index e19c6c7f..d0512e26 100644 --- a/logs/file.go +++ b/logs/file.go @@ -13,6 +13,8 @@ import ( "time" ) +// FileLogWriter implements LoggerInterface. +// It writes messages by lines limit, file size limit, or time frequency. type FileLogWriter struct { *log.Logger mw *MuxWriter @@ -38,17 +40,20 @@ type FileLogWriter struct { Level int `json:"level"` } +// an *os.File writer with locker. type MuxWriter struct { sync.Mutex fd *os.File } +// write to os.File. func (l *MuxWriter) Write(b []byte) (int, error) { l.Lock() defer l.Unlock() return l.fd.Write(b) } +// set os.File in writer. func (l *MuxWriter) SetFd(fd *os.File) { if l.fd != nil { l.fd.Close() @@ -56,6 +61,7 @@ func (l *MuxWriter) SetFd(fd *os.File) { l.fd = fd } +// create a FileLogWriter returning as LoggerInterface. func NewFileWriter() LoggerInterface { w := &FileLogWriter{ Filename: "", @@ -73,15 +79,16 @@ func NewFileWriter() LoggerInterface { return w } -// jsonconfig like this -//{ +// Init file logger with json config. +// jsonconfig like: +// { // "filename":"logs/beego.log", // "maxlines":10000, // "maxsize":1<<30, // "daily":true, // "maxdays":15, // "rotate":true -//} +// } func (w *FileLogWriter) Init(jsonconfig string) error { err := json.Unmarshal([]byte(jsonconfig), w) if err != nil { @@ -94,6 +101,7 @@ func (w *FileLogWriter) Init(jsonconfig string) error { return err } +// start file logger. create log file and set to locker-inside file writer. func (w *FileLogWriter) StartLogger() error { fd, err := w.createLogFile() if err != nil { @@ -122,6 +130,7 @@ func (w *FileLogWriter) docheck(size int) { w.maxsize_cursize += size } +// write logger message into file. func (w *FileLogWriter) WriteMsg(msg string, level int) error { if level < w.Level { return nil @@ -158,6 +167,8 @@ func (w *FileLogWriter) initFd() error { return nil } +// DoRotate means it need to write file in new file. +// new file name like xx.log.2013-01-01.2 func (w *FileLogWriter) DoRotate() error { _, err := os.Lstat(w.Filename) if err == nil { // file exists @@ -211,10 +222,14 @@ func (w *FileLogWriter) deleteOldLog() { }) } +// destroy file logger, close file writer. func (w *FileLogWriter) Destroy() { w.mw.fd.Close() } +// flush file logger. +// there are no buffering messages in file logger in memory. +// flush file means sync file from disk. func (w *FileLogWriter) Flush() { w.mw.fd.Sync() } diff --git a/logs/log.go b/logs/log.go index a9254aaa..b65414cb 100644 --- a/logs/log.go +++ b/logs/log.go @@ -6,6 +6,7 @@ import ( ) const ( + // log message levels LevelTrace = iota LevelDebug LevelInfo @@ -16,6 +17,7 @@ const ( type loggerType func() LoggerInterface +// LoggerInterface defines the behavior of a log provider. type LoggerInterface interface { Init(config string) error WriteMsg(msg string, level int) error @@ -38,6 +40,8 @@ func Register(name string, log loggerType) { adapters[name] = log } +// BeeLogger is default logger in beego application. +// it can contain several providers and log message into all providers. type BeeLogger struct { lock sync.Mutex level int @@ -50,7 +54,9 @@ type logMsg struct { msg string } -// config need to be correct JSON as string: {"interval":360} +// NewLogger returns a new BeeLogger. +// channellen means the number of messages in chan. +// if the buffering chan is full, logger adapters write to file or other way. func NewLogger(channellen int64) *BeeLogger { bl := new(BeeLogger) bl.msg = make(chan *logMsg, channellen) @@ -60,6 +66,8 @@ func NewLogger(channellen int64) *BeeLogger { return bl } +// SetLogger provides a given logger adapter into BeeLogger with config string. +// config need to be correct JSON as string: {"interval":360}. func (bl *BeeLogger) SetLogger(adaptername string, config string) error { bl.lock.Lock() defer bl.lock.Unlock() @@ -73,6 +81,7 @@ func (bl *BeeLogger) SetLogger(adaptername string, config string) error { } } +// remove a logger adapter in BeeLogger. func (bl *BeeLogger) DelLogger(adaptername string) error { bl.lock.Lock() defer bl.lock.Unlock() @@ -96,10 +105,14 @@ func (bl *BeeLogger) writerMsg(loglevel int, msg string) error { return nil } +// set log message level. +// if message level (such as LevelTrace) is less than logger level (such as LevelWarn), ignore message. func (bl *BeeLogger) SetLevel(l int) { bl.level = l } +// start logger chan reading. +// when chan is full, write logs. func (bl *BeeLogger) StartLogger() { for { select { @@ -111,43 +124,50 @@ func (bl *BeeLogger) StartLogger() { } } +// log trace level message. func (bl *BeeLogger) Trace(format string, v ...interface{}) { msg := fmt.Sprintf("[T] "+format, v...) bl.writerMsg(LevelTrace, msg) } +// log debug level message. func (bl *BeeLogger) Debug(format string, v ...interface{}) { msg := fmt.Sprintf("[D] "+format, v...) bl.writerMsg(LevelDebug, msg) } +// log info level message. func (bl *BeeLogger) Info(format string, v ...interface{}) { msg := fmt.Sprintf("[I] "+format, v...) bl.writerMsg(LevelInfo, msg) } +// log warn level message. func (bl *BeeLogger) Warn(format string, v ...interface{}) { msg := fmt.Sprintf("[W] "+format, v...) bl.writerMsg(LevelWarn, msg) } +// log error level message. func (bl *BeeLogger) Error(format string, v ...interface{}) { msg := fmt.Sprintf("[E] "+format, v...) bl.writerMsg(LevelError, msg) } +// log critical level message. func (bl *BeeLogger) Critical(format string, v ...interface{}) { msg := fmt.Sprintf("[C] "+format, v...) bl.writerMsg(LevelCritical, msg) } -//flush all chan data +// flush all chan data. func (bl *BeeLogger) Flush() { for _, l := range bl.outputs { l.Flush() } } +// close logger, flush all chan data and destroy all adapters in BeeLogger. func (bl *BeeLogger) Close() { for { if len(bl.msg) > 0 { diff --git a/logs/smtp.go b/logs/smtp.go index 228977bb..19296887 100644 --- a/logs/smtp.go +++ b/logs/smtp.go @@ -12,7 +12,7 @@ const ( subjectPhrase = "Diagnostic message from server" ) -// smtpWriter is used to send emails via given SMTP-server. +// smtpWriter implements LoggerInterface and is used to send emails via given SMTP-server. type SmtpWriter struct { Username string `json:"Username"` Password string `json:"password"` @@ -22,10 +22,21 @@ type SmtpWriter struct { Level int `json:"level"` } +// create smtp writer. func NewSmtpWriter() LoggerInterface { return &SmtpWriter{Level: LevelTrace} } +// init smtp writer with json config. +// config like: +// { +// "Username":"example@gmail.com", +// "password:"password", +// "host":"smtp.gmail.com:465", +// "subject":"email title", +// "sendTos":["email1","email2"], +// "level":LevelError +// } func (s *SmtpWriter) Init(jsonconfig string) error { err := json.Unmarshal([]byte(jsonconfig), s) if err != nil { @@ -34,6 +45,8 @@ func (s *SmtpWriter) Init(jsonconfig string) error { return nil } +// write message in smtp writer. +// it will send an email with subject and only this message. func (s *SmtpWriter) WriteMsg(msg string, level int) error { if level < s.Level { return nil @@ -65,9 +78,12 @@ func (s *SmtpWriter) WriteMsg(msg string, level int) error { return err } +// implementing method. empty. func (s *SmtpWriter) Flush() { return } + +// implementing method. empty. func (s *SmtpWriter) Destroy() { return } -- GitLab