README
¶
GO GELF LOGGER
This package provides an io.Writer that can be used with logging libraries such as zerolog or zap for sending your logs to a GELF-compatible server like Graylog.
This project was inspired by https://github.com/Graylog2/go-gelf.
I was missing the capability of also sending the additional fields, which can be specified in zerolog or zap, as actual additional field with GELF.
This package takes all fields except of "level", "message"/"msg" and "time" and adds them as additional fields in the GELF request.
So you don't need an additional custom extractor or pipline for those fields. An example could be a "request-id" field.
Requirements
- Go1.22.0
- The timestamp field must be a UNIX timestamp with milliseconds.
- The log message must be a JSON string.
Installation
TODO: To install the package, use the following command:
Usage
Below is a basic usage example:
package main
import (
"crypto/tls"
"crypto/x509"
gelflogger "github.com/jame-developer/gelf-logger"
"github.com/rs/zerolog"
"io"
"log"
"net"
"os"
)
// Main function with zerolog integration using the MultilevelWriter func.
func main() {
// Create an array of log writers for the MultilevelWriter and add `os.Stderr` as default.
logWriters := []io.Writer{os.Stderr}
// Load our Root CA certificate chain
caCert, err := os.ReadFile("path to your rootCA certificate chain")
if err != nil {
log.Fatal(err)
}
caCertPool := x509.NewCertPool()
caCertPool.AppendCertsFromPEM(caCert)
// Create the credentials and return it
config := &tls.Config{
RootCAs: caCertPool,
InsecureSkipVerify: false,
// Filled other fields as necessary
}
graylogLogger, gelfLoggerInitErr := gelflogger.NewLogger("<YOUR_GRAYLOG_SERVER>:12201", true, config)
// Only append the gelf-writer to the logWrites if initialization was successful.
if gelfLoggerInitErr == nil {
gelfWriter := gelflogger.GelfWriter{
Logger: graylogLogger,
}
logWriters = append(logWriters, &gelfWriter)
}
// Set the time field format to a GELF compatible timestamp format see also https://go2docs.graylog.org/5-0/getting_in_log_data/gelf.html?tocpath=Getting%20in%20Logs%7CLog%20Sources%7CGELF%7C_____0#GELFPayloadSpecification
zerolog.TimeFieldFormat = zerolog.TimeFormatUnixMs
// Create the Multilevel writer and create the zero logger.
multiLevelWriter := zerolog.MultiLevelWriter(logWriters...)
logger := zerolog.New(multiLevelWriter).With().Timestamp().Logger()
// Use the created zero logger to log an error message, in case the initialization of the GELF-logger failed
if gelfLoggerInitErr != nil {
logger.Error().Err(gelfLoggerInitErr).Msg("Failed to initialize GELF logger.")
}
// Log a test message, you should see this message in your console and on the server you specified above.
logger.Info().Str("custom_field", "custom_value").IPAddr("remoteIP", net.ParseIP("192.168.0.1")).Msg("This is a test log message with zerolog2")
}
Testing
- create test certificate files. You can use OpenSSL with the following commands in your
test_datafolder under project root:
openssl req -newkey rsa:2048 -nodes -keyout testkey.pem -x509 -days 1 -out testcert.pem
To run tests in the terminal, go to the directory where the project is located and type: go test ./...
License
This project is licensed under the terms of MIT license.
Contact
If you have specific questions about this project, you can reach out. I'll get back to you as soon as I can.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GelfWriter ¶
type GelfWriter struct {
Logger *Logger
}
GelfWriter Use the logger to write log messages
func (*GelfWriter) Write ¶
func (gw *GelfWriter) Write(p []byte) (n int, err error)
Write writes the log message to Graylog. It first unmarshals the log message into a map, and then retrieves the "message" key from the map. It ensures that the connection to Graylog is alive before writing the log message. If the connection is not alive, it calls the ensureConnection method to establish a new connection
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger represents a logging client that connects to a Graylog server using TCP.
The Logger struct has the following fields: - conn: The network connection to the Graylog server. - connLock: A mutex used to ensure thread-safe access to the conn field. - address: The address of the Graylog server to connect to. - useTLS: A boolean value indicating whether to use TLS for the connection. - tslConfig: The TLS configuration to use if useTLS is true. - host: The hostname of the client machine.
The Logger struct provides the following methods: - connect: Establishes a connection to the Graylog server. - ensureConnection: Ensures that a connection to the Graylog server is established, reconnecting if necessary. - Log: Sends a log message to the Graylog server.
func NewLogger ¶
func NewLogger(address string, useTSL bool, tslConfig *tls.Config, baseLogProcessor func(fields map[string]interface{}) (int, float64, []byte, error)) (*Logger, error)
NewLogger creates a new Logger.
Example with TLS:
// Load our Root CA certificate
caCert, err := os.ReadFile("/path/to/ca.crt")
if err != nil {
log.Fatal(err)
}
caCertPool := x509.NewCertPool()
caCertPool.AppendCertsFromPEM(caCert)
// Create the credentials and return it
config := &tls.Config{
RootCAs: caCertPool,
InsecureSkipVerify: true,
// Other fields can be filled in as necessary
}
writer, err := NewLogger("localhost:1234", true, config)
This creates a new Logger that will use TLS when connecting to the specified address.
Source Files
Directories