logaro

README

Logaro

Logaro is a lightweight Go package for JSON-based logging. It provides a simple and flexible logging solution with support for log levels, log entry customization, and hierarchical loggers.

Features

• JSON-based logging format for easy log consumption and analysis.
• Configurable log levels to control the verbosity of the log output.
• Ability to customize log entries with additional fields.
• Hierarchical loggers to organize and inherit log settings.
• Support for serializers to transform log message and field values.

Installation

To use Logaro in your Go project, you need to have Go installed and set up. Then, run the following command to install the package:

go get github.com/iamando/logaro

Usage

Here's a basic example of how to use Logaro:

package main

import "github.com/iamando/logaro"


func main() {
 // Create a logger
 logger := logaro.GenerateLogger()

 // Log a message
 logger.Log("info", "Hello, Logaro!", nil)

 // Log a message with additional fields
 logger.Log("error", "An error occurred", map[string]interface{}{
  "error_code": 500,
  "error_msg":  "Internal Server Error",
 })

 // Create a child logger with additional fields
 childLogger := logger.WithFields(map[string]interface{}{
  "component": "subsystemA",
 })

 // Log from the child logger
 childLogger.Log("debug", "Debug message from subsystemA", nil)
}

For more detailed examples and advanced usage, please refer to the examples directory.

Output

Using Logaro, the log entries can be output in a JSON format. Here's an example of how the log entries would appear when logged to the standard output:

{"timestamp":"2023-05-10T10:30:45Z","message":"This is an informational message","level":"info","fields":null}
{"timestamp":"2023-05-10T10:30:45Z","message":"This is a warning message","level":"warn","fields":null}
{"timestamp":"2023-05-10T10:30:45Z","message":"This is an error message","level":"error","fields":null}
{"timestamp":"2023-05-10T10:30:45Z","message":"Debugging information","level":"debug","fields":{"user_id":123,"request_id":"abc123"}}
{"timestamp":"2023-05-10T10:30:45Z","message":"Child logger message","level":"info","fields":{"component":"subsystemA"}}
{"timestamp":"2023-05-10T10:30:45Z","message":"Custom serialization example","level":"info","fields":{"field":"Value"}}

The log entries are represented as JSON objects, where each object contains the timestamp, message, level, and fields properties. The fields property contains additional key-value pairs associated with the log entry.

Please note that the actual log output may vary based on the specific log messages, log levels, and fields provided in your application.

Feel free to customize and expand upon this output example section based on your specific package functionality and desired log format.

API

type Logger

Represents a logger instance that can be used to log messages at different levels.

Methods

• Log(level string, message string, fields map[string]interface{}) Logs a message at the specified log level. Additional fields can be provided as a map of key-value pairs.

• Child(fields map[string]interface{}) *Logger Creates a child logger with the specified additional fields. The child logger inherits the log settings and fields from its parent. ssss

• WithFields(fields map[string]interface{}) *Logger Creates a child logger with the specified additional fields. The child logger inherits the log settings and fields from its parent.

• WithSerializers(serializers map[string]func(interface{}) interface{}) *Logger Creates a child logger with custom serializers for transforming log message and field values. The serializers argument should be a map where the keys represent the fields to be serialized and the values are functions that perform the serialization.

type LogEntry

Represents a log entry containing the log message, log level, and additional fields.

Fields

• Timestamp string The timestamp of the log entry in RFC3339 format.

• Message string The log message.

• Level string The log level.

• Fields map[string]interface{} Additional fields associated with the log entry.

func NewLogger() *Logger

Creates a new instance of the Logger with default settings.

This API section provides an overview of the available types, methods, and functions in the Logaro package. Please refer to the code documentation and examples for more details on how to use the API effectively.

Feel free to customize and expand upon this API section based on your specific package functionality and features.

Documentation

For detailed documentation and API reference, please refer to the GoDoc page.

Support

Logaro is an MIT-licensed open source project. It can grow thanks to the sponsors and support.

License

Logaro is MIT licensed.

Documentation

Index

• type LogEntry
• type Logger
  • func GenerateLogger() *Logger
  • func (l *Logger) Child(fields map[string]interface{}) *Logger
  • func (l *Logger) Log(level, message string, fields map[string]interface{})
  • func (l *Logger) WithFields(fields map[string]interface{}) *Logger
  • func (l *Logger) WithSerializers(serializers map[string]func(interface{}) interface{}) *Logger

Types

type LogEntry

type LogEntry struct {
	Timestamp string                 `json:"timestamp"`
	Message   string                 `json:"message"`
	Level     string                 `json:"level"`
	Fields    map[string]interface{} `json:"fields,omitempty"`
}

LogEntry represents a log entry structure. It defines the structure of a log entry with various fields.

• Timestamp: the timestamp when the log entry was created.
• Message: the log message.
• Level: the severity level of the log entry.
• Fields: additional fields associated with the log entry (optional). These fields provide extra context or information about the log event. They are stored as key-value pairs in a map[string]interface{}. The "omitempty" tag ensures that the "fields" field is omitted from the JSON output if no additional fields are present in the log entry.

type Logger

type Logger struct {
	Level       string
	Writer      *json.Encoder
	Parent      *Logger
	Children    []*Logger
	EventFields map[string]interface{}
	Serializer  func(data interface{}) interface{}
}

Logger represents a JSON logger instance. It encapsulates the configuration and functionality of a logging instance. - Level: the log level for the logger. - Writer: the JSON encoder used for writing log entries. - Parent: the parent logger if this logger is a child logger. - Children: a list of child loggers created from this logger. - EventFields: additional fields associated with each log entry from this logger. - Serializer: a function for serializing log entry messages and fields (optional).

func GenerateLogger

func GenerateLogger() *Logger

GenerateLogger creates a new logger instance with the specified configuration. It initializes a Logger struct with the provided log level and output writer. - level: the log level for the logger. - writer: the JSON encoder used for writing log entries. Returns the newly created logger instance. The logger is initialized with default settings for parent, children, event fields, and serializer.

func (*Logger) Child

func (l *Logger) Child(fields map[string]interface{}) *Logger

Child creates a child logger with additional event fields. It creates a new logger instance as a child of the current logger. The child logger inherits the log level and event fields from the parent logger. Additionally, it adds the specified additional event fields to its own fields. Returns the newly created child logger that can be used for logging with added context. Child loggers provide a hierarchical structure to organize and filter log entries.

func (*Logger) Log

func (l *Logger) Log(level, message string, fields map[string]interface{})

Log logs a message at the specified level, along with optional additional fields. It first checks if the logger is enabled for the given log level. If the logger is enabled, it constructs a LogEntry with a timestamp, log message, log level, and merged event fields (including additional fields passed as parameters). If a serializer is set for the logger, it applies the serializer function to the log entry before encoding. The serializer can be used to customize the formatting or modify the log entry. Finally, it encodes the log entry using the logger's JSON encoder and writes it to the output. If there is an error encoding the log entry, an error message is printed to the standard output.

func (*Logger) WithFields

func (l *Logger) WithFields(fields map[string]interface{}) *Logger

WithFields creates a child logger with additional event fields. It creates a new child logger instance based on the current logger. The child logger inherits the log level from the parent logger. Additionally, it adds the specified additional event fields to its own fields. Returns the newly created child logger with the added event fields. The child logger can be used to log with the inherited log level and the additional context provided by the added event fields, allowing more specific and detailed log entries.

func (*Logger) WithSerializers

func (l *Logger) WithSerializers(serializers map[string]func(interface{}) interface{}) *Logger

WithSerializers creates a child logger with custom serializers for specific fields. It creates a new child logger instance based on the current logger. The child logger inherits the log level from the parent logger. It adds custom serializers for specific fields to the child logger's serializer. The serializers are applied to the corresponding fields during log entry serialization, allowing custom formatting or modification of specific fields. Returns the newly created child logger with the added serializers. The child logger can be used to log with the inherited log level, and the added serializers provide customization for specific fields during serialization.