System.Posix.Syslog.UDP

Log messages to syslog over a network via UDP, with protocols such as RFC 5424 or RFC 3164.

The following features are currently missing (but may be provided in future releases):

• validation of string identifiers such as APP-NAME or MSGID
• support for STRUCTURED-DATA (RFC 5424 only)

Syslog UDP packet component datatypes

Re-exports from hsyslog

data Priority

Log messages are prioritized with one of the following levels:

>>> [minBound..maxBound] :: [Priority]
[Emergency,Alert,Critical,Error,Warning,Notice,Info,Debug]

The Ord instance for Priority considers the more urgent level lower than less urgent ones:

>>> Emergency < Debug
True
>>> minimum [minBound..maxBound] :: Priority
Emergency
>>> maximum [minBound..maxBound] :: Priority
Debug

Constructors

Emergency

the system is unusable

Alert

action must be taken immediately

Critical

critical conditions

Error

error conditions

Warning

warning conditions

Notice

normal but significant condition

Info

informational

Debug

debug-level messages

Instances

Bounded Priority

Defined in System.Posix.Syslog.Priority

Methods

minBound :: Priority

maxBound :: Priority

Enum Priority

Defined in System.Posix.Syslog.Priority

Methods

succ :: Priority -> Priority

pred :: Priority -> Priority

toEnum :: Int -> Priority

fromEnum :: Priority -> Int

enumFrom :: Priority -> [Priority]

enumFromThen :: Priority -> Priority -> [Priority]

enumFromTo :: Priority -> Priority -> [Priority]

enumFromThenTo :: Priority -> Priority -> Priority -> [Priority]

Eq Priority

Defined in System.Posix.Syslog.Priority

Methods

(==) :: Priority -> Priority -> Bool

(/=) :: Priority -> Priority -> Bool

Ord Priority

Defined in System.Posix.Syslog.Priority

Methods

compare :: Priority -> Priority -> Ordering

(<) :: Priority -> Priority -> Bool

(<=) :: Priority -> Priority -> Bool

(>) :: Priority -> Priority -> Bool

(>=) :: Priority -> Priority -> Bool

max :: Priority -> Priority -> Priority

min :: Priority -> Priority -> Priority

Read Priority

Defined in System.Posix.Syslog.Priority

Methods

readsPrec :: Int -> ReadS Priority

readList :: ReadS [Priority]

readPrec :: ReadPrec Priority

readListPrec :: ReadPrec [Priority]

Show Priority

Defined in System.Posix.Syslog.Priority

Methods

showsPrec :: Int -> Priority -> ShowS

show :: Priority -> String

showList :: [Priority] -> ShowS

Generic Priority

Defined in System.Posix.Syslog.Priority

Associated Types

type Rep Priority :: Type -> Type

Methods

from :: Priority -> Rep Priority x

to :: Rep Priority x -> Priority

type Rep Priority

Defined in System.Posix.Syslog.Priority

type Rep Priority = D1 (MetaData "Priority" "System.Posix.Syslog.Priority" "hsyslog-5.0.2-4YPEwpeEGKZ6PP1UUUwS4g" False) (((C1 (MetaCons "Emergency" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Alert" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "Critical" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Error" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "Warning" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Notice" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "Info" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Debug" PrefixI False) (U1 :: Type -> Type))))

data Facility

Syslog distinguishes various system facilities. Most applications should log in USER.

Constructors

Kernel

kernel messages

User

user-level messages (default unless set otherwise)

Mail

mail system

News

network news subsystem

UUCP

UUCP subsystem

Daemon

system daemons

Auth

security and authorization messages

Cron

clock daemon

LPR

line printer subsystem

Local0

reserved for local use

Local1

reserved for local use

Local2

reserved for local use

Local3

reserved for local use

Local4

reserved for local use

Local5

reserved for local use

Local6

reserved for local use

Local7

reserved for local use

Instances

Bounded Facility

Defined in System.Posix.Syslog.Facility

Methods

minBound :: Facility

maxBound :: Facility

Enum Facility

Defined in System.Posix.Syslog.Facility

Methods

succ :: Facility -> Facility

pred :: Facility -> Facility

toEnum :: Int -> Facility

fromEnum :: Facility -> Int

enumFrom :: Facility -> [Facility]

enumFromThen :: Facility -> Facility -> [Facility]

enumFromTo :: Facility -> Facility -> [Facility]

enumFromThenTo :: Facility -> Facility -> Facility -> [Facility]

Eq Facility

Defined in System.Posix.Syslog.Facility

Methods

(==) :: Facility -> Facility -> Bool

(/=) :: Facility -> Facility -> Bool

Read Facility

Defined in System.Posix.Syslog.Facility

Methods

readsPrec :: Int -> ReadS Facility

readList :: ReadS [Facility]

readPrec :: ReadPrec Facility

readListPrec :: ReadPrec [Facility]

Show Facility

Defined in System.Posix.Syslog.Facility

Methods

showsPrec :: Int -> Facility -> ShowS

show :: Facility -> String

showList :: [Facility] -> ShowS

Generic Facility

Defined in System.Posix.Syslog.Facility

Associated Types

type Rep Facility :: Type -> Type

Methods

from :: Facility -> Rep Facility x

to :: Rep Facility x -> Facility

type Rep Facility

Defined in System.Posix.Syslog.Facility

type Rep Facility = D1 (MetaData "Facility" "System.Posix.Syslog.Facility" "hsyslog-5.0.2-4YPEwpeEGKZ6PP1UUUwS4g" False) ((((C1 (MetaCons "Kernel" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "User" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "Mail" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "News" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "UUCP" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Daemon" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "Auth" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Cron" PrefixI False) (U1 :: Type -> Type)))) :+: (((C1 (MetaCons "LPR" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Local0" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "Local1" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Local2" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "Local3" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Local4" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "Local5" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "Local6" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Local7" PrefixI False) (U1 :: Type -> Type))))))

Newtypes for various String/Int values

Refer to RFC 5424 section 6.2 as to the purpose of each.

newtype AppName

Constructors

AppName ByteString

see APP-NAME

Instances

Eq AppName

Defined in System.Posix.Syslog.UDP

Methods

(==) :: AppName -> AppName -> Bool

(/=) :: AppName -> AppName -> Bool

Show AppName

Defined in System.Posix.Syslog.UDP

Methods

showsPrec :: Int -> AppName -> ShowS

show :: AppName -> String

showList :: [AppName] -> ShowS

newtype HostName

Constructors

HostName ByteString

see HOSTNAME; fetch via getHostName

Instances

Eq HostName

Defined in System.Posix.Syslog.UDP

Methods

(==) :: HostName -> HostName -> Bool

(/=) :: HostName -> HostName -> Bool

Show HostName

Defined in System.Posix.Syslog.UDP

Methods

showsPrec :: Int -> HostName -> ShowS

show :: HostName -> String

showList :: [HostName] -> ShowS

newtype PriVal

Constructors

PriVal CInt

see PRI; construct via maskedPriVal

Instances

Eq PriVal

Defined in System.Posix.Syslog.UDP

Methods

(==) :: PriVal -> PriVal -> Bool

(/=) :: PriVal -> PriVal -> Bool

Show PriVal

Defined in System.Posix.Syslog.UDP

Methods

showsPrec :: Int -> PriVal -> ShowS

show :: PriVal -> String

showList :: [PriVal] -> ShowS

newtype ProcessID

Constructors

ProcessID ByteString

see PROCID; fetch via getProcessId

Instances

Eq ProcessID

Defined in System.Posix.Syslog.UDP

Methods

(==) :: ProcessID -> ProcessID -> Bool

(/=) :: ProcessID -> ProcessID -> Bool

Show ProcessID

Defined in System.Posix.Syslog.UDP

Methods

showsPrec :: Int -> ProcessID -> ShowS

show :: ProcessID -> String

showList :: [ProcessID] -> ShowS

newtype MessageID

Constructors

MessageID ByteString

see MSGID

Instances

Eq MessageID

Defined in System.Posix.Syslog.UDP

Methods

(==) :: MessageID -> MessageID -> Bool

(/=) :: MessageID -> MessageID -> Bool

Show MessageID

Defined in System.Posix.Syslog.UDP

Methods

showsPrec :: Int -> MessageID -> ShowS

show :: MessageID -> String

showList :: [MessageID] -> ShowS

Type aliases

What syslog refers to as Priority, RFC 5424 calls Severity.

type Severity = Priority

type SeverityMask = [Priority]

Structured Data

Currently unsupported; a placeholder for future use.

data StructuredData

Constructors

StructuredData

see STRUCTURED-DATA (unsupported)

The easy Haskell API to syslog via UDP

initSyslog :: SyslogConfig -> IO SyslogFn

Return a function that logs to syslog via UDP.

{-# LANGUAGE OverloadedStrings #-}

import System.Posix.Syslog.UDP

main = do
  syslog <- defaultConfig >>= initSyslog
  putStrLn "huhu"
  syslog USER Debug "huhu"

This makes no assumptions about socket connection status or endpoint availability. Any errors while sending are silently ignored.

type SyslogFn

Arguments

 = Facility

facility to log to

-> Severity

severity under which to log

-> Text

message body

-> IO ()

The type of function returned by initSyslog.

data SyslogConfig

Configuration options for connecting and logging to your syslog socket.

Constructors

SyslogConfig

Fields

• appName :: !AppName

  see APP-NAME; fetch via getAppName

• hostName :: !HostName

  see HOSTNAME; fetch via getHostName

• processId :: !ProcessID

  see PROCID; fetch via getProcessId

• severityMask :: !SeverityMask

  whitelist of priorities of logs to send

• address :: !AddrInfo

  where to send the syslog packets; construct via resolveUdpAddress or find via getAddrInfo

• protocol :: Protocol

  protocol for formatting the message, such as rfc5424Protocol or rfc3164Protocol

• onException :: SomeException -> IO ()

  custom exception handler

defaultConfig :: IO SyslogConfig

A convenient default config for connecting to localhost. Provided for development/testing purposes.

localhost :: AddrInfo

The default IPv4 address/port for syslog on a local machine. Provided for development/testing purposes.

Common protocols for use with SyslogConfig

type Protocol = PriVal -> UTCTime -> HostName -> AppName -> ProcessID -> Text -> ByteString

rfc5424Protocol :: Protocol

rfc3164Protocol :: Protocol

rsyslogProtocol :: Protocol

Manually constructing syslog UDP packets

rfc5424Packet

Arguments

:: FormatTime t

=> PriVal

see PRI; construct via maskedPriVal

-> Maybe t

time of message, converted to TIMESTAMP

-> Maybe HostName

see HOSTNAME; fetch via getHostName

-> Maybe AppName

see APP-NAME; fetch via getAppName

-> Maybe ProcessID

see PROCID; fetch via getProcessId

-> Maybe MessageID

see MSGID

-> Maybe StructuredData

see STRUCTURED-DATA (unsupported)

-> Text

see MSG

-> ByteString

Construct a syslog UDP packet as dictated by RFC 5424. Note that fields in a syslog packet are whitespace-delineated, so don't allow whitespace in anything but the log message!

rfc3164Packet

Arguments

:: FormatTime t

=> PriVal

see PRI; construct via maskedPriVal

-> t

time of message, converted to TIMESTAMP in HEADER

-> HostName

the HOSTNAME of the HEADER; fetch via getHostName

-> AppName

the program name in the TAG portion of the MSG; fetch via getAppName

-> ProcessID

the process identifier in the TAG portion of the MSG; fetch via getProcessId

-> Text

the CONTENT portion of the MSG

-> ByteString

Construct a syslog UDP packet as dictated by RFC 3164. Note that fields in a syslog packet are whitespace-delineated, so don't allow whitespace in anything but the log message!

rsyslogPacket :: FormatTime t => PriVal -> t -> HostName -> AppName -> ProcessID -> Text -> ByteString

Recommended rsyslog template RSYSLOG_ForwardFormat. Same fields as RFC 3164, but with an RFC 3339 high-precision timestamp.

Miscellaneous utilities

getAppName :: IO AppName

getHostName :: IO HostName

getProcessId :: IO ProcessID

maskedPriVal :: SeverityMask -> Facility -> Severity -> Maybe PriVal

Construct a PRI. Nothing indicates that the severities are fully masked, and so no packet should be sent.

resolveUdpAddress :: Integral n => String -> n -> IO (Maybe AddrInfo)

Obtain an IPv4 AddrInfo for your SyslogConfig from a hostname (or IPv4 address) and port. Sets the address protocol to Datagram.

rfc3339Timestamp :: FormatTime t => t -> ByteString

An RFC 3339 high-precision timestamp.