Observe.Event

This is the primary module needed to instrument code with eventuo11y.

Instrumentors should first define selector types and field types appropriate to the unit of code they're instrumenting:

Selectors are values which designate the general category of event being created, parameterized by the type of fields that can be added to it. For example, a web service's selector type may have a ServicingRequest constructor, whose field type includes a ResponseCode constructor which records the HTTP status code. Selectors are intended to be of a domain-specific type per unit of functionality within an instrumented codebase, implemented as a GADT (but see DynamicEventSelector for a generic option).

Fields make up the basic data captured in an event. They should be added to an Event as the code progresses through various phases of work, and can be both milestone markers ("we got this far in the process") or more detailed instrumentation ("we've processed N records"). They are intended to be of a domain-specific type per unit of functionality within an instrumented codebase (but see DynamicField for a generic option).

Instrumentation then centers around Events, populated using the event manipulation functions. Events are initialized with MonadEvent functions, typically via the resource-safe event allocation functions. For an explicit alternative to MonadEvent, see Observe.Event.Explicit.

Depending on which EventBackends may end up consuming the Events, instrumentors will also need to define renderers for their selectors and fields. For example, they may need to implement values of types RenderSelectorJSON to use JSON rendering EventBackends.

Documentation

data Event m r f

An instrumentation event.

Events are the core of the instrumenting user's interface to eventuo11y. Typical usage would be to create an Event using withEvent and add fields to the Event at appropriate points in your code with addField.

m

The monad we're instrumenting in.

r

The type of event references. See reference.

f

The type of fields on this event. See addField.

hoistEvent :: (forall x. m x -> n x) -> Event m r f -> Event n r f

Hoist an Event along a given natural transformation into a new monad.

Event manipulation

addField :: Event m r f -> f -> m ()

Add a field to an Event.

Fields make up the basic data captured in an event. They should be added to an Event as the code progresses through various phases of work, and can be both milestone markers ("we got this far in the process") or more detailed instrumentation ("we've processed N records").

They are intended to be of a domain specific type per unit of functionality within an instrumented codebase (but see DynamicField for a generic option).

reference :: Event m r f -> r

Obtain a reference to an Event.

References are used to link Events together, via the newEventParent and newEventCauses fields of NewEventArgs.

References can live past when an event has been finalized.

Code being instrumented should always have r as an unconstrained type parameter, both because it is an implementation concern for EventBackends and because references are backend-specific and it would be an error to reference an event in one backend from an event in a different backend.

MonadEvent

class (forall r s. Monad (em r s), Monad (BackendMonad em)) => MonadEvent em

Monads suitable for Event-based instrumentation, with implicit EventBackend management.

See Observe.Event.Explicit for Event-based instrumentation with explicit EventBackend passing.

Note that em is an indexed monad of EventMonadKind.

Minimal complete definition

liftBackendMonad, backend, withModifiedBackend

Instances

Monad m => MonadEvent (EventT m)

Defined in Observe.Event.Class

Associated Types

type BackendMonad (EventT m) :: Type -> Type

Methods

liftBackendMonad :: forall a r (s :: SelectorKind). BackendMonad (EventT m) a -> EventT m r s a

backend :: forall r (s :: SelectorKind). EventT m r s (EnvBackend (EventT m) r s)

withModifiedBackend :: forall r (s :: SelectorKind) r' (s' :: SelectorKind) a. (EnvBackend (EventT m) r s -> EnvBackend (EventT m) r' s') -> EventT m r' s' a -> EventT m r s a

(MonadEvent em, MonadTransControl t, forall r (s :: SelectorKind). Monad (t (em r s))) => MonadEvent (TransEventMonad t em)

Defined in Observe.Event.Class

Associated Types

type BackendMonad (TransEventMonad t em) :: Type -> Type

Methods

liftBackendMonad :: forall a r (s :: SelectorKind). BackendMonad (TransEventMonad t em) a -> TransEventMonad t em r s a

backend :: forall r (s :: SelectorKind). TransEventMonad t em r s (EnvBackend (TransEventMonad t em) r s)

withModifiedBackend :: forall r (s :: SelectorKind) r' (s' :: SelectorKind) a. (EnvBackend (TransEventMonad t em) r s -> EnvBackend (TransEventMonad t em) r' s') -> TransEventMonad t em r' s' a -> TransEventMonad t em r s a

type EnvEvent em r s = Event (em r s) r

An Event in a MonadEvent

Resource-safe event allocation

data NewEventArgs r s f

Arguments specifying how an Event should be created.

See simpleNewEventArgs for a simple case.

Constructors

NewEventArgs

Fields

• newEventSelector :: !(s f)

  The selector specifying the category of new Event we're creating, as well as the type of fields that can be added to it (with addField).

  Selectors are intended to be of a domain specific type per unit of functionality within an instrumented codebase, implemented as a GADT (but see DynamicEventSelector for a generic option).

• newEventParent :: !(Maybe r)

  The parent of the new Event, if any.

  Typically handled automatically via withEvent.

• newEventCauses :: ![r]

  The proximate causes of the new Event, if any.

• newEventInitialFields :: ![f]

  Fields set at the creation of the Event.

  See addField.

emitImmediateEvent' :: MonadEvent em => NewEventArgs r s f -> em r s r

Create an event which has no duration and is immediately finalized successfully.

Returns a reference to the event.

withEvent :: MonadWithEvent em => forall f. s f -> (EnvEvent em r s f -> em r s a) -> em r s a

Run an action with a new Event, selected by the given selector.

The selector specifies the category of new event we're creating, as well as the type of fields that can be added to it (with addField).

Selectors are intended to be of a domain specific type per unit of functionality within an instrumented codebase, implemented as a GADT (but see DynamicEventSelector for a generic option).

Within the nested action, all new parentless Events will be made children of the new Event.

The Event will be finalized at the end of the nested action.

withEventArgs :: MonadWithEvent em => forall f. NewEventArgs r s f -> (EnvEvent em r s f -> em r s a) -> em r s a

Run an action with a new Event, specified by the given NewEventArgs

Within the nested action, all new parentless Events will be made children of the new Event.

The Event will be finalized at the end of the nested action.

withNarrowingEvent :: MonadWithEvent em => InjectSelector s t -> forall f. t f -> (EnvEvent em r s f -> em r s x) -> em r t x

Run an action with a new Event , selected by a given selector, with a narrower sub-selector type.

The selector specifies the category of new event we're creating, as well as the type of fields that can be added to it (with addField).

Selectors are intended to be of a domain specific type per unit of functionality within an instrumented codebase, implemented as a GADT (but see DynamicEventSelector for a generic option).

Within the nested action, all new parentless Events will be made children of the new Event, and all new Events will be selected by the narrower selector type.

The Event will be finalized at the end of the nested action.

withNarrowingEventArgs :: MonadWithEvent em => InjectSelector s t -> forall f. NewEventArgs r t f -> (EnvEvent em r s f -> em r s x) -> em r t x

Run an action with a new Event , specified by the given NewEventArgs, with a narrower sub-selector type.

Within the nested action, all new parentless Events will be made children of the new Event, and all new Events will be selected by the narrower selector type.

The Event will be finalized at the end of the nested action.

type InjectSelector s t = forall f. s f -> forall a. (forall g. t g -> (f -> g) -> a) -> a

Inject a narrower selector and its fields into a wider selector.

See injectSelector for a simple way to construct one of these.

injectSelector :: (forall f. s f -> t f) -> InjectSelector s t

Construct an InjectSelector with a straightforward injection from s to t

idInjectSelector :: InjectSelector s s

The identity InjectSelector

class (MonadEvent em, forall r s. MonadWithExceptable (em r s)) => MonadWithEvent em

A MonadEvent suitable for running the withEvent family of functions

Instances

(MonadEvent em, forall r (s :: SelectorKind). MonadWithExceptable (em r s)) => MonadWithEvent em

Defined in Observe.Event

allocateEvent :: (MonadEvent em, Exceptable e) => forall f. s f -> GeneralAllocate (em r s) e () releaseArg (EnvEvent em r s f)

Allocate a new Event, selected by the given selector.

The selector specifies the category of new event we're creating, as well as the type of fields that can be added to it (with addField).

Selectors are intended to be of a domain specific type per unit of functionality within an instrumented codebase, implemented as a GADT (but see DynamicEventSelector for a generic option).

The Event will be automatically finalized on release.

allocateEventArgs :: (MonadEvent em, Exceptable e) => forall f. NewEventArgs r s f -> GeneralAllocate (em r s) e () releaseArg (EnvEvent em r s f)

Allocate a new Event, specified by the given NewEventArgs.

The Event will be automatically finalized on release.

EventT

data EventT m r s a

Make a monad into a MonadEvent.

Instances

MonadBaseControl b m => MonadBaseControl b (EventT m r s)

Defined in Observe.Event.Class

Associated Types

type StM (EventT m r s) a

Methods

liftBaseWith :: (RunInBase (EventT m r s) b -> b a) -> EventT m r s a

restoreM :: StM (EventT m r s) a -> EventT m r s a

MonadError e m => MonadError e (EventT m r s)

Defined in Observe.Event.Class

Methods

throwError :: e -> EventT m r s a

catchError :: EventT m r s a -> (e -> EventT m r s a) -> EventT m r s a

MonadReader r m => MonadReader r (EventT m ref s)

Defined in Observe.Event.Class

Methods

ask :: EventT m ref s r

local :: (r -> r) -> EventT m ref s a -> EventT m ref s a

reader :: (r -> a) -> EventT m ref s a

MonadState s' m => MonadState s' (EventT m r s)

Defined in Observe.Event.Class

Methods

get :: EventT m r s s'

put :: s' -> EventT m r s ()

state :: (s' -> (a, s')) -> EventT m r s a

MonadWriter w m => MonadWriter w (EventT m r s)

Defined in Observe.Event.Class

Methods

writer :: (a, w) -> EventT m r s a

tell :: w -> EventT m r s ()

listen :: EventT m r s a -> EventT m r s (a, w)

pass :: EventT m r s (a, w -> w) -> EventT m r s a

MonadBase b m => MonadBase b (EventT m r s)

Defined in Observe.Event.Class

Methods

liftBase :: b α -> EventT m r s α

Monad m => MonadEvent (EventT m)

Defined in Observe.Event.Class

Associated Types

type BackendMonad (EventT m) :: Type -> Type

Methods

liftBackendMonad :: forall a r (s :: SelectorKind). BackendMonad (EventT m) a -> EventT m r s a

backend :: forall r (s :: SelectorKind). EventT m r s (EnvBackend (EventT m) r s)

withModifiedBackend :: forall r (s :: SelectorKind) r' (s' :: SelectorKind) a. (EnvBackend (EventT m) r s -> EnvBackend (EventT m) r' s') -> EventT m r' s' a -> EventT m r s a

MonadFail m => MonadFail (EventT m r s)

Defined in Observe.Event.Class

Methods

fail :: String -> EventT m r s a

MonadFix m => MonadFix (EventT m r s)

Defined in Observe.Event.Class

Methods

mfix :: (a -> EventT m r s a) -> EventT m r s a

MonadIO m => MonadIO (EventT m r s)

Defined in Observe.Event.Class

Methods

liftIO :: IO a -> EventT m r s a

MonadZip m => MonadZip (EventT m r s)

Defined in Observe.Event.Class

Methods

mzip :: EventT m r s a -> EventT m r s b -> EventT m r s (a, b)

mzipWith :: (a -> b -> c) -> EventT m r s a -> EventT m r s b -> EventT m r s c

munzip :: EventT m r s (a, b) -> (EventT m r s a, EventT m r s b)

Contravariant m => Contravariant (EventT m r s)

Defined in Observe.Event.Class

Methods

contramap :: (a' -> a) -> EventT m r s a -> EventT m r s a'

(>$) :: b -> EventT m r s b -> EventT m r s a

Alternative m => Alternative (EventT m r s)

Defined in Observe.Event.Class

Methods

empty :: EventT m r s a

(<|>) :: EventT m r s a -> EventT m r s a -> EventT m r s a

some :: EventT m r s a -> EventT m r s [a]

many :: EventT m r s a -> EventT m r s [a]

Applicative m => Applicative (EventT m r s)

Defined in Observe.Event.Class

Methods

pure :: a -> EventT m r s a

(<*>) :: EventT m r s (a -> b) -> EventT m r s a -> EventT m r s b

liftA2 :: (a -> b -> c) -> EventT m r s a -> EventT m r s b -> EventT m r s c

(*>) :: EventT m r s a -> EventT m r s b -> EventT m r s b

(<*) :: EventT m r s a -> EventT m r s b -> EventT m r s a

Functor m => Functor (EventT m r s)

Defined in Observe.Event.Class

Methods

fmap :: (a -> b) -> EventT m r s a -> EventT m r s b

(<$) :: a -> EventT m r s b -> EventT m r s a

Monad m => Monad (EventT m r s)

Defined in Observe.Event.Class

Methods

(>>=) :: EventT m r s a -> (a -> EventT m r s b) -> EventT m r s b

(>>) :: EventT m r s a -> EventT m r s b -> EventT m r s b

return :: a -> EventT m r s a

MonadPlus m => MonadPlus (EventT m r s)

Defined in Observe.Event.Class

Methods

mzero :: EventT m r s a

mplus :: EventT m r s a -> EventT m r s a -> EventT m r s a

MonadCatch m => MonadCatch (EventT m r s)

Defined in Observe.Event.Class

Methods

catch :: Exception e => EventT m r s a -> (e -> EventT m r s a) -> EventT m r s a

MonadMask m => MonadMask (EventT m r s)

Defined in Observe.Event.Class

Methods

mask :: ((forall a. EventT m r s a -> EventT m r s a) -> EventT m r s b) -> EventT m r s b

uninterruptibleMask :: ((forall a. EventT m r s a -> EventT m r s a) -> EventT m r s b) -> EventT m r s b

generalBracket :: EventT m r s a -> (a -> ExitCase b -> EventT m r s c) -> (a -> EventT m r s b) -> EventT m r s (b, c)

MonadThrow m => MonadThrow (EventT m r s)

Defined in Observe.Event.Class

Methods

throwM :: Exception e => e -> EventT m r s a

MonadAllocate m => MonadAllocate (EventT m r s)

Defined in Observe.Event.Class

Associated Types

type AllocationContext (EventT m r s) :: Type -> Type

type GeneralReleaseKey (EventT m r s)

type AllocationException (EventT m r s)

Methods

generalAllocate :: GeneralAllocate (AllocationContext (EventT m r s)) (AllocationException (EventT m r s)) () () a -> EventT m r s (GeneralReleaseKey (EventT m r s), a)

generalRegister :: (GeneralReleaseType (AllocationException (EventT m r s)) () -> AllocationContext (EventT m r s) ()) -> EventT m r s (GeneralReleaseKey (EventT m r s))

generalRelease :: GeneralReleaseKey (EventT m r s) -> AllocationContext (EventT m r s) ()

MonadWith m => MonadWith (EventT m r s)

Defined in Observe.Event.Class

Associated Types

type WithException (EventT m r s)

Methods

stateThreadingGeneralWith :: GeneralAllocate (EventT m r s) (WithException (EventT m r s)) releaseReturn b a -> (a -> EventT m r s b) -> EventT m r s (b, releaseReturn)

MonadCont m => MonadCont (EventT m r s)

Defined in Observe.Event.Class

Methods

callCC :: ((a -> EventT m r s b) -> EventT m r s a) -> EventT m r s a

PrimMonad m => PrimMonad (EventT m r s)

Defined in Observe.Event.Class

Associated Types

type PrimState (EventT m r s)

Methods

primitive :: (State# (PrimState (EventT m r s)) -> (# State# (PrimState (EventT m r s)), a #)) -> EventT m r s a

MonadUnliftIO m => MonadUnliftIO (EventT m r s)

Defined in Observe.Event.Class

Methods

withRunInIO :: ((forall a. EventT m r s a -> IO a) -> IO b) -> EventT m r s b

type BackendMonad (EventT m)

Defined in Observe.Event.Class

type BackendMonad (EventT m) = m

type AllocationContext (EventT m r s)

Defined in Observe.Event.Class

type AllocationContext (EventT m r s) = AllocationContext (ReaderT (EventBackend m r s) m)

type AllocationException (EventT m r s)

Defined in Observe.Event.Class

type AllocationException (EventT m r s) = AllocationException (ReaderT (EventBackend m r s) m)

type GeneralReleaseKey (EventT m r s)

Defined in Observe.Event.Class

type GeneralReleaseKey (EventT m r s) = GeneralReleaseKey (ReaderT (EventBackend m r s) m)

type WithException (EventT m r s)

Defined in Observe.Event.Class

type WithException (EventT m r s) = WithException m

type PrimState (EventT m r s)

Defined in Observe.Event.Class

type PrimState (EventT m r s) = PrimState (ReaderT (EventBackend m r s) m)

type StM (EventT m r s) a

Defined in Observe.Event.Class

type StM (EventT m r s) a = StM (ReaderT (EventBackend m r s) m) a

runEventT :: Monad m => EventT m r s a -> EventBackend m r s -> m a

Run an EventT with an initial EventBackend.

eventLift :: forall m r s. Applicative m => StatelessControlTransformation m (EventT m r s)

Lift m into EventT m.

TransEventMonad

newtype TransEventMonad t em r s a

Apply a MonadTransformer to an EventMonadKind to get a transformed EventMonadKind

When t is MonadTransControl and em is MonadEvent, TransEventMonad t em is MonadEvent and has all of the relevant instances conferred by t.

Constructors

TransEventMonad

Fields

• unTransEventMonad :: t (em r s) a

Instances

MonadBaseControl b (t (em r s)) => MonadBaseControl b (TransEventMonad t em r s)

Defined in Observe.Event.Class

Associated Types

type StM (TransEventMonad t em r s) a

Methods

liftBaseWith :: (RunInBase (TransEventMonad t em r s) b -> b a) -> TransEventMonad t em r s a

restoreM :: StM (TransEventMonad t em r s) a -> TransEventMonad t em r s a

MonadError e (t (em r s)) => MonadError e (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

throwError :: e -> TransEventMonad t em r s a

catchError :: TransEventMonad t em r s a -> (e -> TransEventMonad t em r s a) -> TransEventMonad t em r s a

MonadReader r' (t (em r s)) => MonadReader r' (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

ask :: TransEventMonad t em r s r'

local :: (r' -> r') -> TransEventMonad t em r s a -> TransEventMonad t em r s a

reader :: (r' -> a) -> TransEventMonad t em r s a

MonadState s' (t (em r s)) => MonadState s' (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

get :: TransEventMonad t em r s s'

put :: s' -> TransEventMonad t em r s ()

state :: (s' -> (a, s')) -> TransEventMonad t em r s a

MonadWriter w (t (em r s)) => MonadWriter w (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

writer :: (a, w) -> TransEventMonad t em r s a

tell :: w -> TransEventMonad t em r s ()

listen :: TransEventMonad t em r s a -> TransEventMonad t em r s (a, w)

pass :: TransEventMonad t em r s (a, w -> w) -> TransEventMonad t em r s a

MonadBase b (t (em r s)) => MonadBase b (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

liftBase :: b α -> TransEventMonad t em r s α

(MonadEvent em, MonadTransControl t, forall r (s :: SelectorKind). Monad (t (em r s))) => MonadEvent (TransEventMonad t em)

Defined in Observe.Event.Class

Associated Types

type BackendMonad (TransEventMonad t em) :: Type -> Type

Methods

liftBackendMonad :: forall a r (s :: SelectorKind). BackendMonad (TransEventMonad t em) a -> TransEventMonad t em r s a

backend :: forall r (s :: SelectorKind). TransEventMonad t em r s (EnvBackend (TransEventMonad t em) r s)

withModifiedBackend :: forall r (s :: SelectorKind) r' (s' :: SelectorKind) a. (EnvBackend (TransEventMonad t em) r s -> EnvBackend (TransEventMonad t em) r' s') -> TransEventMonad t em r' s' a -> TransEventMonad t em r s a

MonadFail (t (em r s)) => MonadFail (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

fail :: String -> TransEventMonad t em r s a

MonadFix (t (em r s)) => MonadFix (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

mfix :: (a -> TransEventMonad t em r s a) -> TransEventMonad t em r s a

MonadIO (t (em r s)) => MonadIO (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

liftIO :: IO a -> TransEventMonad t em r s a

MonadZip (t (em r s)) => MonadZip (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

mzip :: TransEventMonad t em r s a -> TransEventMonad t em r s b -> TransEventMonad t em r s (a, b)

mzipWith :: (a -> b -> c) -> TransEventMonad t em r s a -> TransEventMonad t em r s b -> TransEventMonad t em r s c

munzip :: TransEventMonad t em r s (a, b) -> (TransEventMonad t em r s a, TransEventMonad t em r s b)

Contravariant (t (em r s)) => Contravariant (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

contramap :: (a' -> a) -> TransEventMonad t em r s a -> TransEventMonad t em r s a'

(>$) :: b -> TransEventMonad t em r s b -> TransEventMonad t em r s a

Alternative (t (em r s)) => Alternative (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

empty :: TransEventMonad t em r s a

(<|>) :: TransEventMonad t em r s a -> TransEventMonad t em r s a -> TransEventMonad t em r s a

some :: TransEventMonad t em r s a -> TransEventMonad t em r s [a]

many :: TransEventMonad t em r s a -> TransEventMonad t em r s [a]

Applicative (t (em r s)) => Applicative (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

pure :: a -> TransEventMonad t em r s a

(<*>) :: TransEventMonad t em r s (a -> b) -> TransEventMonad t em r s a -> TransEventMonad t em r s b

liftA2 :: (a -> b -> c) -> TransEventMonad t em r s a -> TransEventMonad t em r s b -> TransEventMonad t em r s c

(*>) :: TransEventMonad t em r s a -> TransEventMonad t em r s b -> TransEventMonad t em r s b

(<*) :: TransEventMonad t em r s a -> TransEventMonad t em r s b -> TransEventMonad t em r s a

Functor (t (em r s)) => Functor (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

fmap :: (a -> b) -> TransEventMonad t em r s a -> TransEventMonad t em r s b

(<$) :: a -> TransEventMonad t em r s b -> TransEventMonad t em r s a

Monad (t (em r s)) => Monad (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

(>>=) :: TransEventMonad t em r s a -> (a -> TransEventMonad t em r s b) -> TransEventMonad t em r s b

(>>) :: TransEventMonad t em r s a -> TransEventMonad t em r s b -> TransEventMonad t em r s b

return :: a -> TransEventMonad t em r s a

MonadPlus (t (em r s)) => MonadPlus (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

mzero :: TransEventMonad t em r s a

mplus :: TransEventMonad t em r s a -> TransEventMonad t em r s a -> TransEventMonad t em r s a

MonadCatch (t (em r s)) => MonadCatch (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

catch :: Exception e => TransEventMonad t em r s a -> (e -> TransEventMonad t em r s a) -> TransEventMonad t em r s a

MonadMask (t (em r s)) => MonadMask (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

mask :: ((forall a. TransEventMonad t em r s a -> TransEventMonad t em r s a) -> TransEventMonad t em r s b) -> TransEventMonad t em r s b

uninterruptibleMask :: ((forall a. TransEventMonad t em r s a -> TransEventMonad t em r s a) -> TransEventMonad t em r s b) -> TransEventMonad t em r s b

generalBracket :: TransEventMonad t em r s a -> (a -> ExitCase b -> TransEventMonad t em r s c) -> (a -> TransEventMonad t em r s b) -> TransEventMonad t em r s (b, c)

MonadThrow (t (em r s)) => MonadThrow (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

throwM :: Exception e => e -> TransEventMonad t em r s a

MonadAllocate (t (em r s)) => MonadAllocate (TransEventMonad t em r s)

Defined in Observe.Event.Class

Associated Types

type AllocationContext (TransEventMonad t em r s) :: Type -> Type

type GeneralReleaseKey (TransEventMonad t em r s)

type AllocationException (TransEventMonad t em r s)

Methods

generalAllocate :: GeneralAllocate (AllocationContext (TransEventMonad t em r s)) (AllocationException (TransEventMonad t em r s)) () () a -> TransEventMonad t em r s (GeneralReleaseKey (TransEventMonad t em r s), a)

generalRegister :: (GeneralReleaseType (AllocationException (TransEventMonad t em r s)) () -> AllocationContext (TransEventMonad t em r s) ()) -> TransEventMonad t em r s (GeneralReleaseKey (TransEventMonad t em r s))

generalRelease :: GeneralReleaseKey (TransEventMonad t em r s) -> AllocationContext (TransEventMonad t em r s) ()

MonadWith (t (em r s)) => MonadWith (TransEventMonad t em r s)

Defined in Observe.Event.Class

Associated Types

type WithException (TransEventMonad t em r s)

Methods

stateThreadingGeneralWith :: GeneralAllocate (TransEventMonad t em r s) (WithException (TransEventMonad t em r s)) releaseReturn b a -> (a -> TransEventMonad t em r s b) -> TransEventMonad t em r s (b, releaseReturn)

MonadCont (t (em r s)) => MonadCont (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

callCC :: ((a -> TransEventMonad t em r s b) -> TransEventMonad t em r s a) -> TransEventMonad t em r s a

PrimMonad (t (em r s)) => PrimMonad (TransEventMonad t em r s)

Defined in Observe.Event.Class

Associated Types

type PrimState (TransEventMonad t em r s)

Methods

primitive :: (State# (PrimState (TransEventMonad t em r s)) -> (# State# (PrimState (TransEventMonad t em r s)), a #)) -> TransEventMonad t em r s a

MonadUnliftIO (t (em r s)) => MonadUnliftIO (TransEventMonad t em r s)

Defined in Observe.Event.Class

Methods

withRunInIO :: ((forall a. TransEventMonad t em r s a -> IO a) -> IO b) -> TransEventMonad t em r s b

type BackendMonad (TransEventMonad t em)

Defined in Observe.Event.Class

type BackendMonad (TransEventMonad t em) = BackendMonad em

type AllocationContext (TransEventMonad t em r s)

Defined in Observe.Event.Class

type AllocationContext (TransEventMonad t em r s) = AllocationContext (t (em r s))

type AllocationException (TransEventMonad t em r s)

Defined in Observe.Event.Class

type AllocationException (TransEventMonad t em r s) = AllocationException (t (em r s))

type GeneralReleaseKey (TransEventMonad t em r s)

Defined in Observe.Event.Class

type GeneralReleaseKey (TransEventMonad t em r s) = GeneralReleaseKey (t (em r s))

type WithException (TransEventMonad t em r s)

Defined in Observe.Event.Class

type WithException (TransEventMonad t em r s) = WithException (t (em r s))

type PrimState (TransEventMonad t em r s)

Defined in Observe.Event.Class

type PrimState (TransEventMonad t em r s) = PrimState (t (em r s))

type StM (TransEventMonad t em r s) a

Defined in Observe.Event.Class

type StM (TransEventMonad t em r s) a = StM (t (em r s)) a

Primitives

type family BackendMonad em :: Type -> Type

The monad of the implicitly carried EventBackend

Instances

type BackendMonad (EventT m)

Defined in Observe.Event.Class

type BackendMonad (EventT m) = m

type BackendMonad (TransEventMonad t em)

Defined in Observe.Event.Class

type BackendMonad (TransEventMonad t em) = BackendMonad em

type EnvBackend em = EventBackend (BackendMonad em)

The type of the implicit EventBackend of a MonadEvent

data EventBackend m r s

A backend for creating Events.

Different EventBackends will be used to emit instrumentation to different systems. Multiple backends can be combined with pairEventBackend.

A simple EventBackend for logging to a Handle can be created with jsonHandleBackend.

From an EventBackend, new events can be created via selectors (of type s f for some field type f), typically with the resource-safe allocation functions. Selectors are values which designate the general category of event being created, as well as the type of fields that can be added to it. For example, a web service's selector type may have a ServicingRequest constructor, whose field type includes a ResponseCode constructor which records the HTTP status code.

Selectors are intended to be of a domain specific type per unit of functionality within an instrumented codebase, implemented as a GADT (but see DynamicEventSelector for a generic option).

Implementations must ensure that EventBackends and their underlying Events are safe to use across threads.

m

The monad we're instrumenting in.

r

The type of event references used in this EventBackend. See reference.

s

The type of event selectors. See newEventSelector.

liftBackendMonad :: MonadEvent em => BackendMonad em a -> em r s a

backend :: MonadEvent em => em r s (EnvBackend em r s)

Access the implicitly carried EventBackend

withModifiedBackend

Arguments

:: MonadEvent em

=> (EnvBackend em r s -> EnvBackend em r' s')

Modify the EventBackend

Note that the modification may change the reference and selector types.

-> em r' s' a

Action to run with the modified backend available.

-> em r s a

Run an instrumented action with a modified EventBackend

Primitive Event resource management.

Prefer the resource-safe event allocation functions to these when possible.

finalize :: Event m r f -> Maybe SomeException -> m ()

Mark an Event as finished, perhaps due to an Exception.

In normal usage, this should be automatically called via the use of the resource-safe event allocation functions.

This is a no-op if the Event has already been finalized. As a result, it is likely pointless to call addField after this call, though it still may be reasonable to call reference.

newEvent' :: MonadEvent em => forall f. s f -> em r s (EnvEvent em r s f)

Create a new Event, selected by the given selector.

The selector specifies the category of new event we're creating, as well as the type of fields that can be added to it (with addField).

Selectors are intended to be of a domain specific type per unit of functionality within an instrumented codebase, implemented as a GADT (but see DynamicEventSelector for a generic option).

Consider the resource-safe event allocation functions instead of calling this directly.

newEventArgs :: MonadEvent em => forall f. NewEventArgs r s f -> em r s (EnvEvent em r s f)

Create a new Event, specified by the given NewEventArgs.

Consider the resource-safe event allocation functions instead of calling this directly.

Backend Events

Events within the BackendMonad of a MonadEvent

These are low-level primitives that can be used if the existing higher-level event allocation/backend modification combinators are insufficient

type BackendEvent em = Event (BackendMonad em)

An Event in the BackendMonad of a MonadEvent

hoistBackendEvent :: MonadEvent em => BackendEvent em r f -> EnvEvent em r s f

Bring a BackendEvent into the MonadEvent

allocateBackendEvent :: (MonadEvent em, Exceptable e) => forall f. NewEventArgs r s f -> GeneralAllocate (em r s) e () releaseArg (BackendEvent em r f)

A BackendMonad variant of allocateEventArgs.

withBackendEvent :: (MonadEvent em, MonadWithExceptable (em r s)) => forall f. NewEventArgs r s f -> (BackendEvent em r f -> em r s a) -> em r s a

Run an action with a new BackendEvent.

The Event will be finalized upon completion.

newBackendEvent :: MonadEvent em => forall f. NewEventArgs r s f -> em r s (BackendEvent em r f)

A BackendMonad variant of newEventArgs