Observe.Event.Implementation

This is the primary module needed to write new EventBackends.

Documentation

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.

Typically the entrypoint for some eventuo11y-instrumented code will take an EventBackend, polymorphic in r and possibly m. Calling code can use subEventBackend to place the resulting events in its hierarchy.

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.

Constructors

EventBackend

Fields

• newEventImpl :: !(forall f. s f -> m (EventImpl m r f))

  Create a new EventImpl corresponding to the given selector.

• newOnceFlag :: !(m (OnceFlag m))

  Allocate a new OnceFlag in our monad.

data EventImpl m r f

The internal implementation of an Event.

All fields have corresponding event manipulation functions, except that finalizeImpl and failImpl can assume that they will only ever be called once (i.e., EventImpl implementations do not have to implement locking internally).

Constructors

EventImpl

Fields

• referenceImpl :: !r
• addFieldImpl :: !(f -> m ())
• addParentImpl :: !(r -> m ())
• addProximateImpl :: !(r -> m ())
• finalizeImpl :: !(m ())
• failImpl :: !(Maybe SomeException -> m ())

OnceFlags

Generic helper to make operations idempotent.

newtype OnceFlag m

A flag to ensure only one operation from some class is performed, once.

Typically consumed via runOnce

Constructors

OnceFlag

Fields

• checkAndSet :: m FlagState

  Get the state of the OnceFlag, and set the flag.

  This operation should be atomic, and ideally would only return NewlySet once. In monads that don't support it, at a minimum it must be monotonic (once one caller gets AlreadySet, all callers will).

data FlagState

The state of a OnceFlag

Constructors

NewlySet

The flag was not set, but is now

AlreadySet

The flag was already set

runOnce :: Monad m => OnceFlag m -> m () -> m ()

Run an operation if no other operations using this OnceFlag have run.

hoistOnceFlag

Arguments

:: (forall x. f x -> g x)

Natural transformation from f to g

-> OnceFlag f

-> OnceFlag g

Hoist a OnceFlag along a given natural transformation into a new monad.

alwaysNewOnceFlag :: Applicative m => OnceFlag m

A OnceFlag which is always NewlySet.

Only safe to use if the operations to be guarded by the flag are already idempotent.

newOnceFlagIO :: IO (OnceFlag IO)

A OnceFlag in IO using an MVar.