natzap

README

Natzap

Natzap is an extension to the logging package zap.

It can send fire-and-forget log messages to a subject, or it can send ACK'd log messages to a stream via JetStream.

License

This package is released under MIT license.

Authors

Created by LuBashQ.

Contributing

I follow the "fork-and-pull" Git workflow.

1. Fork the repo on GitHub
2. Clone the project to your own machine
3. Commit changes to your own branch
4. Push your work back up to your fork
5. Submit a Pull request so that we can review your changes

NOTE: Be sure to merge the latest from "upstream" before making a pull request!

Everyone is welcome to contribute to this project.

Documentation

Overview

Package natzap implements a zap core which sends logs over a NATS connection via NATS core or NATS JetStream.

Index

• type Core
  • func NewCore(enabler zapcore.LevelEnabler, encoder zapcore.Encoder, con *nats.Conn) *Core
  • func (core *Core) Check(entry zapcore.Entry, checked *zapcore.CheckedEntry) *zapcore.CheckedEntry
  • func (core *Core) Sync() error
  • func (core *Core) With(fields []zapcore.Field) zapcore.Core
  • func (core *Core) WithJetStream(stream string) (c *Core, err error)
  • func (core *Core) WithSubject(subject string) *Core
  • func (core *Core) Write(entry zapcore.Entry, fields []zapcore.Field) error

Types

type Core

type Core struct {
	zapcore.LevelEnabler
	// contains filtered or unexported fields
}

Core implements the zapcore.Core interface. Allow logs to be sent via NATS

func NewCore

func NewCore(enabler zapcore.LevelEnabler, encoder zapcore.Encoder, con *nats.Conn) *Core

NewCore creates a new minimal Core instance

Example:

con, _ := nats.Connect(nats.DefaultURL)
encoder := zapcore.NewJSONEncoder(zap.NewDevelopmentEncoderConfig())
core := natzap.NewCore(zapcore.WarnLevel, encoder, con)

func (*Core) Check

func (core *Core) Check(entry zapcore.Entry, checked *zapcore.CheckedEntry) *zapcore.CheckedEntry

Check checks if the log needs to be sent by checking the entry's level. This method is called by zap.

Returns a zapcore.CheckedEntry instance reference with the Core added to it if the log is to be sent, or without the Core instance if it needs to be ignored

func (*Core) Sync

func (core *Core) Sync() error

func (*Core) With

func (core *Core) With(fields []zapcore.Field) zapcore.Core

With clones a Core instance and adds zapcore.Field instances to it

func (*Core) WithJetStream

func (core *Core) WithJetStream(stream string) (c *Core, err error)

WithJetStream adds JestStream communication to a Core instance.

Returns the same Core instance and nil if the stream exists, the Core instance and a nats.ErrStreamNotFound error if the stream was not found, or a nil Core instance and error otherwise.

Note: WithJetStream requires WithSubject to be called before it.

Example:

con, err := nats.Connect(nats.DefaultURL)
if err != nil {
    log.Panic(err)
}
encoder := zapcore.NewJSONEncoder(zap.NewDevelopmentEncoderConfig())
core, err := NewCore(zapcore.WarnLevel, encoder, con).WithSubject("foo.bar").WithJetStream("FOO")
if errors.Is(err, nats.ErrStreamNotFound) {
	_, err = core.js.AddStream(&nats.StreamConfig{
	    Name:     "FOO",
	    Subjects: []string{"foo.bar"},
	})
	if err != nil {
	    log.Fatal(err)
	}
} else if err != nil {
    log.Fatal(err)
}

func (*Core) WithSubject

func (core *Core) WithSubject(subject string) *Core

WithSubject add a subject to a Core instance and returns the same instance

Example:

con, _ := nats.Connect(nats.DefaultURL)
encoder := zapcore.NewJSONEncoder(zap.NewDevelopmentEncoderConfig())
core := natzap.NewCore(zapcore.WarnLevel, encoder, con).WithSubject("foo.bar")

func (*Core) Write

func (core *Core) Write(entry zapcore.Entry, fields []zapcore.Field) error

Write writes a log message to the configured NATS subject or stream. This method is called by zap.

Returns an error when the message cannot be encoded, when the NATS message is not published or when the message does not receive an ACK from the NATS server; otherwise returns nil

Example:

con, err := nats.Connect(nats.DefaultURL)
if err != nil {
  t.Error(err)
}
encoder := zapcore.NewJSONEncoder(zap.NewDevelopmentEncoderConfig())
core := NewCore(zapcore.WarnLevel, encoder, con).WithSubject("foo.bar")
logger := zap.New(core, zap.Development())
logger.Warn("Warning message")
con.Close()