Documentation
¶
Overview ¶
Package navigator provides structured logging capabilities for the K8sBlackPearl project, leveraging the uber-go/zap library. It offers leveled logging with the option to prefix messages with emojis for enhanced visual distinction.
A package-level Logger variable is available and protected by a mutex to ensure safe concurrent access. This Logger should be initialized and set using SetLogger prior to invoking any logging functions. Failing to set the Logger will result in error messages being printed to standard output instead of proper log entries.
Logging functions such as LogInfoWithEmoji and LogErrorWithEmoji are available for recording informational and error messages, respectively. These functions enhance log messages with emojis and a context string for quick identification. They also support structured logging by accepting a variable number of zap.Field parameters.
Helper function CreateLogFields is provided to generate a slice of zap.Field from specified strings, facilitating the inclusion of consistent structured context within logs throughout the application.
Usage ¶
The Logger must be initialized and set using SetLogger before any logging activity. Subsequently, LogInfoWithEmoji and LogErrorWithEmoji can be employed 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 the 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.
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