captainslog

package module
v0.1.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 10, 2019 License: MPL-2.0 Imports: 11 Imported by: 9

README

captainslog Build Status Doc Status

Construct, emit, and parse Syslog messages.

Usage

Create a captainslog.SyslogMsg from RF3164 bytes:

b := []byte("<191>2006-01-02T15:04:05.999999-07:00 host.example.org test: engage\n")
msg, err := captainslog.NewSyslogMsgFromBytes(b)
if err != nil {
	panic(err)
}

Create a captainslog.SyslogMsg by setting its fields:

msg := captainslog.NewSyslogMsg()
msg.SetFacility(captainslog.Local7)
msg.SetSeverity(captainslog.Err)

msgTime, err := time.Parse("2006 Jan 02 15:04:05", "2017 Aug 15 16:18:34")
if err != nil {
	t.Error(err)
}

msg.SetTime(msgTime)
msg.SetProgram("myprogram")
msg.SetPid("12")
msg.SetHost("host.example.com")

captainslog.NewSyslogMsg accepts the following functional options (note: these may also be passed to SyslogMsg.Bytes() and SyslogMsg.String):

captainslog.OptionUseLocalFormat tells SyslogMsg.String() and SyslogMsg.Byte() to format the message to be compatible with writing to /dev/log rather than over the wire.

captainslog.OptionUseRemoteFormat tells SyslogMsg.String() and SyslogMsg.Byte() to use wire format for the message instead of local format.

Serialize a captainslog.SyslogMsg to RFC3164 bytes:

b := msg.Bytes()

Create a captainslog.Parser and parse a message:

p := captainslog.NewParser(<options>)
msg, err := p.ParseBytes([]byte(line)

Both captainslog.NewSyslogMsgFromBytes and captainslog.NewParser accept the following functional arguments:

captainslog.OptionNoHostname sets the parser to not expect the hostname as part of the syslog message, and instead ask the host for its hostname.

captainslog.OptionDontParseJSON sets the parser to not parse JSON in the content field of the message. A subsequent call to SyslogMsg.String() or SyslogMsg.Bytes() will then use SyslogMsg.Content for the content field, unless SyslogMsg.JSONValues have been added since the message was originally parsed. If SyslogMsg.JSONValues have been added, the call to SyslogMsg.String() or SyslogMsg.Bytes() will then parse the JSON, and merge the results with the keys in SyslogMsg.JSONVaues.

captainslog.OptionUseGJSONParser uses the tidwall/gjson parser to parse JSON in the content field of the message. This may improve parsing performance.

captainslog.OptionLocation is a helper function to configure the parser to parse time in the given timezone, If the parsed time contains a valid timezone identifier this takes precedence. Default timezone is UTC.

Contibution Guidelines

We use the Collective Code Construction Contract for the development of captainslog. For details, see CONTRIBUTING.md.

License

Copyright 2016 DigitalOcean

Captainslog is released under the Mozilla Public License, version 2.0

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	//ErrBadTime is returned when the time of a message is malformed.
	ErrBadTime = errors.New("Time not found")

	//ErrBadHost is returned when the host of a message is malformed.
	ErrBadHost = errors.New("Host not found")

	//ErrBadTag is returned when the tag of a message is malformed.
	ErrBadTag = errors.New("Tag not found")

	//ErrBadContent is returned when the content of a message is malformed.
	ErrBadContent = errors.New("Content not found")
)
View Source 
var (
	//ErrBadPriority is returned when the priority of a message is malformed.
	ErrBadPriority = errors.New("Priority not found")

	//ErrBadFacility is returned when a facility is not within allowed values.
	ErrBadFacility = errors.New("Facility not found")

	//ErrBadSeverity is returned when a severity is not within allowed values.
	ErrBadSeverity = errors.New("Severity not found")
)

Functions

func CheckForLikelyDateTime added in v0.1.14 

func CheckForLikelyDateTime(buf []byte) bool

CheckForLikelyDateTime checks for a YYYY-MM-DD string. If one is found, we use this to decide that trying to parse a full rsyslog style timestamp is worth the cpu time.

func ContentOptionParseJSON added in v0.1.14 

func ContentOptionParseJSON(opts *contentOpts)

ContentOptionParseJSON will treat the content as a CEE message

func ContentOptionRequireTerminator added in v0.1.14 

func ContentOptionRequireTerminator(opts *contentOpts)

ContentOptionRequireTerminator sets ParseContent to require a \n terminator

func ContentOptionUseGJSON added in v0.1.14 

func ContentOptionUseGJSON(opts *contentOpts)

ContentOptionUseGJSON will use the "github.com/tidwall/gjson" JSON parser, if ContentOptionParseJSON is specified

func OptionDontParseJSON 

func OptionDontParseJSON(p *Parser)

OptionDontParseJSON sets the parser to not parse JSON in the content field of the message. A subsequent call to SyslogMsg.String() or SyslogMsg.Bytes() will then use SyslogMsg.Content for the content field, unless SyslogMsg.JSONValues have been added since the message was originally parsed. If SyslogMsg.JSONValues have been added, the call to SyslogMsg.String() or SyslogMsg.Bytes() will then parse the JSON, and merge the results with the keys in SyslogMsg.JSONVaues.

func OptionLocation added in v0.1.14 

func OptionLocation(location *time.Location) func(*Parser)

OptionLocation is a helper function to configure the parser to parse time in the given timezone, If the parsed time contains a valid timezone identifier this takes precedence. Default timezone is UTC.

func OptionNoHostname 

func OptionNoHostname(p *Parser)

OptionNoHostname sets the parser to not expect the hostname as part of the syslog message, and instead ask the host for its hostname.

func OptionSanitizeProgram added in v0.1.14 

func OptionSanitizeProgram(p *Parser)

OptionSanitizeProgram sets the parser to sanitize the syslog program name if needed. Useful for programs such as /usr/bin/someprogram.

func OptionUseGJSONParser added in v0.1.14 

func OptionUseGJSONParser(p *Parser)

OptionUseGJSONParser uses an alternate parser for CEE JSON content: 

https://github.com/tidwall/gjson

Particularly for logs with significant numbers of JSON fields, this is expected to yield performance gains. This setting has no effect when used with OptionDontParseJSON.

func OptionUseLocalFormat added in v0.1.14 

func OptionUseLocalFormat(s *SyslogMsg)

OptionUseLocalFormat tells SyslogMsg.String() and SyslogMsg.Byte() to format the message to be compatible with writing to /dev/log rather than over the wire.

func OptionUseRemoteFormat added in v0.1.14 

func OptionUseRemoteFormat(s *SyslogMsg)

OptionUseRemoteFormat tells SyslogMsg.String() and SyslogMsg.Byte() to use wire format for the message instead of local format

func ParseCEE added in v0.1.14 

func ParseCEE(buf []byte) (int, string, error)

ParseCEE will try to find a syslog cee cookie at the beginning of the passed in []byte. It returns the offset from the start of the []byte to the end of the cee string, the string, and an error.

func ParseHost added in v0.1.14 

func ParseHost(buf []byte) (int, string, error)

ParseHost will try to find a host at the beginning of the passed in []byte. It will return the offset from the start of the []byte to the end of the host string, a captainslog.Priority, and an error.

func TagOptionSanitizeProgram added in v0.1.14 

func TagOptionSanitizeProgram(opts *tagOpts)

TagOptionSanitizeProgram sets the tag options to sanitize the program name

Types

type Content added in v0.1.14 

type Content struct {
	Content    string
	JSONValues map[string]interface{}
}

Content holds the Content of a syslog message, including the Content as a string, and a struct of the JSONValues of appropriate.

func ParseContent added in v0.1.14 

func ParseContent(buf []byte, options ...func(*contentOpts)) (int, Content, error)

ParseContent will try to find syslog content at the beginning of the passed in []byte. It returns the offset from the start of the []byte to the end of the content, a captainslog.Content, and an error. It accepts two options:

ContentOptionRequireTerminator: if true, if the syslog message does not 

contain a '\n' terminator it will be treated as invalid.

ContentOptionParseJSON: if true, it will treat the content field of the 

syslog message as a CEE message and parse the JSON.

type Facility 

type Facility int

Facility represents a syslog facility code 

const (
	//Kern is the kernel rfc3164 facility.
	Kern Facility = 0

	//User is the user rfc3164 facility.
	User Facility = 1

	// Mail is the mail rfc3164 facility.
	Mail Facility = 2

	// Daemon is the daemon rfc3164 facility.
	Daemon Facility = 3

	// Auth is the auth rfc3164 facility.
	Auth Facility = 4

	// Syslog is the syslog rfc3164 facility.
	Syslog Facility = 5

	// LPR is the printer rfc3164 facility.
	LPR Facility = 6

	// News is a news rfc3164 facility.
	News Facility = 7

	// UUCP is the UUCP rfc3164 facility.
	UUCP Facility = 8

	// Cron is the cron rfc3164 facility.
	Cron Facility = 9

	//AuthPriv is the authpriv rfc3164 facility.
	AuthPriv Facility = 10

	// FTP is the ftp rfc3164 facility.
	FTP Facility = 11

	// Local0 is the local0 rfc3164 facility.
	Local0 Facility = 16

	// Local1 is the local1 rfc3164 facility.
	Local1 Facility = 17

	// Local2  is the local2 rfc3164 facility.
	Local2 Facility = 18

	// Local3 is the local3 rfc3164 facility.
	Local3 Facility = 19

	// Local4 is the local4 rfc3164 facility.
	Local4 Facility = 20

	// Local5 is the local5 rfc3164 facility.
	Local5 Facility = 21

	// Local6 is the local6 rfc3164 facility.
	Local6 Facility = 22

	// Local7 is the local7 rfc3164 facility.
	Local7 Facility = 23
)

func (*Facility) FromString added in v0.1.14 

func (f *Facility) FromString(v string) error

FromString sets the Facility from a string representation.

func (Facility) String 

func (f Facility) String() string

type Parser 

type Parser struct {
	// contains filtered or unexported fields
}

Parser is a parser for syslog messages.

func NewParser 

func NewParser(options ...func(*Parser)) *Parser

NewParser returns a new parser

func (*Parser) ParseBytes 

func (p *Parser) ParseBytes(b []byte) (SyslogMsg, error)

ParseBytes accepts a []byte and tries to parse it into a SyslogMsg.

type Priority 

type Priority struct {
	Priority int
	Facility Facility
	Severity Severity
}

Priority represents the PRI of a rfc3164 message.

func NewPriority 

func NewPriority(f Facility, s Severity) (*Priority, error)

NewPriority calculates a Priority from a Facility and Severity.

func ParsePri added in v0.1.14 

func ParsePri(buf []byte) (int, Priority, error)

ParsePri will try to find a syslog priority at the beginning of the passed in []byte. It will return the offset from the start of the []byte to the end of the priority string, a captainslog.Priority, and an error.

func (*Priority) SetFacility added in v0.1.14 

func (p *Priority) SetFacility(f Facility) error

SetFacility sets the Facility component of the Priority.

func (*Priority) SetSeverity added in v0.1.14 

func (p *Priority) SetSeverity(s Severity) error

SetSeverity sets the Severity component of the Priority.

func (Priority) String added in v0.1.14 

func (p Priority) String() string

String converts the given Priority to a string.

type Severity 

type Severity int

Severity represents a syslog severity code 

const (
	// Emerg is an emergency rfc3164 severity
	Emerg Severity = 0

	// Alert is an alert rfc3164 severity
	Alert Severity = 1

	// Crit is a critical level rfc3164 severity
	Crit Severity = 2

	// Err is an error level rfc3164 severity
	Err Severity = 3

	// Warning is a warning level rfc3164 severity
	Warning Severity = 4

	// Notice is a notice level rfc3164 severity
	Notice Severity = 5

	// Info is an info level rfc3164 severity
	Info Severity = 6

	// Debug is a debug level rfc3164 severity
	Debug Severity = 7
)

func (*Severity) FromString added in v0.1.14 

func (s *Severity) FromString(v string) error

FromString loads a syslog severity from a string representation

func (Severity) String 

func (s Severity) String() string

type SyslogMsg 

type SyslogMsg struct {
	Pri    Priority
	Time   time.Time
	Host   string
	Tag    Tag
	Cee    string
	IsJSON bool
	IsCee  bool

	Content string

	JSONValues map[string]interface{}
	// contains filtered or unexported fields
}

SyslogMsg holds an Unmarshaled rfc3164 message.

func NewSyslogMsg 

func NewSyslogMsg(options ...SyslogMsgOption) SyslogMsg

NewSyslogMsg creates a new empty SyslogMsg.

func NewSyslogMsgFromBytes 

func NewSyslogMsgFromBytes(b []byte, options ...func(*Parser)) (SyslogMsg, error)

NewSyslogMsgFromBytes accepts a []byte containing an RFC3164 message and returns a SyslogMsg. If the original RFC3164 message is a CEE enhanced message, the JSON will be parsed into the JSONValues map[string]inferface{}

Example 
package main

import (
	"fmt"

	"github.com/digitalocean/captainslog"
)

func main() {
	msg, err := captainslog.NewSyslogMsgFromBytes([]byte("<191>2006-01-02T15:04:05.999999-07:00 host.example.org test: engage\n"))
	if err != nil {
		panic(err)
	}

	fmt.Printf("Syslog message was from host %q", msg.Host)
}

Output:

Syslog message was from host "host.example.org"

func (*SyslogMsg) AddTag 

func (s *SyslogMsg) AddTag(key string, value interface{})

AddTag adds a tag to the value at key. If the key exists, the value currently at the key will be overwritten.

func (*SyslogMsg) AddTagArray 

func (s *SyslogMsg) AddTagArray(key string, value interface{}) error

AddTagArray adds a tag to an array of tags at the key. If the key does not already exist, it will create the key and initially it to a []interface{}.

func (*SyslogMsg) Bytes 

func (s *SyslogMsg) Bytes(options ...SyslogMsgOption) []byte

Bytes returns the SyslogMsg as RFC3164 []byte.

func (*SyslogMsg) JSON 

func (s *SyslogMsg) JSON() ([]byte, error)

JSON returns a JSON representation of the message encoded in a []byte. Syslog fields are named with a "syslog_" prefix to avoid potential collision with fields from the message body.

func (*SyslogMsg) SetContent added in v0.1.14 

func (s *SyslogMsg) SetContent(c string) error

SetContent accepts a string to set the content of the SyslogMsg. It will check to see if the string is JSON and try to parse it if so.

func (*SyslogMsg) SetFacility added in v0.1.14 

func (s *SyslogMsg) SetFacility(f Facility) error

SetFacility accepts a captainslog.Facility to set the facility of the SyslogMsg

func (*SyslogMsg) SetHost added in v0.1.14 

func (s *SyslogMsg) SetHost(h string)

SetHost accepts a string to set the host of the SyslogMsg

func (*SyslogMsg) SetPid added in v0.1.14 

func (s *SyslogMsg) SetPid(p string)

SetPid accepts a string to set the pid of the SyslogMsg

func (*SyslogMsg) SetProgram added in v0.1.14 

func (s *SyslogMsg) SetProgram(p string)

SetProgram accepts a string to set the programname of the SyslogMsg

func (*SyslogMsg) SetSeverity added in v0.1.14 

func (s *SyslogMsg) SetSeverity(sv Severity) error

SetSeverity accepts a captainslog.Severity to set the severity of the SyslogMsg

func (*SyslogMsg) SetTime added in v0.1.14 

func (s *SyslogMsg) SetTime(t time.Time)

SetTime accepts a time.Time to set the time of the SyslogMsg

func (*SyslogMsg) String 

func (s *SyslogMsg) String(options ...SyslogMsgOption) string

String returns the SyslogMsg as an RFC3164 string.

type SyslogMsgOption added in v0.1.14 

type SyslogMsgOption func(*SyslogMsg)

SyslogMsgOption can be passed to SyslogMsg.String(), SyslogMsg.Byte(), or NewSyslogMsg to control formatting

type Tag added in v0.1.14 

type Tag struct {
	Program           string
	Pid               string
	HasColon          bool
	StartsWithBracket bool
}

Tag holds the data derviced from a syslog message's tag, including the full tag, the program name and the pid.

func NewTag added in v0.1.14 

func NewTag() *Tag

NewTag constructs a new empty captainslog.Tag

func ParseTag added in v0.1.14 

func ParseTag(buf []byte, options ...func(*tagOpts)) (int, Tag, error)

ParseTag will try to find a syslog tag at the beginning of the passed in []byte. It returns the offset from the start of the []byte to the end of the tag string, a captainslog.Tag, and an error.

func (Tag) String added in v0.1.14 

func (t Tag) String() string

String converts the specified Tag into a string.

type Time added in v0.1.14 

type Time struct {
	Time       time.Time
	TimeFormat string
}

Time holds both the time derviced from a syslog message along with the time format string used to parse it.

func ParseTime added in v0.1.14 

func ParseTime(buf []byte, location *time.Location) (int, Time, error)

ParseTime will try to find a syslog time at the beginning of the passed in []byte. It returns the offset from the start of the []byte to the end of the time string, a captainslog.Time, and an error.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.