Documentation
¶
Overview ¶
Package navigator provides structured logging capabilities tailored for the K8sBlackPearl project, utilizing the uber-go/zap library for high-performance, leveled logging. This package enhances log messages with emojis for visual distinction and supports structured logging with zap.Field parameters.
A package-level Logger variable is available, which should be set using SetLogger before any logging functions are called. If the Logger is not set, logging functions will default to printing error messages to standard output to prevent the application from panicking due to a nil Logger.
Functions such as LogInfoWithEmoji and LogErrorWithEmoji are provided for logging informational and error messages, respectively. These functions append emojis to the log messages for easier visual scanning in log output. They also accept a variable number of zap.Field parameters for structured context logging.
The CreateLogFields helper function is available to generate a slice of zap.Field from specified strings, enabling consistent structured context in logs throughout the application.
Usage ¶
Before logging, the Logger must be initialized and set using SetLogger. After setting up, the logging functions such as LogInfoWithEmoji and LogErrorWithEmoji can be used for logging messages with structured context.
Example:
// Initialize the Logger (usually at the start of the application)
logger, _ := zap.NewProduction()
navigator.SetLogger(logger)
// Logging with package functions
navigator.LogInfoWithEmoji("🚀", "Application started")
navigator.LogErrorWithEmoji("❗️", "An error occurred", zap.Error(err))
// Structuring log fields
fields := navigator.CreateLogFields("navigation", "starry-sea", zap.String("detail", "additional info"))
navigator.LogInfoWithEmoji("🧭", "Navigating the stars", fields...)
Important Note: Ensure that SetLogger is invoked before any logging functions to prevent nil pointer dereferences. If the Logger is nil during a logging attempt, an error message will be printed to standard output indicating the absence of a set Logger.
The use of emoji strings in logging functions is optional and for visual enhancement. These can be excluded or customized according to the application's logging standards.
Copyright (c) 2023 H0llyW00dzZ
Index ¶
- Variables
- func CreateLogFields(sailing string, shipsnamespace string, fieldOpts ...LogFieldOption) []zap.Field
- func LogErrorWithEmoji(emoji string, context string, fields ...zap.Field)
- func LogErrorWithEmojiRateLimited(emoji string, context string, fields ...zap.Field)
- func LogInfoWithEmoji(emoji string, context string, fields ...zap.Field)
- func LogInfoWithEmojiRateLimited(emoji string, context string, fields ...zap.Field)
- func LogWithEmoji(level zapcore.Level, emoji string, context string, rateLimited bool, ...)
- func SetLogger(logger *zap.Logger)
- type LogFieldOption
Constants ¶
This section is empty.
Variables ¶
var Logger *zap.Logger
Logger is a package-level variable to access the zap logger throughout the worker package.
Functions ¶
func CreateLogFields ¶ added in v0.1.0
func CreateLogFields(sailing string, shipsnamespace string, fieldOpts ...LogFieldOption) []zap.Field
createLogFields creates a slice of zap.Field with the operation and additional info. It can be used to add structured context to logs.
func LogErrorWithEmoji ¶ added in v0.1.0
logErrorWithEmoji logs an error message with a given emoji, context, and fields. It checks if the Logger is not nil before logging to prevent panics.
func LogErrorWithEmojiRateLimited ¶ added in v0.1.1
LogErrorWithEmojiRateLimited logs an error message with rate limiting.
func LogInfoWithEmoji ¶ added in v0.1.0
LogInfoWithEmoji logs an informational message with a given emoji, context, and fields. It checks if the Logger is not nil before logging to prevent panics.
func LogInfoWithEmojiRateLimited ¶ added in v0.1.1
LogInfoWithEmojiRateLimited logs an informational message with rate limiting.
Note: this dead code is left here for future use.
func LogWithEmoji ¶ added in v0.1.2
func LogWithEmoji(level zapcore.Level, emoji string, context string, rateLimited bool, fields ...zap.Field)
LogWithEmoji logs a message with a given level, emoji, context, and fields. It checks if the Logger is not nil before logging to prevent panics. The rateLimited flag determines whether the log should be rate limited.
Types ¶
type LogFieldOption ¶ added in v0.1.0
LogFieldOption is a type that represents a function which returns a zap.Field. It's used to pass custom field generators to functions that create a slice of zap.Fields for logging. This allows for deferred creation of zap.Fields, which can be useful when the value of the field is not immediately available or when you want to include custom logic to determine the value of the field.
Example usage:
fields := navigator.CreateLogFields("sailing", "the high seas", navigator.WithAnyZapField(zap.Int("treasure chests", 5)))
navigator.LogInfoWithEmoji("🏴☠️", "Pirates ahoy!", fields...)
func WithAnyZapField ¶ added in v0.1.0
func WithAnyZapField(field zap.Field) LogFieldOption
WithAnyZapField creates a LogFieldOption that encapsulates a zap.Field for deferred addition to a log entry. This function is particularly handy when you have a custom field to add to your log that isn't already covered by existing "With*" functions. It allows for a more flexible and dynamic approach to logging, akin to how a pirate might prefer the freedom to navigate the open seas.
Example:
Let's say we want to log an event related to a pirate's treasure map. We have a custom binary field that represents the map, and we want to include this in our log fields. We can use WithAnyZapField to add this custom field to our logs as follows:
treasureMap := []byte{0x0A, 0x0B, 0x0C, 0x0D} // This represents our treasure map in binary form.
fields := navigator.CreateLogFields("sailing", "find treasure", navigator.WithAnyZapField(zap.Binary("treasureMap", treasureMap)))
navigator.LogInfoWithEmoji("🏴☠️", "Found a treasure map!", fields...)
Source Files