hermod-trace-resources
Safe HaskellSafe-Inferred
LanguageHaskell2010

Hermod.Tracing.Resources

Description

OS-level and RTS resource sampling for the Hermod tracing system.

This is the only public module of the package. Import it and call readResourceStats once per sampling interval to obtain a ResourceStats snapshot. The value carries LogFormatting and MetaTrace instances and can be fed directly into any Trace IO ResourceStats.

Platform support:

  • Linux — CPU, GC, memory (RSS), block IO, filesystem IO, network (opt-in), threads.
  • macOS — CPU, GC, memory (RSS), network IO, threads; disk IO stubbed.
  • Windows — CPU, GC, memory (RSS), block I/O, threads.
  • Other — GHC RTS metrics (CPU, GC, threads) only; OS fields report 0.
Synopsis

Documentation

data Resources a Source #

A snapshot of resource usage for the current process, parameterised over the numeric type a. The concrete alias ResourceStats fixes a ~ Word64.

Fields that cannot be measured on the current platform are set to 0.

Constructors

Resources 

Fields

  • rCentiCpu :: !a

    CPU time in centiseconds (1/100 s) since process start, from /proc/self/stat on Linux or equivalent OS API.

  • rCentiGC :: !a

    CPU centiseconds spent in the GHC garbage collector (RTS stats).

  • rCentiMut :: !a

    CPU centiseconds spent in the mutator, i.e. application code (RTS stats).

  • rGcsMajor :: !a

    Number of major (full-heap) GC runs since process start (RTS stats).

  • rGcsMinor :: !a

    Number of minor GC runs since process start (RTS stats).

  • rAlloc :: !a

    Cumulative bytes allocated in the heap since process start (RTS stats).

  • rLive :: !a

    Live heap bytes immediately after the last GC run (RTS stats).

  • rHeap :: !a

    Committed heap bytes (total heap size reserved from the OS) (RTS stats).

  • rRSS :: !a

    Resident set size in bytes: physical memory currently mapped to the process (from the OS kernel).

  • rCentiBlkIO :: !a

    Centiseconds spent waiting for block I/O (Linux /proc/self/stat only; 0 on other platforms).

  • rNetRd :: !a

    IP packet bytes received since boot (Linux /proc/self/net/netstat, only when the with-netstat flag is enabled; 0 otherwise).

  • rNetWr :: !a

    IP packet bytes transmitted since boot (Linux /proc/self/net/netstat, only when the with-netstat flag is enabled; 0 otherwise).

  • rFsRd :: !a

    Filesystem bytes read by the process (from /proc/self/io on Linux or equivalent OS API).

  • rFsWr :: !a

    Filesystem bytes written by the process (from /proc/self/io on Linux or equivalent OS API).

  • rThreads :: !a

    Number of live GHC green threads (RTS stats).

Instances

Instances details
Applicative Resources Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

Methods

pure :: a -> Resources a Source #

(<*>) :: Resources (a -> b) -> Resources a -> Resources b Source #

liftA2 :: (a -> b -> c) -> Resources a -> Resources b -> Resources c Source #

(*>) :: Resources a -> Resources b -> Resources b Source #

(<*) :: Resources a -> Resources b -> Resources a Source #

Functor Resources Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

Methods

fmap :: (a -> b) -> Resources a -> Resources b Source #

(<$) :: a -> Resources b -> Resources a Source #

LogFormatting ResourceStats Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

Methods

forMachine :: DetailLevel -> ResourceStats -> Object

forHuman :: ResourceStats -> Text

asMetrics :: ResourceStats -> [Metric]

MetaTrace ResourceStats Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

Methods

namespaceFor :: ResourceStats -> Namespace ResourceStats

severityFor :: Namespace ResourceStats -> Maybe ResourceStats -> Maybe SeverityS

privacyFor :: Namespace ResourceStats -> Maybe ResourceStats -> Maybe Privacy

detailsFor :: Namespace ResourceStats -> Maybe ResourceStats -> Maybe DetailLevel

documentFor :: Namespace ResourceStats -> Maybe Text

metricsDocFor :: Namespace ResourceStats -> [(Text, Text)]

allNamespaces :: [Namespace ResourceStats]

FromJSON a => FromJSON (Resources a) Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

Methods

parseJSON :: Value -> Parser (Resources a)

parseJSONList :: Value -> Parser [Resources a]

omittedField :: Maybe (Resources a)

ToJSON a => ToJSON (Resources a) Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

Methods

toJSON :: Resources a -> Value

toEncoding :: Resources a -> Encoding

toJSONList :: [Resources a] -> Value

toEncodingList :: [Resources a] -> Encoding

omitField :: Resources a -> Bool

Generic (Resources a) Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

Associated Types

type Rep (Resources a) :: Type -> Type Source #

Methods

from :: Resources a -> Rep (Resources a) x Source #

to :: Rep (Resources a) x -> Resources a Source #

Show a => Show (Resources a) Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

type Rep (Resources a) Source # 
Instance details

Defined in Hermod.Tracing.Resources.Types

type Rep (Resources a) = D1 ('MetaData "Resources" "Hermod.Tracing.Resources.Types" "hermod-trace-resources-1.0.0-7hXRDDadXfmACiwJUrBfEo" 'False) (C1 ('MetaCons "Resources" 'PrefixI 'True) (((S1 ('MetaSel ('Just "rCentiCpu") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: (S1 ('MetaSel ('Just "rCentiGC") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Just "rCentiMut") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a))) :*: ((S1 ('MetaSel ('Just "rGcsMajor") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Just "rGcsMinor") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a)) :*: (S1 ('MetaSel ('Just "rAlloc") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Just "rLive") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a)))) :*: (((S1 ('MetaSel ('Just "rHeap") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Just "rRSS") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a)) :*: (S1 ('MetaSel ('Just "rCentiBlkIO") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Just "rNetRd") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a))) :*: ((S1 ('MetaSel ('Just "rNetWr") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Just "rFsRd") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a)) :*: (S1 ('MetaSel ('Just "rFsWr") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a) :*: S1 ('MetaSel ('Just "rThreads") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a))))))

type ResourceStats = Resources Word64 Source #

Concrete snapshot of resource usage with all fields as Word64 counts.

readResourceStats :: IO (Maybe ResourceStats) Source #

Sample resource usage of the current process.

Returns Nothing only when the underlying OS interface is unavailable (e.g. /proc not mounted). Under normal operating conditions this always returns Just.

The returned ResourceStats is a Resources Word64; fields that cannot be measured on the current platform are set to 0.