README
¶
Logging Module
The Logging Module provides structured logging with Zap for high-performance logging in Go applications. It wraps the zap logging library and adds features like trace ID extraction from context and context-aware logging methods.
Features
- Log Levels: Debug, Info, Warn, Error, Fatal
- Structured Logging: Key-value pairs for better searchability
- Output Formats: JSON, console
- Context-Aware Logging: Log with context information including trace IDs
- Performance: High-performance logging with minimal allocations
- Trace Integration: Automatic extraction of trace IDs from OpenTelemetry context
Installation
go get github.com/abitofhelp/servicelib/logging
Quick Start
See the Basic Usage example for a complete, runnable example of how to use the Logging module.
API Documentation
Basic Logging
The NewLogger function creates a new zap logger configured for either development or production use.
Basic Usage
See the Basic Usage example for a complete, runnable example of how to use the basic logging functionality.
Context-Aware Logging
The ContextLogger struct provides context-aware logging methods that automatically extract trace information from the context.
Context-Aware Logging Example
See the Context-Aware Logging example for a complete, runnable example of how to use context-aware logging.
Trace Integration
The WithTraceID function adds trace ID and span ID to the logger from the provided context.
Adding Trace IDs to Logs
See the Trace ID example for a complete, runnable example of how to add trace IDs to logs.
Logger Interface
The Logger interface defines the methods for context-aware logging.
See the Context-Aware Logging example for a complete, runnable example of how to use the Logger interface.
Configuration
The logger can be configured with different log levels and output formats.
See the Basic Usage example for a complete, runnable example of how to configure the logger.
Available log levels:
debug: Detailed information for debugginginfo: General operational informationwarn: Warning events that might cause issueserror: Error events that might still allow the application to continuefatal: Severe error events that cause the application to terminate
Best Practices
-
Use Structured Logging: Always use structured logging with key-value pairs instead of string formatting.
-
Include Context: Always pass context to logging methods when available to include trace information.
-
Log Levels: Use appropriate log levels for different types of information.
-
Error Logging: When logging errors, always include the error object using
zap.Error(err). -
Performance: In hot paths, check if the log level is enabled before constructing expensive log messages.
See the Basic Usage example for examples of these best practices.
Troubleshooting
Common Issues
Logger Not Initialized
Issue: Attempting to use a logger that hasn't been properly initialized.
Solution: Always check for errors when creating a logger and ensure that the logger is initialized before use.
Log Messages Not Appearing
Issue: Log messages are not appearing in the expected output.
Solution: Check that the log level is set appropriately. For example, debug messages won't appear if the log level is set to info or higher.
Performance Issues
Issue: Logging is causing performance issues in the application.
Solution: Use conditional logging for expensive operations, ensure that debug logging is disabled in production, and consider using sampling for high-volume logs.
Related Components
- Telemetry - The telemetry component uses the logging component for logging telemetry events.
- Middleware - The middleware component uses the logging component for request logging.
- Health - The health component uses the logging component for logging health check results.
Contributing
Contributions to this component are welcome! Please see the Contributing Guide for more information.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Documentation
¶
Overview ¶
Package logging provides centralized logging functionality for services. It wraps the zap logging library and adds features like trace ID extraction from context and context-aware logging methods. This package is part of the infrastructure layer and provides logging capabilities to all other layers of the application.
Index ¶
- func NewLogger(level string, development bool) (*zap.Logger, error)
- func WithTraceID(ctx context.Context, logger *zap.Logger) *zap.Logger
- type ContextLogger
- func (l *ContextLogger) Debug(ctx context.Context, msg string, fields ...zap.Field)
- func (l *ContextLogger) Error(ctx context.Context, msg string, fields ...zap.Field)
- func (l *ContextLogger) Fatal(ctx context.Context, msg string, fields ...zap.Field)
- func (l *ContextLogger) Info(ctx context.Context, msg string, fields ...zap.Field)
- func (l *ContextLogger) Sync() error
- func (l *ContextLogger) Warn(ctx context.Context, msg string, fields ...zap.Field)
- func (l *ContextLogger) With(ctx context.Context) *zap.Logger
- type Logger
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewLogger ¶
NewLogger creates a new zap logger configured based on the provided level and environment. It sets up appropriate encoders and log levels for either development or production use. Parameters:
- level: The minimum log level as a string (e.g., "debug", "info", "warn", "error")
- development: Whether to use development mode with console output (true) or production mode with JSON output (false)
Returns:
- *zap.Logger: A configured zap logger instance
- error: An error if logger creation fails
func WithTraceID ¶
WithTraceID adds trace ID and span ID to the logger from the provided context. This enables correlation between logs and traces for distributed tracing. Parameters:
- ctx: The context containing trace information
- logger: The base logger to enhance with trace information
Returns:
- *zap.Logger: A new logger with trace ID and span ID fields added if available
Types ¶
type ContextLogger ¶
type ContextLogger struct {
// contains filtered or unexported fields
}
ContextLogger is a logger that includes context information in log entries. It wraps a zap.Logger and provides methods that accept a context parameter, automatically extracting and including trace information in log entries.
func NewContextLogger ¶
func NewContextLogger(base *zap.Logger) *ContextLogger
NewContextLogger creates a new context-aware logger wrapping the provided base logger. If base is nil, a no-op logger will be used to prevent nil pointer panics. Parameters:
- base: The base zap logger to wrap
Returns:
- *ContextLogger: A new context logger instance
func (*ContextLogger) Debug ¶
Debug logs a debug-level message with context information. Parameters:
- ctx: The context containing trace information
- msg: The message to log
- fields: Additional fields to include in the log entry
func (*ContextLogger) Error ¶
Error logs an error-level message with context information. Parameters:
- ctx: The context containing trace information
- msg: The message to log
- fields: Additional fields to include in the log entry
func (*ContextLogger) Fatal ¶
Fatal logs a fatal-level message with context information. This will terminate the program after logging the message. Parameters:
- ctx: The context containing trace information
- msg: The message to log
- fields: Additional fields to include in the log entry
func (*ContextLogger) Info ¶
Info logs an info-level message with context information. Parameters:
- ctx: The context containing trace information
- msg: The message to log
- fields: Additional fields to include in the log entry
func (*ContextLogger) Sync ¶
func (l *ContextLogger) Sync() error
Sync flushes any buffered log entries to their destination. This should be called before program termination to ensure all logs are written. Returns:
- error: An error if flushing fails
func (*ContextLogger) Warn ¶
Warn logs a warning-level message with context information. Parameters:
- ctx: The context containing trace information
- msg: The message to log
- fields: Additional fields to include in the log entry
func (*ContextLogger) With ¶
func (l *ContextLogger) With(ctx context.Context) *zap.Logger
With returns a logger with trace information from the given context. Parameters:
- ctx: The context containing trace information
Returns:
- *zap.Logger: A logger with trace ID and span ID fields added if available
type Logger ¶
type Logger interface {
// Debug logs a debug-level message with context information
Debug(ctx context.Context, msg string, fields ...zap.Field)
// Info logs an info-level message with context information
Info(ctx context.Context, msg string, fields ...zap.Field)
// Warn logs a warning-level message with context information
Warn(ctx context.Context, msg string, fields ...zap.Field)
// Error logs an error-level message with context information
Error(ctx context.Context, msg string, fields ...zap.Field)
// Fatal logs a fatal-level message with context information
Fatal(ctx context.Context, msg string, fields ...zap.Field)
// Sync flushes any buffered log entries
Sync() error
}
Logger defines the interface for context-aware logging
Source Files
Directories