| Safe Haskell | Safe |
|---|---|
| Language | Haskell2010 |
Df1
Description
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"Synopsis
- data Log = Log {
- log_time :: !SystemTime
- log_level :: !Level
- log_path :: !(Seq Path)
- log_message :: !Message
- data Level
- data Path
- data Segment
- unSegment :: Segment -> Text
- class ToSegment a where
- data Key
- unKey :: Key -> Text
- class ToKey a where
- data Value
- unValue :: Value -> Text
- class ToValue a where
- data Message
- unMessage :: Message -> Text
- class ToMessage a where
- parse :: Parser Log
- render :: Log -> Builder
- renderColor :: Log -> Builder
Types
Constructors
| Log | |
Fields
| |
Importance of the logged message.
These levels, listed in increasing order of importance, correspond to the levels used by syslog(3).
Constructors
| Debug | Message intended to be useful only when deliberately debugging a program. |
| Info | Informational message. |
| Notice | A condition that is not an error, but should possibly be handled specially. |
| Warning | A warning condition, such as an exception being gracefully handled or some missing configuration setting being assigned a default value. |
| Error | Error condition, such as an unhandled exception. |
| Critical | Critical condition that could result in system failure, such as a disk running out of space. |
| Alert | A condition that should be corrected immediately, such as a corrupted database. |
| Emergency | System is unusable. |
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") ] ::SeqPath
Please notice that [] :: is a valid path insofar as df1
is concerned, and that Seq PathAttr and Push can be juxtapositioned in any order.
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 "" :: is acceptable, and will be correctly rendered
and parsed back.Segment
class ToSegment a where Source #
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.
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 "" :: is acceptable, and will be correctly rendered and
parsed back.Key
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.
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 "" :: is acceptable, and will be correctly rendered
and parsed back.Value
class ToValue a where Source #
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.
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 "" :: is acceptable, and will be correctly rendered
and parsed back.Message
class ToMessage a where Source #
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.
Parsing
If sucessful, parsing will stop after the first CR or LF newline marker if any, otherwise it will consume all input.
Rendering
renderColor :: Log -> Builder Source #