ecluse:ecluse-runtime
Safe HaskellNone
LanguageGHC2021

Ecluse.Runtime.Log

Description

The structured-logging pipeline: the katip LogEnv every layer attaches context to, in the format and at the severity floor configuration chose. JsonLog writes one compact JSON object per line to stdout, the shape a log collector's stdout autodiscovery consumes directly, and ConsoleLog the human-readable bracketed form for local development. Colour is forced off either way, so a captured JSON line stays valid JSON. A bearer token reaches no field here: it is the redacted Secret of Ecluse.Core.Credential, and a URL is reduced to its authority before it names anything in a line.

Synopsis

Log format

data LogFormat Source #

The on-the-wire shape of the log stream, selected by configuration.

Constructors

JsonLog

One compact JSON object per line to stdout (JSONL): the in-container default a log collector's stdout JSON parsing consumes.

ConsoleLog

The human-readable bracketed form, for local development.

Instances

Instances details
WireVocab LogFormat Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Generic LogFormat Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Associated Types

type Rep LogFormat 
Instance details

Defined in Ecluse.Runtime.Log.Internal

type Rep LogFormat = D1 ('MetaData "LogFormat" "Ecluse.Runtime.Log.Internal" "ecluse-0.4.0-inplace-ecluse-runtime" 'False) (C1 ('MetaCons "JsonLog" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ConsoleLog" 'PrefixI 'False) (U1 :: Type -> Type))
Show LogFormat Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Eq LogFormat Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Universe LogFormat Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Methods

universe :: [LogFormat] #

type Rep LogFormat Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

type Rep LogFormat = D1 ('MetaData "LogFormat" "Ecluse.Runtime.Log.Internal" "ecluse-0.4.0-inplace-ecluse-runtime" 'False) (C1 ('MetaCons "JsonLog" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ConsoleLog" 'PrefixI 'False) (U1 :: Type -> Type))

parseLogFormat :: Text -> Either Text LogFormat Source #

Parse a LogFormat from its wire name, naming the accepted set on failure.

>>> parseLogFormat "json"
Right JsonLog
>>> parseLogFormat "yaml"
Left "unknown log format \"yaml\" (expected one of: json, console)"

Log level

data LogLevel Source #

The lowest severity the stream keeps, selected by configuration. The four values are the ones severityStatus renders into the status field.

Constructors

DebugLevel

Keep everything, the per-decision diagnostics included.

InfoLevel

The default: normal runtime conditions and worse.

WarnLevel

Warnings and worse.

ErrorLevel

Errors alone.

Instances

Instances details
WireVocab LogLevel Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Generic LogLevel Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Associated Types

type Rep LogLevel 
Instance details

Defined in Ecluse.Runtime.Log.Internal

type Rep LogLevel = D1 ('MetaData "LogLevel" "Ecluse.Runtime.Log.Internal" "ecluse-0.4.0-inplace-ecluse-runtime" 'False) ((C1 ('MetaCons "DebugLevel" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InfoLevel" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "WarnLevel" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ErrorLevel" 'PrefixI 'False) (U1 :: Type -> Type)))

Methods

from :: LogLevel -> Rep LogLevel x #

to :: Rep LogLevel x -> LogLevel #

Show LogLevel Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Eq LogLevel Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Ord LogLevel Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Universe LogLevel Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Methods

universe :: [LogLevel] #

type Rep LogLevel Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

type Rep LogLevel = D1 ('MetaData "LogLevel" "Ecluse.Runtime.Log.Internal" "ecluse-0.4.0-inplace-ecluse-runtime" 'False) ((C1 ('MetaCons "DebugLevel" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "InfoLevel" 'PrefixI 'False) (U1 :: Type -> Type)) :+: (C1 ('MetaCons "WarnLevel" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "ErrorLevel" 'PrefixI 'False) (U1 :: Type -> Type)))

parseLogLevel :: Text -> Either Text LogLevel Source #

Parse a LogLevel from its wire name, naming the accepted set on failure.

>>> parseLogLevel "warn"
Right WarnLevel
>>> parseLogLevel "trace"
Left "unknown log level \"trace\" (expected one of: debug, info, warn, error)"

Pipeline construction

newLogEnv :: LogFormat -> LogLevel -> DdContext -> Environment -> IO LogEnv Source #

Build the LogEnv: one stdout scribe in format that keeps items at or above level. The formatter stamps logIdentity on every line, so a line outside a span names its service.

Structured context

moduleField :: Text -> SimpleLogPayload Source #

The structured context naming the source module a log line came from. Compose it into a log site's payload so a reader filters the stream by emitter without the katip namespace.

Log lines outside a handler

moduleContext :: LogEnv -> Text -> KatipContextT m a -> m a Source #

Run action in a context naming its emitting module. A phase that holds no Handler reader, such as boot or a worker loop, enters the log stream this way.

logLine :: LogEnv -> SimpleLogPayload -> Severity -> Text -> IO () Source #

Log one line through a composition-root LogEnv under payload, for a caller whose context is a payload rather than a module name.

moduleLog :: LogEnv -> Text -> Severity -> Text -> IO () Source #

One line under a moduleField naming the emitting module and nothing else.

Datadog trace correlation

data DdContext Source #

The unified-service identity stamped onto every log line, resolved by Ecluse.Runtime.Telemetry.Resolve so logs and traces share one identity.

Constructors

DdContext 

Fields

Instances

Instances details
Show DdContext Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Eq DdContext Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

data DdSpan Source #

The active span's ids, rendered in the Datadog form by Ecluse.Runtime.Telemetry.Correlation. They are Text, so this type needs no OTel dependency.

Constructors

DdSpan 

Fields

Instances

Instances details
Show DdSpan Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Eq DdSpan Source # 
Instance details

Defined in Ecluse.Runtime.Log.Internal

Methods

(==) :: DdSpan -> DdSpan -> Bool #

(/=) :: DdSpan -> DdSpan -> Bool #

ddField :: DdContext -> SimpleLogPayload Source #

The dd object as a katip payload under the dd key. Install it as the initial context of a request or worker scope so every line there carries that scope's active span.