auditlog

README

README

The log/auditlog package is used by Go services to log audit messages to file.

If the file is inaccessible for writing or encounters unexpected errors, the audit messages will be directed to STDOUT instead.

How To Use

To use the log package you first need to import the library into your project:

import "github.com/IOTechSystems/go-mod-edge-utils/pkg/log/auditlog"

To send an audit message to a file, you first need to create a Logger with service name, desired coverage level, desired io.Writer (write to file as default), configurations about log rotation, and then you can send audit messages (indicating the coverage level of the message using one of the various log function calls).

Audit messages can be logged as Base, Advanced, or Full.

logger := auditlog.InitLogger("SERVICE_NAME", "FULL", nil, auditlog.Configuration{})
	details := map[string]interface{}{
		"key1": "value1",
		"key2": "value2",
	}

logger.LogFull(auditlog.SeverityNormal, "Admin", "auditlog.ActionTypeLogin", "description", nil)
logger.LogAdvanced(auditlog.SeverityNormal, "Admin", auditlog.ActionTypeLogin, "description", details)
logger.LogBase(auditlog.SeverityCritical, "Admin", auditlog.ActionTypeDelete, "description", details)

An audit message is composed of the following elements.

Severity

The supported severity levels are Normal, Warning, and Critical.

Actor

An actor is the entity that initiated the action that is being audited.

Action Type

There are various action types that can be specified. The action type is the type of action that is being audited.

Description

The description is a string that describes the action that is being audited.

Details

The details is a map of key-value pairs that provide additional information about the action that is being audited.

Documentation

Index

• Constants
• type ActionType
• type Configuration
• type Logger
  • func InitLogger(owningServiceName string, coverageLevel string, logWriter io.Writer, ...) Logger
• type Severity

Constants

const (
	TimestampKey   = "ts"
	ActorKey       = "actor"
	ActionKey      = "action"
	DescriptionKey = "desc"
	DetailsKey     = "details"
	SeverityKey    = "severity"
)

const (
	BaseCoverage     = "BASE"
	AdvancedCoverage = "ADVANCED"
	FullCoverage     = "FULL"
)

Constants of coverage level which can be used to label and group audit log by their coverage level.

const (
	FullCoverageLevel     = slog.Level(-8)
	AdvancedCoverageLevel = slog.Level(2)
	BaseCoverageLevel     = slog.Level(12)
)

Leverage the slog level to define the coverage levels for easily setting the level and filtering. The higher the level, the more general the event. Those pre-defined levels can be found in the slog package (https://pkg.go.dev/log/slog#Level).

Types

type ActionType

type ActionType string

ActionType is a categorical identifier used to give high-level insight as to the action type.

const (
	ActionTypeCreate   ActionType = "CREATE"
	ActionTypeDelete   ActionType = "DELETE"
	ActionTypeDownload ActionType = "DOWNLOAD"
	ActionTypeLogin    ActionType = "LOGIN"
	ActionTypeLogout   ActionType = "LOGOUT"
	ActionTypeUnknown  ActionType = "UNKNOWN"
	ActionTypeUpdate   ActionType = "UPDATE"
	ActionTypeUpload   ActionType = "UPLOAD"
	ActionTypeView     ActionType = "VIEW"
)

Constant ActionType identifiers which can be used to label and group audit log by their action type.

type Configuration

type Configuration struct {
	// StorageDir is the directory to write logs to.
	StorageDir string

	// Filename is the file to write logs to.  Backup log files will be retained
	// in the same directory.
	FileName string

	// MaxSize is the maximum size in megabytes of the log file before it gets
	// rotated. It defaults to 100 megabytes.
	MaxSize int

	// MaxAge is the maximum number of days to retain old log files based on the
	// timestamp encoded in their filename.  Note that a day is defined as 24
	// hours and may not exactly correspond to calendar days due to daylight
	// savings, leap seconds, etc. The default is not to remove old log files
	// based on age.
	MaxAge int

	// MaxBackups is the maximum number of old log files to retain.  The default
	// is to retain all old log files (though MaxAge may still cause them to get
	// deleted.)
	MaxBackups int
}

type Logger

type Logger interface {
	// LogBase adds an audit log entry to the log writer with base coverage level
	LogBase(severity Severity, actor string, action ActionType, description string, details any)
	// LogAdvanced adds an audit log entry to the log writer with advanced coverage level
	LogAdvanced(severity Severity, actor string, action ActionType, description string, details any)
	// LogFull adds an audit log entry to the log writer with full coverage level
	LogFull(severity Severity, actor string, action ActionType, description string, details any)
}

Logger defines the interface for logging operations.

func InitLogger

func InitLogger(owningServiceName string, coverageLevel string, logWriter io.Writer, config Configuration) Logger

InitLogger creates an instance of Logger

type Severity

type Severity string

Severity is a categorical identifier used to give high-level insight as to the severity type.

const (
	SeverityCritical Severity = "CRITICAL"
	SeverityNormal   Severity = "NORMAL"
	SeverityMinor    Severity = "MINOR"
)

Constant Severity identifiers which can be used to label and group audit log by their severity.