navigator

Documentation

Overview

Package navigator provides logging functionality to the K8sBlackPearl project. It utilizes the uber-go/zap logging library to provide structured, leveled, and optionally emoji-prefixed logging capabilities.

The package exposes a package-level Logger variable that is protected by a mutex to ensure thread-safe access and modification. This Logger must be set using the SetLogger function before any of the logging functions are called. If the Logger is not set, the logging functions will output an error message to standard output.

The LogInfoWithEmoji and LogErrorWithEmoji functions provide a way to log informational and error messages, respectively. They both require an emoji string and a context string as part of the message to add a visual identifier to the logs. These functions also accept a variadic number of zap.Field parameters to include structured data in the log messages.

The CreateLogFields function is a helper that creates a slice of zap.Field from given information strings. This can be used to add consistent structured context to logs across different parts of the application.

Usage

Before logging can occur, the Logger must be initialized and set using the SetLogger function. Once set, the LogInfoWithEmoji and LogErrorWithEmoji functions can be used to log messages with structured data.

Example:

// Initialize the Logger (typically done at application start)
logger, _ := zap.NewProduction()
navigator.SetLogger(logger)

// Use the logging functions
navigator.LogInfoWithEmoji("🚀", "Application started")
navigator.LogErrorWithEmoji("❗️", "An error occurred", zap.Error(err))

// Create structured log fields
fields := navigator.CreateLogFields("navigation", "starry-sea", "additional info")
navigator.LogInfoWithEmoji("🧭", "Navigating the stars", fields...)

Note: It is crucial that the SetLogger function is called before any logging functions to avoid nil pointer dereferences. If the Logger is nil when a logging function is called, a message indicating that the Logger is not set will be printed to standard output.

The emoji strings used in the logging functions are purely for visual effect and can be omitted or replaced based on the logging preferences of the application.

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 SetLogger(logger *zap.Logger)
• type LogFieldOption
  • func WithAnyZapField(field zap.Field) LogFieldOption

Variables

var Logger *zap.Logger

Logger is a package-level variable to access the zap logger throughout the worker package.

Functions

func CreateLogFields

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

func LogErrorWithEmoji(emoji string, context string, fields ...zap.Field)

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

func LogErrorWithEmojiRateLimited(emoji string, context string, fields ...zap.Field)

LogErrorWithEmojiRateLimited logs an error message with rate limiting.

func LogInfoWithEmoji

func LogInfoWithEmoji(emoji string, context string, fields ...zap.Field)

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

func LogInfoWithEmojiRateLimited(emoji string, context string, fields ...zap.Field)

LogInfoWithEmojiRateLimited logs an informational message with rate limiting.

func SetLogger

func SetLogger(logger *zap.Logger)

SetLogger sets the logger instance for the package in a thread-safe manner.

Types

type LogFieldOption

type LogFieldOption func() zap.Field

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

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...)