zl 🧑‍💻

zl is a logger based on zap. It provides advanced logging features.

zl is a logging package designed with the developer experience in mind. You can choose the most suitable output format according to your purpose, such as emphasizing easy-to-read console output during development in a local environment and outputting structured detailed logs in a production environment. It offers rich functionality but is easy to configure.

This is useful when developing systems that perform complex processing.

Features

Selectable output format

PrettyOutput (Default) 🧑‍💻

• High Developer Experience.
• The optimal setting for a development environment.
• Output colored simple logs to the console.
• Output detail JSON logs to the logfile.
• Easy-to-read error reports and stack trace.
• It can jumps directly to the line of the file that is output to the console log (when using Goland or VSCode).

Log messages do not have to be written in upper snake case, but if messages are written in a uniform manner, it is easy to extract specific logs using tools such as Google Cloud Logging or the jq command. It is recommended that log messages be written in a consistent manner. By writing log messages succinctly and placing detailed information in separate fields, the overall clarity of the logs is improved, making it easier to understand the flow of processes.

ConsoleOutput ⚡

• High Performance.
• The optimal setting for a production environment.
• Output detail JSON logs to the console.
• Especially suitable for cloud environments such as Google Cloud Logging or Datadog.
• It is fast because it uses only the functions provided by zap (not sugared) and does not perform any extra processing.

FileOutput

• The optimal setting for a production environment.
• It is especially suitable for command line tool or on-premises environments.
• Support logfile rotation.

ConsoleAndFileOutput

• It is a setting for the development environment.
• Output detail JSON logs to console and logfile.
• It is recommended to use with jq command to avoid drowning in a sea of information.
• It is recommended to set PrettyOutput instead.

Installation

go get -u github.com/nkmr-jp/zl

Quick Start

code: examples/basic/main.go

package main

import (
	"encoding/json"
	"os"
	"strconv"

	"github.com/nkmr-jp/zl"
	"go.uber.org/zap"
)

func main() {
	// Set Options
	zl.SetLevel(zl.DebugLevel)
	zl.SetOmitKeys(zl.HostnameKey)

	// Initialize
	zl.Init()
	defer zl.Sync() // flush log buffer

	// Write logs
	zl.Info("USER_INFO", zap.String("user_name", "Alice"), zap.Int("user_age", 20)) // can use zap fields.
	zl.Info("DISPLAY_TO_CONSOLE", zl.Console("The message you want to display to console"))
	zl.Warn("WARN_MESSAGE")
	zl.Debug("DEBUG_MESSAGE")
	_, err := os.ReadFile("test")
	zl.Err("READ_FILE_ERROR", err)
	
	// if the same error occurs multiple times in the same location, the error report will show them all together.
	for i := 0; i < 2; i++ {
		_, err = strconv.Atoi("one")
		zl.Err("A_TO_I_ERROR", err)
	}
	for i := 0; i < 3; i++ {
		v := ""
		err = json.Unmarshal([]byte("test"), &v)
		zl.Err("JSON_UNMARSHAL_ERROR", err)
	}
}

Console output.
The console displays minimal information. Displays a stack trace when an error occurs.

File output.
Detailed information is available in the log file. You can also use jq to extract only the information you need.

$ cat log/app.jsonl | jq 'select(.message | startswith("USER_")) | select(.pid==921)'

{
  "severity": "INFO",
  "timestamp": "2022-08-22T10:30:39.154575+09:00",
  "caller": "basic/main.go:22",
  "function": "main.main",
  "message": "USER_INFO",
  "version": "fc43f68",
  "pid": 921,
  "user_name": "Alice",
  "user_age": 20
}
   

Examples

• examples
• example_test.go