-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Type, render and parse the df1 hierarchical structured log format -- -- Type, render and parse logs in df1 format, a hierarchical -- structured log format that is easy for humans and fast for computers. @package df1 @version 0.4 module Df1.Render -- | Renders a Log on its own line. Doesn't include a trailing -- newline character. -- -- For example: -- -- 
--   2019-11-15T18:05:54.949470902Z NOTICE Welcome to my program!
--   2019-11-15T18:05:54.949623731Z /initialization NOTICE Starting web server
--   2019-11-15T18:05:54.949630205Z /initialization ALERT Disk is almost full!!!
--   2019-11-15T18:05:54.949640299Z /server port=80 INFO Listening for new clients
--   2019-11-15T18:05:54.949652133Z /server port=80 /handler client-address=10.0.0.8 INFO Connection established
--   2019-11-15T18:05:54.949664482Z /server port=80 /handler client-address=10.0.0.8 WARNING user error (Oops!)
--
log :: Log -> Builder -- | Like log, but with ANSI colors. logColorANSI :: Log -> Builder -- | Escaping rules for Key: -- -- -- -- The output is encoded as UTF-8. key :: Key -> Builder -- | Escaping rules for Segment: -- -- -- -- The output is encoded as UTF-8. message :: Message -> Builder -- | Renders YYYY-MM-DDThh:mm:ss.sssssssssZ (nanosecond precision). -- -- The rendered string is 30 characters long, and it's encoded as -- ASCII/UTF-8. iso8601 :: SystemTime -> Builder -- | Escaping rules for Segment: -- -- -- -- The output is encoded as UTF-8. segment :: Segment -> Builder -- | Escaping rules for Value: -- -- -- -- The output is encoded as UTF-8. value :: Value -> Builder module Df1.Parse -- | If sucessful, parsing will stop after the first CR or LF newline -- marker if any, otherwise it will consume all input. log :: Parser Log -- | This module exports tools for typing, parsing, and rendering logs in -- the df1 hierarchical structured logging format. -- -- Consider this a preview release: The API is likely to stay stable, but -- extensive testing, formalization and tooling is due. -- -- Draft BNF specification of the df1 log line format (TO -- BE VERIFIED): -- -- 
--   <log> ::= <timestamp> " " <path> " " <level> " " <message>
--   <path> ::= <path1> " " <path> | <path1> | ""
--   <path1> ::= "/" <segment> | <key> "=" <value>
--   <segment> ::= zero or more characters until " "
--   <key> ::= zero or more characters until (" " | "=")
--   <value> ::= zero or more characters until " "
--   <message> ::= zero or more characters until LF ("\n")
--   <level> ::= "DEBUG" | "INFO" | "NOTICE" | "WARNING" | "ERROR" | "CRITICAL" | "ALERT" | "EMERGENCY"
--   <timestamp> ::= <year> "-" <month> "-" <day> "T" <hour> ":" <minute> ":" <second> "." <nanosecond> "Z"
--   <year> ::= <digit> <digit> <digit> <digit>
--   <month> ::= <digit> <digit>
--   <day> ::= <digit> <digit>
--   <hour> ::= <digit> <digit>
--   <minute> ::= <digit> <digit>
--   <second> ::= <digit> <digit>
--   <nanosecond> ::= <digit> <digit> <digit> <digit> <digit> <digit> <digit> <digit> <digit>
--   <digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
--
module Df1 data Log Log :: !SystemTime -> !Level -> !Seq Path -> !Message -> Log -- | First known timestamp when the log was generated. -- -- We use SystemTime rather than UTCTime because it is -- cheaper to obtain and to render. You can use systemToUTCTime to -- convert it if necessary. [log_time] :: Log -> !SystemTime -- | Importance level of the logged message. [log_level] :: Log -> !Level -- | Path where the logged message was created from. -- -- The leftmost Path is the closest to the root. The rightmost -- Path is the one closest to where the log was generated. -- -- An empty Seq is acceptable, conveying the idea of the -- “root path”. [log_path] :: Log -> !Seq Path -- | Human-readable message itself. [log_message] :: Log -> !Message -- | Importance of the logged message. -- -- These levels, listed in increasing order of importance, correspond to -- the levels used by syslog(3). data Level -- | Message intended to be useful only when deliberately debugging a -- program. Debug :: Level -- | Informational message. Info :: Level -- | A condition that is not an error, but should possibly be handled -- specially. Notice :: Level -- | A warning condition, such as an exception being gracefully handled or -- some missing configuration setting being assigned a default value. Warning :: Level -- | Error condition, such as an unhandled exception. Error :: Level -- | Critical condition that could result in system failure, such as a disk -- running out of space. Critical :: Level -- | A condition that should be corrected immediately, such as a corrupted -- database. Alert :: Level -- | System is unusable. Emergency :: Level -- | Path represents the hierarchical structure of logged messages. -- -- For example, consider a df1 log line as like the following: -- -- 
--   1999-12-20T07:11:39.230553031Z /foo x=a y=b /bar /qux z=c z=d WARNING Something
--
-- -- For that line, the log_path attribute of the Log -- datatype will contain the following: -- -- 
--   [ Push (segment "foo")
--   , Attr (key "x") (value "a")
--   , Attr (key "y") (value "b")
--   , Push (segment "bar")
--   , Push (segment "qux")
--   , Attr (key "z") (value "c")
--   , Attr (key "z") (value "d")
--   ] :: Seq Path
--
-- -- Please notice that [] :: Seq Path is a valid -- path insofar as df1 is concerned, and that Attr and -- Push can be juxtapositioned in any order. data Path Push :: !Segment -> Path Attr :: !Key -> !Value -> Path -- | A path segment. -- -- If you have the OverloadedStrings GHC extension enabled, you -- can build a Segment using a string literal: -- -- 
--   "foo" :: Segment
--
-- -- Otherwise, you can use fromString or segment. -- -- Notice that "" :: Segment is acceptable, and will be -- correctly rendered and parsed back. data Segment unSegment :: Segment -> Text -- | Convert an arbitrary type to a Segment. -- -- You are encouraged to create custom ToSegment instances for -- your types making sure you avoid rendering sensitive details such as -- passwords, so that they don't accidentally end up in logs. -- -- Any characters that need to be escaped for rendering will be -- automatically escaped at rendering time. You don't need to escape them -- here. class ToSegment a segment :: ToSegment a => a -> Segment -- | An attribute key (see Attr). -- -- If you have the OverloadedStrings GHC extension enabled, you -- can build a Key using a string literal: -- -- 
--   "foo" :: Key
--
-- -- Otherwise, you can use fromString or key. -- -- Notice that "" :: Key is acceptable, and will be -- correctly rendered and parsed back. data Key unKey :: Key -> Text -- | Convert an arbitrary type to a Key. -- -- You are encouraged to create custom ToKey instances for your -- types making sure you avoid rendering sensitive details such as -- passwords, so that they don't accidentally end up in logs. -- -- Any characters that need to be escaped for rendering will be -- automatically escaped at rendering time. You don't need to escape them -- here. class ToKey a key :: ToKey a => a -> Key -- | An attribute value (see Attr). -- -- If you have the OverloadedStrings GHC extension enabled, you -- can build a Value using a string literal: -- -- 
--   "foo" :: Value
--
-- -- Otherwise, you can use fromString or value. -- -- Notice that "" :: Value is acceptable, and will be -- correctly rendered and parsed back. data Value unValue :: Value -> Text -- | Convert an arbitrary type to a Value. -- -- You are encouraged to create custom ToValue instances for your -- types making sure you avoid rendering sensitive details such as -- passwords, so that they don't accidentally end up in logs. -- -- Any characters that need to be escaped for rendering will be -- automatically escaped at rendering time. You don't need to escape them -- here. class ToValue a value :: ToValue a => a -> Value -- | A message text. -- -- If you have the OverloadedStrings GHC extension enabled, you -- can build a Message using a string literal: -- -- 
--   "foo" :: Message
--
-- -- Otherwise, you can use fromString or message. -- -- Notice that "" :: Message is acceptable, and will be -- correctly rendered and parsed back. data Message unMessage :: Message -> Text -- | Convert an arbitrary type to a Message. -- -- You are encouraged to create custom ToMessage instances for -- your types making sure you avoid rendering sensitive details such as -- passwords, so that they don't accidentally end up in logs. -- -- Any characters that need to be escaped for rendering will be -- automatically escaped at rendering time. You don't need to escape them -- here. class ToMessage a message :: ToMessage a => a -> Message