zenlogger

README

Zenlogger 🤖

This library is built based on internal & personal needs. So, this lib can be not suit for your need.

This library support such as

• Logging to file (including customize naming file)
• Structured log to satisfy Gcloud logs structure
• Customize structure & keys
• Full GCP severity levels (Debug, Info, Notice, Warning, Error, Critical, Alert, Emergency)
• Log level filtering — execute only logs at or above configured level
• Caller metadata includes relative file path and line number (example: internal/service/inquiry.go:32)

Sample Output

###Sample structured output log

This is the sample of output output when beautifyJson set to true.

{
  "pid": "97732c84970d49a883193352f7da24f3",
  "severity": "Info",
  "timestamp": "2022-11-29T20:01:48+0700",
  "caller": "map_test.go:47",
  "message": {
    "title": "test map",
    "values": {
      "halo": {
        "2": "two",
        "developer": {
          "Age": 27,
          "Gender": "male",
          "IsMarried": false,
          "Name": "Zeni",
          "Relationship": "",
          "Supporter": [
            {
              "Age": 22,
              "Gender": "bunga",
              "IsMarried": true,
              "Name": "Mawar",
              "Relationship": "",
              "Supporter": []
            },
            {
              "Age": 20,
              "Gender": "warna",
              "IsMarried": false,
              "Name": "Hitam",
              "Relationship": "",
              "Supporter": []
            }
          ]
        },
        "four": 4,
        "one": 1,
        "three": "tilu"
      }
    }
  }
}

Installation 🚀

How to use: This is the sample code of zenlogger usage

package main

import (
	"github.com/zenmuharom/zenlogger"
)

type Person struct {
	Name         string
	Gender       string
	Age          int
	IsMarried    bool
	Relationship string
	Supporter    []Person
}

func Test_map(t *testing.T) {

	logger := NewZenlogger()
	logger.SetConfig(Config{BeautifyJson: true})

	person := Person{
		Name:      "Zeni",
		Gender:    "male",
		Age:       27,
		IsMarried: false,
		Supporter: []Person{
			{
				Name:      "Mawar",
				Age:       22,
				Gender:    "bunga",
				IsMarried: true,
			},
			{
				Name:      "Hitam",
				Age:       20,
				Gender:    "warna",
				IsMarried: false,
			},
		},
	}

	testMap := map[string]interface{}{
		"one":       "1",
		"2":         "two",
		"three":     "tilu",
		"four":      4,
		"developer": person,
	}
	logger.Info("test map", ZenField{Key: "halo", Value: testMap})
}

Config

This is the sample of config you can customize

	logger := zenlogger.NewZenlogger()
	config := zenlogger.Config{
		Pid: zenlogger.ZenConf{
			Label: "insertId",
		},
		Severity: zenlogger.Severity{
			Label:     "Level",
			Access:    "API",
			Info:      "THIS IS INFO",
			Debug:     "DEBUG",
			Notice:    "NOTICE",
			Warning:   "Please Attention To This",
			Error:     "Fault",
			Query:     "DB",
			Critical:  "CRITICAL",
			Alert:     "ALERT",
			Emergency: "EMERGENCY",
		},
		Caller: zenlogger.Caller{
			Label: "trace_file",
			Level: 0,
		},
		Message: zenlogger.Message{
			Label: "pesan",
			Title: zenlogger.ZenConf{
				Label: "judul",
			},
			Values: zenlogger.ZenConf{
				Label: "isi",
			},
		},
		BeautifyJson: true,
	}
	logger.SetConfig(config)

Set log to file

You can set the log to make zenlogger write into file by adding:

	config := zenlogger.Config{}
	config.Output.Path = "logs"
	config.Output.Format = "20060102"
	config.BeautifyJson = true
	logger.SetConfig(config)

Zenlogger will automatically make directory logs (if not exists), and write into file with golang timed format.

Config Property 🤖

Property	sub	description
Pid		process id is label of the key that differentiate with another process in your program
Severity	Label	The label of severity key
Severity	Access	The value of severity when you call zenlogger.Access()
Severity	Info	The value of severity when you call zenlogger.Info()
Severity	Debug	The value of severity when you call zenlogger.Debug()
Severity	Warning	The value of severity when you call zenlogger.Warning()
Severity	Error	The value of severity when you call zenlogger.Error()
Severity	Notice	The value of severity when you call zenlogger.Notice()
Severity	Query	The value of severity when you call zenlogger.Query()
Severity	Critical	The value of severity when you call zenlogger.Critical()
Severity	Alert	The value of severity when you call zenlogger.Alert()
Severity	Emergency	The value of severity when you call zenlogger.Emergency()
DateTime	Label	The label of datetime key when log written
DateTime	Format	The output datetime format, using standard GO datetime format
Caller	Label	The label of caller key
Caller	Level	The level of caller key. the default is 0
Message	Label	The label of message key
Message	Title.Label	The label of title key
Message	Values.Label	The label of values key
BeautifyJson		The beautify config, true to make it beautify formatted, otherwise, set it to false
Level		Minimum log level to execute. Logs below this level are skipped entirely. Default is LevelDebug (all logs execute)
Output	Path	The output path of log files
Output	Format	The output file name using datetime GO format
Sensitive	Enabled	Enable automatic sensitive field protection by key
Sensitive	CaseInsensitive	Match sensitive keys case-insensitively
Sensitive	Rules	Key-to-rule map for automatic protection (Type, optional MaskCount)

Log Level Filtering

Control which logs execute by setting a minimum level. Logs with a level below the configured value are skipped entirely with zero cost (no JSON marshaling, no reflection).

const (
    LevelDebug     LogLevel = 100  // Access & Query share this tier
    LevelInfo       LogLevel = 200
    LevelNotice     LogLevel = 300
    LevelWarning    LogLevel = 400
    LevelError      LogLevel = 500
    LevelCritical   LogLevel = 600
    LevelAlert      LogLevel = 700
    LevelEmergency  LogLevel = 800
)

Example — only execute Warning and above:

logger := zenlogger.NewZenlogger()
logger.SetConfig(zenlogger.Config{
    Level: zenlogger.LevelWarning, // skips Debug, Info, Notice, Access, Query
})

logger.Debug("skipped")    // no-op
logger.Info("skipped")     // no-op
logger.Warning("executed") // written
logger.Critical("executed") // written

Default is LevelDebug — all logs execute unless you configure otherwise.

Sensitive Field Masking

You can mask sensitive values directly per field.

logger.Info("db connection",
		zenlogger.ZenField{Key: "username", Value: username, Type: zenlogger.FIRST_MASKED, MaskCount: 2},
		zenlogger.ZenField{Key: "password", Value: password, Type: zenlogger.FULL_MASKED},
)

Or use helper constructors for cleaner call sites:

logger.Info("db connection",
	zenlogger.Field("username", username),
	zenlogger.MaskedField("password", password, zenlogger.FULL_MASKED, 0),
)

Or configure automatic protection by key so caller does not need to set Type on every field:

logger := zenlogger.NewZenlogger()
logger.SetConfig(zenlogger.Config{
	Sensitive: zenlogger.SensitiveFieldConfig{
		Enabled:         true,
		CaseInsensitive: true,
		Rules: map[string]zenlogger.SensitiveFieldRule{
			"password": {Type: zenlogger.FULL_MASKED},
			"token":    {Type: zenlogger.FIRST_LAST_MASKED, MaskCount: 2},
			"api_key":  {Type: zenlogger.REDACTED},
		},
	},
})

logger.Info("db connection",
	zenlogger.Field("username", username),
	zenlogger.Field("password", password),
	zenlogger.Field("token", token),
	zenlogger.Field("api_key", apiKey),
)

Available protection types:

• FULL_MASKED: mask the entire value
• FIRST_MASKED: mask first MaskCount characters
• LAST_MASKED: mask last MaskCount characters
• FIRST_LAST_MASKED: mask first and last MaskCount characters
• REDACTED: replace value with [REDACTED]
• HASH_SHA256: replace value with SHA-256 hash (hex encoded)

Notes:

• MaskCount defaults to 1 when not set or <= 0
• If MaskCount is longer than the value length, masking is capped to value length
• Protection is applied to the final string representation of Value

Example output:

{
	"message": {
		"title": "db connection",
		"values": {
			"username": "**npayuser",
			"password": "********"
		}
	}
}

You can set or try it in the link below here: 👉 GO Play. 👈

This library is released under: MIT License.

Documentation

Index

• Constants
• type Caller
• type Config
• type DateTime
• type DefaultZenlogger
  • func (zenlog *DefaultZenlogger) Access(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) Alert(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) ConfCaller(CallerConf Caller)
  • func (zenlog *DefaultZenlogger) ConfDateTime(DateTimeConf DateTime)
  • func (zenlog *DefaultZenlogger) ConfMessage(MessageConf Message)
  • func (zenlog *DefaultZenlogger) ConfPid(pidConf ZenConf)
  • func (zenlog *DefaultZenlogger) ConfSensitive(sensitiveConf SensitiveFieldConfig)
  • func (zenlog *DefaultZenlogger) ConfSeverity(ServerityConf Severity)
  • func (zenlog *DefaultZenlogger) Critical(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) Debug(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) Emergency(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) Error(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) GetConfig() Config
  • func (zenlog *DefaultZenlogger) GetPid() string
  • func (zenlog *DefaultZenlogger) Info(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) Notice(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) Query(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) SetConfig(newConfig Config)
  • func (zenlog *DefaultZenlogger) Warning(message string, fields ...ZenField) string
  • func (zenlog *DefaultZenlogger) WithPid(pid string) Zenlogger
• type LogLevel
• type MaskType
• type Message
• type Output
• type SensitiveFieldConfig
• type SensitiveFieldRule
• type Severity
• type ZenConf
• type ZenField
  • func Field(key string, value interface{}) ZenField
  • func MaskedField(key string, value interface{}, maskType MaskType, maskCount int) ZenField
• type ZenLog
  • func (zmap ZenLog) MarshalJSON() ([]byte, error)
• type ZenMessage
• type Zenlogger
  • func NewZenlogger(pid ...string) Zenlogger

Constants

const (
	DEFAULT_ACCESS    = "Access"
	DEFAULT_INFO      = "Info"
	DEFAULT_NOTICE    = "Notice"
	DFEAULT_WARNING   = "Warning"
	DEFAULT_ERROR     = "Error"
	DEFAULT_DEBUG     = "Debug"
	DEFAULT_QUERY     = "Query"
	DEFAULT_CRITICAL  = "Critical"
	DEFAULT_ALERT     = "Alert"
	DEFAULT_EMERGENCY = "Emergency"
)

Types

type Caller

type Caller struct {
	Label string
	Level int
}

type Config

type Config struct {
	Pid          ZenConf
	Severity     Severity
	DateTime     DateTime
	Caller       Caller
	Message      Message
	BeautifyJson bool
	Production   bool
	Level        LogLevel
	Output       Output
	Sensitive    SensitiveFieldConfig
}

type DateTime

type DateTime struct {
	Label  string
	Format string
}

type DefaultZenlogger

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

func (*DefaultZenlogger) Access

func (zenlog *DefaultZenlogger) Access(message string, fields ...ZenField) string

func (*DefaultZenlogger) Alert

func (zenlog *DefaultZenlogger) Alert(message string, fields ...ZenField) string

func (*DefaultZenlogger) ConfCaller

func (zenlog *DefaultZenlogger) ConfCaller(CallerConf Caller)

func (*DefaultZenlogger) ConfDateTime

func (zenlog *DefaultZenlogger) ConfDateTime(DateTimeConf DateTime)

func (*DefaultZenlogger) ConfMessage

func (zenlog *DefaultZenlogger) ConfMessage(MessageConf Message)

func (*DefaultZenlogger) ConfPid

func (zenlog *DefaultZenlogger) ConfPid(pidConf ZenConf)

func (*DefaultZenlogger) ConfSensitive

func (zenlog *DefaultZenlogger) ConfSensitive(sensitiveConf SensitiveFieldConfig)

func (*DefaultZenlogger) ConfSeverity

func (zenlog *DefaultZenlogger) ConfSeverity(ServerityConf Severity)

func (*DefaultZenlogger) Critical

func (zenlog *DefaultZenlogger) Critical(message string, fields ...ZenField) string

func (*DefaultZenlogger) Debug

func (zenlog *DefaultZenlogger) Debug(message string, fields ...ZenField) string

func (*DefaultZenlogger) Emergency

func (zenlog *DefaultZenlogger) Emergency(message string, fields ...ZenField) string

func (*DefaultZenlogger) Error

func (zenlog *DefaultZenlogger) Error(message string, fields ...ZenField) string

func (*DefaultZenlogger) GetConfig

func (zenlog *DefaultZenlogger) GetConfig() Config

func (*DefaultZenlogger) GetPid

func (zenlog *DefaultZenlogger) GetPid() string

func (*DefaultZenlogger) Info

func (zenlog *DefaultZenlogger) Info(message string, fields ...ZenField) string

func (*DefaultZenlogger) Notice

func (zenlog *DefaultZenlogger) Notice(message string, fields ...ZenField) string

func (*DefaultZenlogger) Query

func (zenlog *DefaultZenlogger) Query(message string, fields ...ZenField) string

func (*DefaultZenlogger) SetConfig

func (zenlog *DefaultZenlogger) SetConfig(newConfig Config)

func (*DefaultZenlogger) Warning

func (zenlog *DefaultZenlogger) Warning(message string, fields ...ZenField) string

func (*DefaultZenlogger) WithPid

func (zenlog *DefaultZenlogger) WithPid(pid string) Zenlogger

type LogLevel

type LogLevel int

const (
	LevelDebug     LogLevel = 100
	LevelInfo      LogLevel = 200
	LevelAccess    LogLevel = 200
	LevelQuery     LogLevel = 200
	LevelNotice    LogLevel = 300
	LevelWarning   LogLevel = 400
	LevelError     LogLevel = 500
	LevelCritical  LogLevel = 600
	LevelAlert     LogLevel = 700
	LevelEmergency LogLevel = 800
)

type MaskType

type MaskType string

const (
	FULL_MASKED       MaskType = "FULL_MASKED"
	FIRST_MASKED      MaskType = "FIRST_MASKED"
	LAST_MASKED       MaskType = "LAST_MASKED"
	FIRST_LAST_MASKED MaskType = "FIRST_LAST_MASKED"
	REDACTED          MaskType = "REDACTED"
	HASH_SHA256       MaskType = "HASH_SHA256"
)

const (
	MaskFull       MaskType = FULL_MASKED
	MaskFirst      MaskType = FIRST_MASKED
	MaskLast       MaskType = LAST_MASKED
	MaskFirstLast  MaskType = FIRST_LAST_MASKED
	MaskRedacted   MaskType = REDACTED
	MaskHashSHA256 MaskType = HASH_SHA256
)

type Message

type Message struct {
	Label  string
	Title  ZenConf
	Values ZenConf
}

type Output

type Output struct {
	Path       string
	Format     string
	BufferSize int64
}

type SensitiveFieldConfig

type SensitiveFieldConfig struct {
	Enabled         bool
	CaseInsensitive bool
	Rules           map[string]SensitiveFieldRule
}

type SensitiveFieldRule

type SensitiveFieldRule struct {
	Type      MaskType
	MaskCount int
}

type Severity

type Severity struct {
	Label     string
	Access    string
	Info      string
	Debug     string
	Query     string
	Notice    string
	Warning   string
	Error     string
	Critical  string
	Alert     string
	Emergency string
}

type ZenConf

type ZenConf struct {
	Label string
}

type ZenField

type ZenField struct {
	Key       string
	Value     interface{}
	Type      MaskType
	MaskCount int
}

func Field

func Field(key string, value interface{}) ZenField

func MaskedField

func MaskedField(key string, value interface{}, maskType MaskType, maskCount int) ZenField

type ZenLog

type ZenLog []ZenField

func (ZenLog) MarshalJSON

func (zmap ZenLog) MarshalJSON() ([]byte, error)

type ZenMessage

type ZenMessage struct {
	Title  string                 `json:"title,omitempty"`
	Values map[string]interface{} `json:"values,omitempty"`
}

type Zenlogger

type Zenlogger interface {
	SetConfig(config Config)
	GetConfig() Config
	WithPid(pid string) Zenlogger
	GetPid() string
	Access(message string, fields ...ZenField) string
	Info(message string, fields ...ZenField) string
	Notice(message string, fields ...ZenField) string
	Query(message string, fields ...ZenField) string
	Debug(message string, fields ...ZenField) string
	Warning(message string, fields ...ZenField) string
	Error(message string, fields ...ZenField) string
	Critical(message string, fields ...ZenField) string
	Alert(message string, fields ...ZenField) string
	Emergency(message string, fields ...ZenField) string
}

func NewZenlogger

func NewZenlogger(pid ...string) Zenlogger