Provides the hooks by which the result of a effectful program can be converted into a FailureDetail
for use in
determining whether the program has failed for the purposes of the trace and how to render that failure.
Provides the hooks by which the result of a effectful program can be converted into a FailureDetail
for use in
determining whether the program has failed for the purposes of the trace and how to render that failure.
If the traced program fails, the exceptionToFailure
function is used to determine if this failure should be
recorded as such for the span and if the program itself is successful, while the resultToFailure
function is used to
determine if there is an application level failure embedded in the result and if so, how it should be rendered.
The default evaluator for a span, if a custom one is not specified, is to treat a failures and successes at
the effectful program-level as such for the span, converting the Throwable
to a string with the stack trace.
This Alegraic Data Type (ADT) represents a failure of the underlying traced program, providing the means to render the failure when the span is recorded.
Represents a general header name/value.
Represents a general header name/value. Note that though it usually represents an HTTP header, it can be any key/value pair (for instance, a header in an RPC payload).
Describes functionality for encoding or decoding a
SpanId
to one or more headers.
Describes functionality for encoding or decoding a
SpanId
to one or more headers. Protocol specific modules
implement this and those implementations can be composed in order
to support headers from multiple protocols in the priority order
desired by the composer.
This data type represents metadata used to annotate a distributed trace Span.
This data type represents metadata used to annotate a distributed trace
Span. Examples of Note
s might be the input parameters to the program being executed
as part of the span, or it might be values derived from the result of that program.
- the human readable name of the Note
.
- the possible value of the Note
(or None if a note has no value when the Span is recorded).
Represents a single span for a distributed trace.
Represents a single span for a distributed trace. A span is the traced execution of an effectful program F
,
part of a possibly larger transaction that represents the trace as a whole.
- the SpanId representing this span's identity and its place in a distributed trace's hiearchy of spans.
- the human readable name of this span - it is the logical name of the effectful program whose execution this span is recording.
- the TraceSystem#Time representing the point in time at which the program started execution
- the FailureDetail is present and provides a means to render the detail of a program execution failure if the execution failed; otherwise is it not present.
- the elapsed time of the execution of the program.
- a Vector
of Notes used to annotate the program's execution with metadata, which can be derived both from
the program's inputs as well as its results.
Represents the core identity of a Span.
Represents the core identity of a Span.
- the globally unique identifier for the trace of which this span is a component.
- the parent identifier of this span. If this span is the root of the trace,
this identifier will equal the spanId
parameter.
- the identifier of this span. If this span is the root of the trace,
this identifier will equal the parentSpanId
parameter.
Represents a cursor into the "current" Span and associated system-level information and is associated with an
effectful program F[A]
to realize a trace of that program.
Represents a cursor into the "current" Span and associated system-level information and is associated with an
effectful program F[A]
to realize a trace of that program.
- an effectful program type representing the program type of the TraceSystem (which in turn indicates
the program type of the TraceSystem
's Emitter
).
- the current Span associated with a particular effectful program.
- should we actually emit a Span? Yes, if this is true when the Span is executed.
- a TraceSystem consisting of system-level information which further annotates a Span when recording it along with an implementation of an TraceSystem#Emitter used to perform the recording of the span.
Enriches an effectful program F[A]
such that TraceT instance methods are made available on it, given
the appropriate typeclasses in implicit scope.
Type alias provided for convenience when using an IO
as the type of effectful
program being traced.
System level configuration for the trace system.
System level configuration for the trace system.
- an effectful program type used to execute the Emitter
and Timer
.
- top-level system-level information that should be included in all trace span recordings (examples include: identity, node, deployment, and environment information). It is separated into identity and metadata as a hint to the emitters to emit directly as part of the span recording or to emit in an appropriate metadata structure.
- TraceSystem#Emitter responsible for actually recording the span information for a distributed trace to some external sink (e.g., log file, remote database, JMX, etc.).
- TraceSystem#Timer responsible for generating timer to measure performance of Spans.
This is the main construct of the library.
This is the main construct of the library. It represents a function TraceContext => F[A]
for an arbitrary F[_]
effectful program, conceptually similiar to a cats.data.Kleisli
.
The TraceContext holds the "current" Span information for the program F[A]
and
this information, along with timing and result data derived when F[A]
is run, is recorded
via the Emitter
, also included in the TraceContext, when the F[A]
execution is complete.
This class is never instantiated by API users; rather, instances are created via as needed via
the public instance and companion object methods described below.
- a type constructor representing the effect which is traced.
- the result of the effect which is traced.
This companion object for Evaluator
instances provides smart constructors and a default
value should no
custom Evaluator
be used when recording a span.
The FailureDetail
companion consists of the enumerated concrete FailureDetail
data types.
The companion to the Note
instances defines the Note.Name
data type and the
associated Note.Value
ADT, as well as providing convenience constructors for the different
value types.
Companion object of the SpanId
datatype.
Companion object of the SpanId
datatype. Provides smart constructors and commonly used constants.
Companion to the TraceIO[A]
type alias - provides the TraceT smart constructors with the effectful
program F
fixed as IO
.
The TraceT
companion provides smart constructors for desired TraceT
instances and
type class isntances.
The distributed trace (dtrace) library provides the means to derive and record a distributed trace across effectful programs given the appropriate typeclasses for that program in implicit scope. The effectful programs are enhanced via a
Kleisli
-like data type, TraceT, which encodes the information to calculate and record a trace Span at the conclusion of the program execution.