README
¶
Go Auditrail
Provides a simple interface for logging audit events in Go with support for multiple backends such as file, Elasticsearch, and more.
Installation
go get github.com/auditrail/go-auditrail
Usage
package main
import (
"context"
"fmt"
"os"
"github.com/botchris/go-auditrail"
)
func main() {
// Create a new client
client := auditrail.NewFileLogger(os.Stdout)
// Log a message
entry := auditrail.NewEntry("john", "order.deleted", "ordersService")
if err := client.Log(context.TODO(), entry); err != nil {
fmt.Println(err.Error())
}
}
Documentation
¶
Overview ¶
Package auditrail provides basic audit log functionality and definitions for logging actions and events.
Index ¶
- Variables
- type DropHandlerFunc
- type Entry
- func (e *Entry) AppendDetails(key string, value interface{}) *Entry
- func (e *Entry) GetAction() string
- func (e *Entry) GetActor() string
- func (e *Entry) GetAuthMethod() string
- func (e *Entry) GetCausationID() string
- func (e *Entry) GetCorrelationID() string
- func (e *Entry) GetDetails() map[string]interface{}
- func (e *Entry) GetIdempotencyID() string
- func (e *Entry) GetModule() string
- func (e *Entry) GetOccurredAt() time.Time
- func (e *Entry) MarshalJSON() ([]byte, error)
- func (e *Entry) UnmarshalJSON(data []byte) error
- func (e *Entry) WithAuthMethod(method string) *Entry
- func (e *Entry) WithCausation(causationID string) *Entry
- func (e *Entry) WithCorrelation(correlationID string) *Entry
- func (e *Entry) WithIdempotency(idempotencyID string) *Entry
- func (e *Entry) WithOccurredAt(when time.Time) *Entry
- type ExponentialBackoffConfig
- type KinesisAPI
- type Logger
- func NewDiscardLogger() Logger
- func NewElasticLogger(index string, client *elasticsearch.Client) Logger
- func NewFileLogger(fd *os.File) (Logger, error)
- func NewFilePathLogger(path string) (Logger, error)
- func NewKinesisLogger(client KinesisAPI, streamName string) (Logger, error)
- func NewQueue(dst Logger, options ...QueueOption) Logger
- func NewRetryer(dst Logger, opts ...RetryerOption) Logger
- type MemoryLogger
- func (s *MemoryLogger) Close() error
- func (s *MemoryLogger) Closed() <-chan struct{}
- func (s *MemoryLogger) Flush()
- func (s *MemoryLogger) Has(idempotencyID ...string) bool
- func (s *MemoryLogger) IsClosed() bool
- func (s *MemoryLogger) Log(_ context.Context, event *Entry) error
- func (s *MemoryLogger) Size() int
- func (s *MemoryLogger) Trail() []*Entry
- type QueueOption
- type RetryStrategy
- type RetryerOption
Constants ¶
This section is empty.
Variables ¶
var DefaultExponentialBackoffConfig = ExponentialBackoffConfig{ Base: time.Second, Factor: time.Second, Max: 20 * time.Second, }
DefaultExponentialBackoffConfig provides a default configuration for exponential backoff.
var ErrTrailClosed = fmt.Errorf("trail is closed")
ErrTrailClosed is returned when the queue is closed.
Functions ¶
This section is empty.
Types ¶
type DropHandlerFunc ¶
DropHandlerFunc is a function that will be called when a message is dropped from the queue.
type Entry ¶
type Entry struct {
// contains filtered or unexported fields
}
Entry represents an audit log event.
This struct is not safe for concurrent write access.
func NewEntry ¶
NewEntry creates a new log entry with the given actor, action, and module.
By default, the following fields are set:
- The time of the event is set to the current time, use Entry.WithOccurredAt to override it to a different value.
- The IdempotencyID is set to randomly generated value, use Entry.WithIdempotency to override it to a different value.
func (*Entry) AppendDetails ¶
AppendDetails adds a key-value pair to the details of the event.
func (*Entry) GetAuthMethod ¶ added in v0.0.4
GetAuthMethod returns the authentication method of the event.
func (*Entry) GetCausationID ¶ added in v0.0.4
GetCausationID returns the causation ID of the event.
func (*Entry) GetCorrelationID ¶ added in v0.0.4
GetCorrelationID returns the correlation ID of the event.
func (*Entry) GetDetails ¶ added in v0.0.4
GetDetails returns the details of the event.
func (*Entry) GetIdempotencyID ¶ added in v0.0.4
GetIdempotencyID returns the idempotency ID of the event.
func (*Entry) GetOccurredAt ¶ added in v0.0.4
GetOccurredAt returns the time of the event.
func (*Entry) MarshalJSON ¶ added in v0.0.4
MarshalJSON marshals the log entry to JSON.
func (*Entry) UnmarshalJSON ¶ added in v0.0.4
UnmarshalJSON unmarshals the log entry from JSON.
func (*Entry) WithAuthMethod ¶
WithAuthMethod sets the authentication method of the event.
func (*Entry) WithCausation ¶
WithCausation sets the causation ID of the event.
func (*Entry) WithCorrelation ¶
WithCorrelation sets the correlation ID of the event.
func (*Entry) WithIdempotency ¶
WithIdempotency sets the idempotency ID of the event.
type ExponentialBackoffConfig ¶
type ExponentialBackoffConfig struct {
// Base is the minimum bound for backing off after failure.
Base time.Duration
// Factor sets the amount of time by which the backoff grows with each
// failure.
Factor time.Duration
// Max is the absolute maximum bound for a single backoff.
Max time.Duration
}
ExponentialBackoffConfig configures backoff parameters.
Note that these parameters operate on the upper bound for choosing a random value. For example, at Base=1s, a random value in [0,1s) will be chosen for the backoff value.
type KinesisAPI ¶
type KinesisAPI interface {
PutRecord(ctx context.Context, params *kinesis.PutRecordInput, optFns ...func(*kinesis.Options)) (*kinesis.PutRecordOutput, error)
}
KinesisAPI captures the kinesis client part that we need.
type Logger ¶
type Logger interface {
// Log writes the given log entry to the audit log, returning an error
// indicates that the log entry could not be written and should be retried.
Log(context.Context, *Entry) error
// Close closes logger and releases any resources.
Close() error
// Closed returns a channel that is closed when the logger is closed.
Closed() <-chan struct{}
// IsClosed returns true if the logger is closed.
IsClosed() bool
}
Logger trail logger to which audit logs are written.
func NewDiscardLogger ¶
func NewDiscardLogger() Logger
NewDiscardLogger returns a logger that discards all log entries.
func NewElasticLogger ¶
NewElasticLogger creates a new ElasticSearch logger.
func NewFileLogger ¶
NewFileLogger builds a new logger that writes log entries to the given file descriptor.
The file descriptor must be writable. If it is not, an error will be returned. You can use os.Stdout or os.Stderr as file descriptors.
The file descriptor must be closed by the caller.
func NewFilePathLogger ¶
NewFilePathLogger builds a new logger that writes log entries to a file at the given path.
If the file does not exist, it will be created.
func NewKinesisLogger ¶
func NewKinesisLogger(client KinesisAPI, streamName string) (Logger, error)
NewKinesisLogger builds a new logger that writes log entries to a Kinesis stream as JSON objects separated by newlines.
func NewQueue ¶
func NewQueue(dst Logger, options ...QueueOption) Logger
NewQueue builds a new logger queue which provides a buffer for entries to be processed asynchronously. See options for configuration.
func NewRetryer ¶
func NewRetryer(dst Logger, opts ...RetryerOption) Logger
NewRetryer creates a new retryer that will retry failed log writes using the provided strategy.
type MemoryLogger ¶
type MemoryLogger struct {
// contains filtered or unexported fields
}
MemoryLogger is a test spy that records all the logs it receives for later inspection. Useful for testing.
This logger is safe for concurrent use and can be shared across multiple goroutines.
func NewMemoryLogger ¶
func NewMemoryLogger() *MemoryLogger
NewMemoryLogger creates a new MemoryLogger.
func (*MemoryLogger) Close ¶
func (s *MemoryLogger) Close() error
func (*MemoryLogger) Closed ¶
func (s *MemoryLogger) Closed() <-chan struct{}
func (*MemoryLogger) Has ¶
func (s *MemoryLogger) Has(idempotencyID ...string) bool
Has whether the logger has recorded all the logs with the given idempotency IDs.
func (*MemoryLogger) IsClosed ¶
func (s *MemoryLogger) IsClosed() bool
func (*MemoryLogger) Log ¶
func (s *MemoryLogger) Log(_ context.Context, event *Entry) error
Log records the log event.
func (*MemoryLogger) Size ¶
func (s *MemoryLogger) Size() int
Size returns the number of logs recorded.
func (*MemoryLogger) Trail ¶
func (s *MemoryLogger) Trail() []*Entry
Trail returns all the logs recorded.
type QueueOption ¶
type QueueOption func(options *queueOptions)
QueueOption is a function that configures a queue.
func WithQueueDropHandler ¶
func WithQueueDropHandler(handler DropHandlerFunc) QueueOption
WithQueueDropHandler sets a function that will be called when a message is dropped. The function is called with the dropped message and the error that caused the drop.
func WithQueueThroughput ¶
func WithQueueThroughput(throughput int) QueueOption
WithQueueThroughput controls the number of concurrent workers that will process messages from the queue. If throughput is less than or equal to zero, it will be set to 1.
func WithQueueTimeout ¶
func WithQueueTimeout(timeout time.Duration) QueueOption
WithQueueTimeout controls the maximum amount of time a worker will wait for the target logger to process a message. If the timeout is exceeded, the message will be dropped. If the timeout is less than or equal to zero, it will be set to 3 seconds.
type RetryStrategy ¶
type RetryStrategy interface {
// Proceed is called before every message send. If proceed returns a
// positive, non-zero integer, the retryer will back off by the provided
// duration.
//
// A message is provided, by may be ignored.
Proceed(*Entry) time.Duration
// Failure reports a failure to the strategy. If this method returns true,
// the message should be dropped.
Failure(*Entry, error) bool
// Success should be called when a message is sent successfully.
Success(*Entry)
}
RetryStrategy defines a strategy for retrying trail writes.
All methods should be goroutine safe.
func NewBreakerStrategy ¶
func NewBreakerStrategy(threshold int, backoff time.Duration) RetryStrategy
NewBreakerStrategy returns a breaker that will backoff after the threshold has been tripped. A Breaker is thread safe and may be shared by many goroutines.
func NewExponentialBackoff ¶
func NewExponentialBackoff(config ExponentialBackoffConfig) RetryStrategy
NewExponentialBackoff returns an exponential backoff strategy with the desired config. If config is nil, the default is returned.
type RetryerOption ¶
type RetryerOption func(options *retryer)
RetryerOption is a function that configures a retryer.
func WithRetryDropHandler ¶
func WithRetryDropHandler(handler DropHandlerFunc) RetryerOption
WithRetryDropHandler configures the drop handler for the retryer. If handler is nil, a no-op handler is used.
func WithRetryStrategy ¶
func WithRetryStrategy(strategy RetryStrategy) RetryerOption
WithRetryStrategy configures the retry strategy for the retryer. If strategy is nil, a default exponential backoff strategy is used.
Source Files
Directories