| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
Hermod.Tracing
Description
Batteries-included public interface for the Hermod tracing system.
A typical application wires up tracing in three steps:
- Define trace types: for each domain-specific message type, write
LogFormatting(human/machine rendering, metrics) andMetaTrace(namespace, severity, documentation) instances. - Construct backends: call
mkHermodTracer(ormkHermodTracer') withstandardTracer,ekgTracer, and/orforwardTracerto build a 'Trace IO YourType'. - Configure: load a
TraceConfigwithreadConfigurationand apply it withconfigureTracers. UsecheckTraceConfigurationto validate the config against all known namespaces at startup.
Synopsis
- class Contravariant (f :: Type -> Type) where
- newtype Trace (m :: Type -> Type) a = Trace {
- unpackTrace :: Tracer m (LoggingContext, Either TraceControl a)
- data DataPoint where
- data ConfigReflection = ConfigReflection {}
- data HermodException = HermodConfigException {
- excMessage :: String
- data FormattedMessage
- data ConfigSource
- type NSWarnings = [Text]
- data PreFormatted = PreFormatted {
- pfTime :: !UTCTime
- pfNamespace :: !Text
- pfThreadId :: !Text
- pfForHuman :: !(Maybe Text)
- pfForMachineObject :: Object
- data TraceObject = TraceObject {
- toHuman :: !(Maybe Text)
- toMachine :: !Text
- toNamespace :: ![Text]
- toSeverity :: !SeverityS
- toDetails :: !DetailLevel
- toTimestamp :: !UTCTime
- toHostname :: !Text
- toThreadId :: !Text
- data LimiterSpec = LimiterSpec {}
- type DataPointName = Text
- type DataPointStore = TVar (Map DataPointName DataPoint)
- data HowToConnect
- = LocalPipe !FilePath
- | RemoteSocket !Host !Port
- type Host = Text
- type Port = Word16
- data SeverityS
- data Namespace a = Namespace {}
- data TraceOptionForwarder = TraceOptionForwarder {}
- data PrometheusSimpleRun = PrometheusSimpleRun {}
- newtype SeverityF = SeverityF (Maybe SeverityS)
- data DetailLevel
- data BackendConfig
- = Forwarder
- | Stdout FormatLogging
- | EKGBackend
- | DatapointBackend
- | PrometheusSimple Bool (Maybe HostName) PortNumber
- data TraceConfig = TraceConfig {}
- data ConfigOption
- = ConfSeverity { }
- | ConfDetail { }
- | ConfBackend {
- backends :: [BackendConfig]
- | ConfLimiter { }
- data CounterAction
- data LoggingContext = LoggingContext {
- lcNSInner :: [Text]
- lcNSPrefix :: [Text]
- lcSeverity :: Maybe SeverityS
- lcPrivacy :: Maybe Privacy
- lcDetails :: Maybe DetailLevel
- data Metric
- data Privacy
- data FormatLogging
- data ForwarderMode
- data Verbosity
- newtype DocCollector = DocCollector (IORef (Map Int LogDoc))
- data LogDoc = LogDoc {
- ldDoc :: !Text
- ldMetricsDoc :: !(Map Text Text)
- ldNamespace :: ![([Text], [Text])]
- ldSeverityCoded :: !(Maybe SeverityS)
- ldPrivacyCoded :: !(Maybe Privacy)
- ldDetailsCoded :: !(Maybe DetailLevel)
- ldDetails :: ![DetailLevel]
- ldBackends :: ![BackendConfig]
- ldFiltered :: ![SeverityF]
- ldLimiter :: ![(Text, Double)]
- ldSilent :: Bool
- class LogFormatting a where
- forMachine :: DetailLevel -> a -> Object
- forHuman :: a -> Text
- asMetrics :: a -> [Metric]
- newtype Folding a b = Folding b
- class MetaTrace a where
- namespaceFor :: a -> Namespace a
- severityFor :: Namespace a -> Maybe a -> Maybe SeverityS
- privacyFor :: Namespace a -> Maybe a -> Maybe Privacy
- detailsFor :: Namespace a -> Maybe a -> Maybe DetailLevel
- documentFor :: Namespace a -> Maybe Text
- metricsDocFor :: Namespace a -> [(Text, Text)]
- allNamespaces :: [Namespace a]
- data TraceControl where
- TCReset :: TraceControl
- TCConfig :: TraceConfig -> TraceControl
- TCOptimize :: ConfigReflection -> TraceControl
- TCDocument :: Int -> DocCollector -> TraceControl
- traceWith :: Monad m => Trace m a -> a -> m ()
- unfold :: Folding a b -> b
- (>$<) :: Contravariant f => (a -> b) -> f b -> f a
- arrow :: forall (m :: Type -> Type) a. TracerA m a () -> Tracer m a
- contramapM :: Monad m => Trace m b -> ((LoggingContext, Either TraceControl a) -> m (LoggingContext, Either TraceControl b)) -> Trace m a
- emptyConfigReflection :: IO ConfigReflection
- configureTracers :: forall a m. (MetaTrace a, MonadIO m) => ConfigReflection -> TraceConfig -> [Trace m a] -> m ()
- withNamespaceConfig :: forall m a b c. (MonadIO m, Ord b) => String -> (TraceConfig -> Namespace a -> m b) -> (Maybe b -> Trace m c -> Trace m a) -> Trace m c -> m (Trace m a)
- filterSeverityFromConfig :: MonadIO m => Trace m a -> m (Trace m a)
- withDetailsFromConfig :: MonadIO m => Trace m a -> m (Trace m a)
- withBackendsFromConfig :: MonadIO m => (Maybe [BackendConfig] -> Trace m FormattedMessage -> Trace m a) -> m (Trace m a)
- withLimitersFromConfig :: forall a m. MonadUnliftIO m => Trace m HermodTracingMessage -> Trace m a -> m (Trace m a)
- maybeSilent :: forall m a. MonadIO m => (TraceConfig -> Namespace a -> Bool) -> [Text] -> Bool -> Trace m a -> m (Trace m a)
- isSilentTracer :: forall a. MetaTrace a => TraceConfig -> Namespace a -> Bool
- hasNoMetrics :: forall a. MetaTrace a => TraceConfig -> Namespace a -> Bool
- getSeverity :: TraceConfig -> Namespace a -> SeverityF
- getDetails :: TraceConfig -> Namespace a -> DetailLevel
- getBackends :: TraceConfig -> Namespace a -> [BackendConfig]
- limitFrequency :: forall a m. MonadUnliftIO m => Double -> Text -> Trace m HermodTracingMessage -> Trace m a -> m (Trace m a)
- mkConfiguration :: TraceConfig
- mkConfigurationWithFallback :: SeverityS -> DetailLevel -> BackendConfig -> TraceConfig
- readConfiguration :: ConfigSource -> IO TraceConfig
- readConfigurationWithFallback :: SeverityS -> DetailLevel -> BackendConfig -> ConfigSource -> IO TraceConfig
- readConfiguration' :: FilePath -> IO TraceConfig
- readConfigurationWithFallback' :: SeverityS -> DetailLevel -> BackendConfig -> FilePath -> IO TraceConfig
- readConfigurationWithDefault :: ConfigSource -> TraceConfig -> IO TraceConfig
- readConfigurationWithFallbackAndDefault :: SeverityS -> DetailLevel -> BackendConfig -> ConfigSource -> TraceConfig -> IO TraceConfig
- applyFallback :: SeverityS -> DetailLevel -> BackendConfig -> TraceConfig -> TraceConfig
- configToRepresentation :: TraceConfig -> ConfigRepresentation
- checkTraceConfiguration :: ConfigSource -> TraceConfig -> [([Text], [Text])] -> IO NSWarnings
- checkTraceConfiguration' :: TraceConfig -> [([Text], [Text])] -> NSWarnings
- metricsFormatter :: forall a m. (LogFormatting a, MonadIO m) => Trace m FormattedMessage -> Trace m a
- preFormatted :: (LogFormatting a, MonadIO m) => Bool -> Trace m PreFormatted -> Trace m a
- forwardFormatter :: forall a m. (MonadIO m, LogFormatting a) => Trace m FormattedMessage -> Trace m a
- forwardFormatter' :: forall m. MonadIO m => Trace m FormattedMessage -> Trace m PreFormatted
- machineFormatter :: forall a m. (MonadIO m, LogFormatting a) => Trace m FormattedMessage -> Trace m a
- machineFormatter' :: forall m. MonadIO m => Trace m FormattedMessage -> Trace m PreFormatted
- cborFormatter :: forall a m. (MonadIO m, LogFormatting a) => Trace m FormattedMessage -> Trace m a
- cborFormatter' :: forall m. MonadIO m => Trace m FormattedMessage -> Trace m PreFormatted
- humanFormatter :: forall a m. (MonadIO m, LogFormatting a) => Bool -> Trace m FormattedMessage -> Trace m a
- humanFormatter' :: forall m. MonadIO m => Bool -> Trace m FormattedMessage -> Trace m PreFormatted
- showT :: Show a => a -> Text
- filterTrace :: forall (m :: Type -> Type) a. Monad m => ((LoggingContext, a) -> Bool) -> Trace m a -> Trace m a
- initDataPointStore :: IO DataPointStore
- writeToStore :: DataPointStore -> DataPointName -> DataPoint -> IO ()
- dataPointTracer :: forall m. MonadIO m => DataPointStore -> Trace m DataPoint
- mkDataPointTracer :: forall dp. (ToJSON dp, MetaTrace dp, NFData dp) => Trace IO DataPoint -> IO (Trace IO dp)
- tryEvalNF :: NFData a => a -> IO (Either SomeException a)
- ekgTracer :: MonadIO m => TraceConfig -> Store -> m (Trace m FormattedMessage)
- showTReal :: RealFloat a => a -> Text
- standardTracer :: forall m. MonadIO m => m (Trace m FormattedMessage)
- threadLabelMe :: String -> IO ()
- forwardTracer :: forall m. MonadIO m => (TraceObject -> IO ()) -> Trace m FormattedMessage
- mkHermodTracer :: forall evt. (LogFormatting evt, MetaTrace evt) => Trace IO FormattedMessage -> Trace IO FormattedMessage -> Maybe (Trace IO FormattedMessage) -> [Text] -> IO (Trace IO evt)
- mkHermodTracer' :: forall evt evt1. (LogFormatting evt1, MetaTrace evt1) => Trace IO FormattedMessage -> Trace IO FormattedMessage -> Maybe (Trace IO FormattedMessage) -> [Text] -> (Trace IO evt1 -> IO (Trace IO evt)) -> IO (Trace IO evt)
- mkMetricsTracer :: Maybe (Trace IO FormattedMessage) -> Trace IO FormattedMessage
- traceTracerInfo :: Trace IO FormattedMessage -> Trace IO FormattedMessage -> ConfigReflection -> IO ()
- traceConfigWarnings :: Trace IO FormattedMessage -> Trace IO FormattedMessage -> [Text] -> IO ()
- traceEffectiveConfiguration :: Trace IO FormattedMessage -> Trace IO FormattedMessage -> TraceConfig -> IO ()
- runInLoop :: IO () -> (SomeException -> IO ()) -> Word64 -> Word64 -> IO ()
- emptyTraceConfig :: TraceConfig
- emptyLoggingContext :: LoggingContext
- getMetricName :: Metric -> Text
- nsCast :: Namespace a -> Namespace b
- nsGetComplete :: Namespace a -> [Text]
- nsGetTuple :: Namespace a -> ([Text], [Text])
- nsPrependInner :: Text -> Namespace a -> Namespace b
- nsRawToText :: ([Text], [Text]) -> Text
- nsReplaceInner :: [Text] -> Namespace a -> Namespace a
- nsReplacePrefix :: [Text] -> Namespace a -> Namespace a
- nsToText :: Namespace a -> Text
- defaultForwarder :: TraceOptionForwarder
- parsePrometheusString :: Text -> Either String BackendConfig
- prometheusSimpleNoOverrides :: PrometheusSimpleRun
- emptyLogDoc :: Text -> [(Text, Text)] -> LogDoc
- contramapMCond :: Monad m => Trace m b -> ((LoggingContext, Either TraceControl a) -> m (Maybe (LoggingContext, Either TraceControl b))) -> Trace m a
- foldCondTraceM :: forall a acc m. MonadUnliftIO m => (acc -> LoggingContext -> a -> m acc) -> acc -> (a -> Bool) -> Trace m (Folding a acc) -> m (Trace m a)
- foldTraceM :: forall a acc m. MonadUnliftIO m => (acc -> LoggingContext -> a -> m acc) -> acc -> Trace m (Folding a acc) -> m (Trace m a)
- routingTrace :: Monad m => (a -> m (Trace m a)) -> Trace m a -> Trace m a
- filterTraceMaybe :: forall (m :: Type -> Type) a. Monad m => Trace m a -> Trace m (Maybe a)
- effect :: (a -> m b) -> TracerA m a b
- emit :: Applicative m => (a -> m ()) -> TracerA m a ()
- nat :: (forall x. m x -> n x) -> TracerA m a b -> TracerA n a b
- squelch :: forall (m :: Type -> Type) a. Applicative m => TracerA m a ()
- runTracer :: Tracer m a -> TracerA m a ()
- debugTracer :: forall (m :: Type -> Type). Applicative m => Tracer m String
- mkTracer :: Applicative m => (a -> m ()) -> Tracer m a
- natTracer :: (forall x. m x -> n x) -> Tracer m s -> Tracer n s
- squelchUnless :: forall (m :: Type -> Type) a. Monad m => (a -> Bool) -> Tracer m a -> Tracer m a
- squelchUnlessM :: Monad m => (a -> m Bool) -> Tracer m a -> Tracer m a
- stdoutTracer :: Tracer IO String
- traceAll :: forall (m :: Type -> Type) t b a. (Monad m, Foldable t) => (b -> t a) -> Tracer m a -> Tracer m b
- traceMaybe :: forall (m :: Type -> Type) a b. Monad m => (a -> Maybe b) -> Tracer m b -> Tracer m a
- traceMaybeM :: Monad m => (a -> m (Maybe b)) -> Tracer m b -> Tracer m a
- traceTraversable :: forall (m :: Type -> Type) t a. (Monad m, Foldable t) => Tracer m a -> Tracer m (t a)
- use :: forall (m :: Type -> Type) a. Tracer m a -> TracerA m a ()
- excludeAsyncExceptions :: SomeException -> Maybe SomeException
- showTHex :: Integral a => a -> Text
Documentation
class Contravariant (f :: Type -> Type) where Source #
The class of contravariant functors.
Whereas in Haskell, one can think of a Functor as containing or producing
values, a contravariant functor is a functor that can be thought of as
consuming values.
As an example, consider the type of predicate functions a -> Bool. One
such predicate might be negative x = x < 0, which
classifies integers as to whether they are negative. However, given this
predicate, we can re-use it in other situations, providing we have a way to
map values to integers. For instance, we can use the negative predicate
on a person's bank balance to work out if they are currently overdrawn:
newtype Predicate a = Predicate { getPredicate :: a -> Bool }
instance Contravariant Predicate where
contramap :: (a' -> a) -> (Predicate a -> Predicate a')
contramap f (Predicate p) = Predicate (p . f)
| `- First, map the input...
`----- then apply the predicate.
overdrawn :: Predicate Person
overdrawn = contramap personBankBalance negative
Any instance should be subject to the following laws:
Note, that the second law follows from the free theorem of the type of
contramap and the first law, so you need only check that the former
condition holds.
Minimal complete definition
Instances
newtype Trace (m :: Type -> Type) a #
Constructors
| Trace | |
Fields
| |
Type wrapper for some value of type v. The only reason we need this
wrapper is an ability to store different values in the same DataPointStore.
Please note that when the acceptor application will read the value of type v
from the store, this value is just as unstructured JSON, but not Haskell
value of type v. That's why FromJSON instance for type v should be
available for the acceptor application, to decode unstructured JSON.
data ConfigReflection #
Constructors
| ConfigReflection | |
data HermodException Source #
Constructors
| HermodConfigException | |
Fields
| |
Instances
| Exception HermodException Source # | |
Defined in Hermod.Tracing.Configuration Methods toException :: HermodException -> SomeException Source # fromException :: SomeException -> Maybe HermodException Source # | |
| Show HermodException Source # | |
Defined in Hermod.Tracing.Configuration | |
data FormattedMessage Source #
Constructors
| FormattedHuman Bool Text | The bool specifies if the formatting includes colours |
| FormattedMachine Text | |
| FormattedMetrics [Metric] | |
| FormattedForwarder TraceObject | |
| FormattedCBOR ByteString |
Instances
| Show FormattedMessage Source # | |
Defined in Hermod.Tracing.Formatter | |
| Eq FormattedMessage Source # | |
Defined in Hermod.Tracing.Formatter Methods (==) :: FormattedMessage -> FormattedMessage -> Bool Source # (/=) :: FormattedMessage -> FormattedMessage -> Bool Source # | |
data ConfigSource Source #
The configuration source that should be ingested
Constructors
| FromFile FilePath | |
| FromJSONObject Object | |
| FromLazyBytes ByteString | |
| FromStrictBytes ByteString |
Instances
| Show ConfigSource Source # | |
Defined in Hermod.Tracing.ConfigurationParser | |
| Eq ConfigSource Source # | |
Defined in Hermod.Tracing.ConfigurationParser Methods (==) :: ConfigSource -> ConfigSource -> Bool Source # (/=) :: ConfigSource -> ConfigSource -> Bool Source # | |
type NSWarnings = [Text] Source #
Warnings as a list of text
data PreFormatted Source #
Constructors
| PreFormatted | |
Fields
| |
data TraceObject Source #
Used as interface object for ForwarderTracer
Constructors
| TraceObject | |
Fields
| |
Instances
data LimiterSpec Source #
Constructors
| LimiterSpec | |
type DataPointName = Text Source #
type DataPointStore = TVar (Map DataPointName DataPoint) Source #
data HowToConnect Source #
Constructors
| LocalPipe !FilePath | Local pipe (UNIX or Windows). |
| RemoteSocket !Host !Port | Remote socket (host and port). |
Instances
Specifies how to connect to the peer.
Taken from ekg-forward:System.Metrics.Configuration, to avoid dependency.
Instances
data TraceOptionForwarder #
Constructors
| TraceOptionForwarder | |
Fields | |
Instances
data PrometheusSimpleRun #
Constructors
| PrometheusSimpleRun | |
Fields | |
Instances
Instances
| FromJSON SeverityF | |
Defined in Hermod.Tracing.Types.Annotations | |
| ToJSON SeverityF | |
Defined in Hermod.Tracing.Types.Annotations Methods toEncoding :: SeverityF -> Encoding toJSONList :: [SeverityF] -> Value toEncodingList :: [SeverityF] -> Encoding | |
| Enum SeverityF | |
Defined in Hermod.Tracing.Types.Annotations Methods succ :: SeverityF -> SeverityF Source # pred :: SeverityF -> SeverityF Source # toEnum :: Int -> SeverityF Source # fromEnum :: SeverityF -> Int Source # enumFrom :: SeverityF -> [SeverityF] Source # enumFromThen :: SeverityF -> SeverityF -> [SeverityF] Source # enumFromTo :: SeverityF -> SeverityF -> [SeverityF] Source # enumFromThenTo :: SeverityF -> SeverityF -> SeverityF -> [SeverityF] Source # | |
| Show SeverityF | |
| Eq SeverityF | |
| Ord SeverityF | |
Defined in Hermod.Tracing.Types.Annotations | |
data DetailLevel #
Instances
data BackendConfig #
Constructors
| Forwarder | |
| Stdout FormatLogging | |
| EKGBackend | |
| DatapointBackend | |
| PrometheusSimple Bool (Maybe HostName) PortNumber |
Instances
data TraceConfig #
Constructors
| TraceConfig | |
Instances
| ToJSON TraceConfig | |
Defined in Hermod.Tracing.ConfigurationParser Methods toJSON :: TraceConfig -> Value toEncoding :: TraceConfig -> Encoding toJSONList :: [TraceConfig] -> Value toEncodingList :: [TraceConfig] -> Encoding omitField :: TraceConfig -> Bool | |
| Show TraceConfig | |
Defined in Hermod.Tracing.Types.Config | |
data ConfigOption #
Constructors
| ConfSeverity | |
| ConfDetail | |
Fields | |
| ConfBackend | |
Fields
| |
| ConfLimiter | |
Fields | |
Instances
data CounterAction #
Constructors
| CounterIncrement | |
| CounterAdd Word64 |
Instances
| Generic CounterAction | |
Defined in Hermod.Tracing.Types.Annotations Methods from :: CounterAction -> Rep CounterAction x Source # to :: Rep CounterAction x -> CounterAction Source # | |
| Show CounterAction | |
Defined in Hermod.Tracing.Types.Annotations | |
| NFData CounterAction | |
Defined in Hermod.Tracing.Types.Annotations Methods rnf :: CounterAction -> () Source # | |
| Eq CounterAction | |
Defined in Hermod.Tracing.Types.Annotations Methods (==) :: CounterAction -> CounterAction -> Bool Source # (/=) :: CounterAction -> CounterAction -> Bool Source # | |
| type Rep CounterAction | |
Defined in Hermod.Tracing.Types.Annotations type Rep CounterAction = D1 ('MetaData "CounterAction" "Hermod.Tracing.Types.Annotations" "hermod-tracing-api-1.0.0-LO80W9OfQJv10WJ5Ly2Uoc-internal" 'False) (C1 ('MetaCons "CounterIncrement" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "CounterAdd" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word64))) | |
data LoggingContext #
Constructors
| LoggingContext | |
Fields
| |
Instances
Constructors
| IntM Text Integer | |
| DoubleM Text Double | |
| CounterM Text CounterAction | |
| LabelSetM Text [(Text, Text)] |
Instances
Constructors
| Confidential | |
| Public |
Instances
| Bounded Privacy | |
| Enum Privacy | |
Defined in Hermod.Tracing.Types.Annotations Methods succ :: Privacy -> Privacy Source # pred :: Privacy -> Privacy Source # toEnum :: Int -> Privacy Source # fromEnum :: Privacy -> Int Source # enumFrom :: Privacy -> [Privacy] Source # enumFromThen :: Privacy -> Privacy -> [Privacy] Source # enumFromTo :: Privacy -> Privacy -> [Privacy] Source # enumFromThenTo :: Privacy -> Privacy -> Privacy -> [Privacy] Source # | |
| Generic Privacy | |
| Show Privacy | |
| Eq Privacy | |
| Ord Privacy | |
Defined in Hermod.Tracing.Types.Annotations | |
| Serialise Privacy | |
Defined in Hermod.Tracing.Types.Annotations | |
| type Rep Privacy | |
Defined in Hermod.Tracing.Types.Annotations | |
data FormatLogging #
Constructors
| HumanFormatColoured | |
| HumanFormatUncoloured | |
| MachineFormat |
Instances
| Show FormatLogging | |
Defined in Hermod.Tracing.Types.Config | |
| Eq FormatLogging | |
Defined in Hermod.Tracing.Types.Config Methods (==) :: FormatLogging -> FormatLogging -> Bool Source # (/=) :: FormatLogging -> FormatLogging -> Bool Source # | |
| Ord FormatLogging | |
Defined in Hermod.Tracing.Types.Config Methods compare :: FormatLogging -> FormatLogging -> Ordering Source # (<) :: FormatLogging -> FormatLogging -> Bool Source # (<=) :: FormatLogging -> FormatLogging -> Bool Source # (>) :: FormatLogging -> FormatLogging -> Bool Source # (>=) :: FormatLogging -> FormatLogging -> Bool Source # max :: FormatLogging -> FormatLogging -> FormatLogging Source # min :: FormatLogging -> FormatLogging -> FormatLogging Source # | |
data ForwarderMode #
Instances
| FromJSON ForwarderMode | |
Defined in Hermod.Tracing.Types.Config | |
| Generic ForwarderMode | |
Defined in Hermod.Tracing.Types.Config Methods from :: ForwarderMode -> Rep ForwarderMode x Source # to :: Rep ForwarderMode x -> ForwarderMode Source # | |
| Show ForwarderMode | |
Defined in Hermod.Tracing.Types.Config | |
| Eq ForwarderMode | |
Defined in Hermod.Tracing.Types.Config Methods (==) :: ForwarderMode -> ForwarderMode -> Bool Source # (/=) :: ForwarderMode -> ForwarderMode -> Bool Source # | |
| Ord ForwarderMode | |
Defined in Hermod.Tracing.Types.Config Methods compare :: ForwarderMode -> ForwarderMode -> Ordering Source # (<) :: ForwarderMode -> ForwarderMode -> Bool Source # (<=) :: ForwarderMode -> ForwarderMode -> Bool Source # (>) :: ForwarderMode -> ForwarderMode -> Bool Source # (>=) :: ForwarderMode -> ForwarderMode -> Bool Source # max :: ForwarderMode -> ForwarderMode -> ForwarderMode Source # min :: ForwarderMode -> ForwarderMode -> ForwarderMode Source # | |
| type Rep ForwarderMode | |
Defined in Hermod.Tracing.Types.Config | |
Instances
| FromJSON Verbosity | |
Defined in Hermod.Tracing.Types.Config | |
| ToJSON Verbosity | |
Defined in Hermod.Tracing.Types.Config Methods toEncoding :: Verbosity -> Encoding toJSONList :: [Verbosity] -> Value toEncodingList :: [Verbosity] -> Encoding | |
| Generic Verbosity | |
| Show Verbosity | |
| Eq Verbosity | |
| Ord Verbosity | |
Defined in Hermod.Tracing.Types.Config | |
| type Rep Verbosity | |
Defined in Hermod.Tracing.Types.Config | |
newtype DocCollector #
Constructors
| DocCollector (IORef (Map Int LogDoc)) |
Constructors
| LogDoc | |
Fields
| |
class LogFormatting a where #
Minimal complete definition
Methods
forMachine :: DetailLevel -> a -> Object #
Instances
| LogFormatting HermodTracingMessage Source # | |
Defined in Hermod.Tracing.HermodTracingMessage Methods forMachine :: DetailLevel -> HermodTracingMessage -> Object # forHuman :: HermodTracingMessage -> Text # asMetrics :: HermodTracingMessage -> [Metric] # | |
| LogFormatting b => LogFormatting (Folding a b) | |
Defined in Hermod.Tracing.Types | |
Constructors
| Folding b |
Instances
| LogFormatting b => LogFormatting (Folding a b) | |
Defined in Hermod.Tracing.Types | |
Minimal complete definition
Methods
namespaceFor :: a -> Namespace a #
severityFor :: Namespace a -> Maybe a -> Maybe SeverityS #
privacyFor :: Namespace a -> Maybe a -> Maybe Privacy #
detailsFor :: Namespace a -> Maybe a -> Maybe DetailLevel #
documentFor :: Namespace a -> Maybe Text #
metricsDocFor :: Namespace a -> [(Text, Text)] #
allNamespaces :: [Namespace a] #
Instances
data TraceControl where #
Constructors
| TCReset :: TraceControl | |
| TCConfig :: TraceConfig -> TraceControl | |
| TCOptimize :: ConfigReflection -> TraceControl | |
| TCDocument :: Int -> DocCollector -> TraceControl |
(>$<) :: Contravariant f => (a -> b) -> f b -> f a infixl 4 Source #
This is an infix alias for contramap.
contramapM :: Monad m => Trace m b -> ((LoggingContext, Either TraceControl a) -> m (LoggingContext, Either TraceControl b)) -> Trace m a #
configureTracers :: forall a m. (MetaTrace a, MonadIO m) => ConfigReflection -> TraceConfig -> [Trace m a] -> m () Source #
Call this function at initialisation, and later for reconfiguration. Config reflection is used to optimise the tracers and has to collect information about the tracers. Although it is possible to give more then one tracer of the same time, it is not a common case to do this.
withNamespaceConfig :: forall m a b c. (MonadIO m, Ord b) => String -> (TraceConfig -> Namespace a -> m b) -> (Maybe b -> Trace m c -> Trace m a) -> Trace m c -> m (Trace m a) Source #
Take a selector function called extract.
Take a function from trace to trace with this config dependent value.
In this way construct a trace transformer with a config value
filterSeverityFromConfig :: MonadIO m => Trace m a -> m (Trace m a) Source #
Filter a trace by severity and take the filter value from the config
withDetailsFromConfig :: MonadIO m => Trace m a -> m (Trace m a) Source #
Set detail level of a trace from the config
withBackendsFromConfig :: MonadIO m => (Maybe [BackendConfig] -> Trace m FormattedMessage -> Trace m a) -> m (Trace m a) Source #
Routing and formatting of a trace from the config
withLimitersFromConfig :: forall a m. MonadUnliftIO m => Trace m HermodTracingMessage -> Trace m a -> m (Trace m a) Source #
Routing and formatting of a trace from the config
maybeSilent :: forall m a. MonadIO m => (TraceConfig -> Namespace a -> Bool) -> [Text] -> Bool -> Trace m a -> m (Trace m a) Source #
Switch off any message of a particular tracer based on the configuration. If the top tracer is silent and no subtracer is not silent, then switch it off
isSilentTracer :: forall a. MetaTrace a => TraceConfig -> Namespace a -> Bool Source #
hasNoMetrics :: forall a. MetaTrace a => TraceConfig -> Namespace a -> Bool Source #
getSeverity :: TraceConfig -> Namespace a -> SeverityF Source #
By guaranteeing fallback values in the config's namespace root, the Debug severity value here should never get used. If it has to be used, this points to a severely erroneous config, or an implementation error in the application's MetaTrace instance(s). For those cases only, this ensures the affected trace message isn't silently filtered out.
getDetails :: TraceConfig -> Namespace a -> DetailLevel Source #
If no details can be found in the config, it is set to DNormal
getBackends :: TraceConfig -> Namespace a -> [BackendConfig] Source #
If no backends can be found in the config, it is set to [EKGBackend, Forwarder, Stdout HumanFormatColoured]
limitFrequency :: forall a m. MonadUnliftIO m => Double -> Text -> Trace m HermodTracingMessage -> Trace m a -> m (Trace m a) Source #
Limits the frequency of messages to nMsg which is given per minute.
If the limiter detects more messages, it traces randomly selected
messages with the given frequency on the vtracer until the
frequency falls under the threshold long enough.(see below)
Before this the ltracer gets a StartLimiting message.
In-between you receive ContinueLimiting messages on the ltracer
every reminderPeriod seconds, with the number of suppressed messages.
Finally it sends a StopLimiting message on the ltracer and traces all
messages on the vtracer again.
A budget is used to decide when to start limiting and stop limiting,
so that the limiter does not get activated if few messages are send in
high frequency, and doesn't get deactivated if their are only few messages
which come with low frequency. When messages arrive in shorter frequency then
by the given thresholdFrequency budget is earned, and if they
arrive in a longer period budget is spend. If budget is gets higher
then budgetLimit, the limiter starts, and if it falls below minus budgetLimit
the limiter stops.
mkConfiguration :: TraceConfig Source #
Creates the minimal viable configuration by only setting fallback values in an empty TraceConfig. Fallback options for the namespace root: Notice severity, normal detail, JSON stdout logging. Notice severity was chosen as it will never filter out any actionable traces while creating minimal noise in the log.
mkConfigurationWithFallback :: SeverityS -> DetailLevel -> BackendConfig -> TraceConfig Source #
Creates the minimal viable configuration by only setting custom fallback values in an empty TraceConfig. Fallback options for the namespace root: custom values.
readConfiguration :: ConfigSource -> IO TraceConfig Source #
Read a configuration source and return the internal representation. Fallback options for the namespace root: Notice severity, normal detail, JSON stdout logging.
readConfigurationWithFallback :: SeverityS -> DetailLevel -> BackendConfig -> ConfigSource -> IO TraceConfig Source #
Read a configuration source and return the internal representation. Fallback options for the namespace root: custom values.
readConfiguration' :: FilePath -> IO TraceConfig Source #
Read a configuration file and return the internal representation.
This will silently provide a minimal viable config via mkConfiguration when the file is absent.
Fallback options for the namespace root: Notice severity, normal detail, JSON stdout logging.
readConfigurationWithFallback' :: SeverityS -> DetailLevel -> BackendConfig -> FilePath -> IO TraceConfig Source #
Read a configuration file and return the internal representation.
This will silently provide a minimal viable config via mkConfigurationWithFallback when the file is absent.
Fallback options for the namespace root: custom values.
readConfigurationWithDefault :: ConfigSource -> TraceConfig -> IO TraceConfig Source #
Read a configuration source and return the internal representation.
TraceConfig fields not specified in the file will be taken from the provided defaultConf (when given there).
Fallback options for the namespace root: Notice severity, normal detail, JSON stdout logging.
readConfigurationWithFallbackAndDefault :: SeverityS -> DetailLevel -> BackendConfig -> ConfigSource -> TraceConfig -> IO TraceConfig Source #
Read a configuration source and return the internal representation.
TraceConfig fields not specified in the file will be taken from the provided defaultConf (when given there).
Fallback options for the namespace root: custom values.
applyFallback :: SeverityS -> DetailLevel -> BackendConfig -> TraceConfig -> TraceConfig Source #
Applies the fallback values to the namespace root, or creates a namespace root from them if none is present.
Furthermore, it ensures a metric prefix is properly namespaced, if there is one configured.
If you do not use any of mkConfiguration* or readConfiguration* to create your TraceConfig, but do it manually,
it is highly recommended to call applyFallback on that TraceConfig value as a last step before using it.
configToRepresentation :: TraceConfig -> ConfigRepresentation Source #
Convert config from internal to external representation
checkTraceConfiguration :: ConfigSource -> TraceConfig -> [([Text], [Text])] -> IO NSWarnings Source #
Checks if all namespaces in this configuration are legal. Legal in this case means that it can be found by a hierarchical lookup in all namespaces. Warns if namespaces in all namespaces are not unique, Warns if namespaces in all namespaces are ending in the middle of another namespace. The namespaces in allNamespaces are consistent with the namespaces for the severityFor, privacyFor, detailsFor, documentFor and metricsDocFor functions.
checkTraceConfiguration' :: TraceConfig -> [([Text], [Text])] -> NSWarnings Source #
metricsFormatter :: forall a m. (LogFormatting a, MonadIO m) => Trace m FormattedMessage -> Trace m a Source #
Format this trace as metrics
preFormatted :: (LogFormatting a, MonadIO m) => Bool -> Trace m PreFormatted -> Trace m a Source #
Transform this trace to a preformatted message, so that double serialization is avoided
forwardFormatter :: forall a m. (MonadIO m, LogFormatting a) => Trace m FormattedMessage -> Trace m a Source #
forwardFormatter' :: forall m. MonadIO m => Trace m FormattedMessage -> Trace m PreFormatted Source #
Format this trace as TraceObject for the trace forwarder
machineFormatter :: forall a m. (MonadIO m, LogFormatting a) => Trace m FormattedMessage -> Trace m a Source #
machineFormatter' :: forall m. MonadIO m => Trace m FormattedMessage -> Trace m PreFormatted Source #
Format this trace as TraceObject for machine-readable text output (JSON)
cborFormatter :: forall a m. (MonadIO m, LogFormatting a) => Trace m FormattedMessage -> Trace m a Source #
cborFormatter' :: forall m. MonadIO m => Trace m FormattedMessage -> Trace m PreFormatted Source #
Format this trace in binary serialisation (CBOR)
humanFormatter :: forall a m. (MonadIO m, LogFormatting a) => Bool -> Trace m FormattedMessage -> Trace m a Source #
humanFormatter' :: forall m. MonadIO m => Bool -> Trace m FormattedMessage -> Trace m PreFormatted Source #
Format this trace in human readable text output
showT :: Show a => a -> Text Source #
Convenience function for a Show instance to be converted to text immediately
filterTrace :: forall (m :: Type -> Type) a. Monad m => ((LoggingContext, a) -> Bool) -> Trace m a -> Trace m a #
writeToStore :: DataPointStore -> DataPointName -> DataPoint -> IO () Source #
Write DataPoint to the store.
dataPointTracer :: forall m. MonadIO m => DataPointStore -> Trace m DataPoint Source #
mkDataPointTracer :: forall dp. (ToJSON dp, MetaTrace dp, NFData dp) => Trace IO DataPoint -> IO (Trace IO dp) Source #
ekgTracer :: MonadIO m => TraceConfig -> Store -> m (Trace m FormattedMessage) Source #
It is mandatory to construct only one standard tracer in any application! Throwing away a standard tracer and using a new one will result in an exception
standardTracer :: forall m. MonadIO m => m (Trace m FormattedMessage) Source #
The standardTracer handles stdout logging in a thread-safe manner. It is strongly advised to construct only one standardTracer for any application.
threadLabelMe :: String -> IO () Source #
forwardTracer :: forall m. MonadIO m => (TraceObject -> IO ()) -> Trace m FormattedMessage Source #
It is mandatory to construct only one forwardTracer tracer in any application! Throwing away a forwardTracer tracer and using a new one will result in an exception
mkHermodTracer :: forall evt. (LogFormatting evt, MetaTrace evt) => Trace IO FormattedMessage -> Trace IO FormattedMessage -> Maybe (Trace IO FormattedMessage) -> [Text] -> IO (Trace IO evt) Source #
Construct a hermod tracer.
The tracer gets a name, which is appended to its namespace.
The tracer has to be an instance of LogFormatting for the display of
messages and an instance of MetaTrace for meta information such as
severity, privacy, details and backends'.
The tracer gets the backends': trStdout, trForward and mbTrEkg
as arguments.
The returned tracer needs to be configured with a configuration
before it is used.
mkHermodTracer' :: forall evt evt1. (LogFormatting evt1, MetaTrace evt1) => Trace IO FormattedMessage -> Trace IO FormattedMessage -> Maybe (Trace IO FormattedMessage) -> [Text] -> (Trace IO evt1 -> IO (Trace IO evt)) -> IO (Trace IO evt) Source #
Adds the possibility to add special tracers via the hook function
traceTracerInfo :: Trace IO FormattedMessage -> Trace IO FormattedMessage -> ConfigReflection -> IO () Source #
traceConfigWarnings :: Trace IO FormattedMessage -> Trace IO FormattedMessage -> [Text] -> IO () Source #
traceEffectiveConfiguration :: Trace IO FormattedMessage -> Trace IO FormattedMessage -> TraceConfig -> IO () Source #
runInLoop :: IO () -> (SomeException -> IO ()) -> Word64 -> Word64 -> IO () Source #
Run an IO action which may throw an exception in a loop. On exception, the action will be re-run after a pause (the delay parameters represent seconds). That pause doubles which each exception, but is reset when the action runs long enough.
getMetricName :: Metric -> Text #
nsGetComplete :: Namespace a -> [Text] #
nsGetTuple :: Namespace a -> ([Text], [Text]) #
nsPrependInner :: Text -> Namespace a -> Namespace b #
nsRawToText :: ([Text], [Text]) -> Text #
nsReplaceInner :: [Text] -> Namespace a -> Namespace a #
nsReplacePrefix :: [Text] -> Namespace a -> Namespace a #
contramapMCond :: Monad m => Trace m b -> ((LoggingContext, Either TraceControl a) -> m (Maybe (LoggingContext, Either TraceControl b))) -> Trace m a #
foldCondTraceM :: forall a acc m. MonadUnliftIO m => (acc -> LoggingContext -> a -> m acc) -> acc -> (a -> Bool) -> Trace m (Folding a acc) -> m (Trace m a) #
foldTraceM :: forall a acc m. MonadUnliftIO m => (acc -> LoggingContext -> a -> m acc) -> acc -> Trace m (Folding a acc) -> m (Trace m a) #
emit :: Applicative m => (a -> m ()) -> TracerA m a () #
squelch :: forall (m :: Type -> Type) a. Applicative m => TracerA m a () #
debugTracer :: forall (m :: Type -> Type). Applicative m => Tracer m String #
mkTracer :: Applicative m => (a -> m ()) -> Tracer m a #
squelchUnlessM :: Monad m => (a -> m Bool) -> Tracer m a -> Tracer m a #
stdoutTracer :: Tracer IO String #
traceAll :: forall (m :: Type -> Type) t b a. (Monad m, Foldable t) => (b -> t a) -> Tracer m a -> Tracer m b #
traceMaybe :: forall (m :: Type -> Type) a b. Monad m => (a -> Maybe b) -> Tracer m b -> Tracer m a #
traceMaybeM :: Monad m => (a -> m (Maybe b)) -> Tracer m b -> Tracer m a #
traceTraversable :: forall (m :: Type -> Type) t a. (Monad m, Foldable t) => Tracer m a -> Tracer m (t a) #
excludeAsyncExceptions :: SomeException -> Maybe SomeException Source #
Helper functions to force trace + metric values in a controlled section of code