Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
, using the passed-in Evaluator
to determine the program's success/failure status.
Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
, using the passed-in Evaluator
to determine the program's success/failure status. In addition, when the effectful program
is run, annotate the associated Span with Notes derived from the result of its run, using the passed-in function.
the TraceContext to use in generating the trace -- usually this contains the root Span (or at least the root span of trace for the virtual machine it is running in).
an Evaluator which converts either a Throwable
or A
to an optional FailureDetail
a variable argument list of Notes used to annotate the current Span.
a partial function which is passed an Either[Throwable, A]
as the result of the underlying program's run and which
returns a Vector
of zero or more Notes, possibly derived from the input result.
the underlying effectful program F[A]
that, when run, will calculate and record the trace of its execution.
Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
.
Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
. In addition, when the effectful program
is run, annotate the associated Span with Notes derived from the result of its run, using the passed-in function.
the TraceContext to use in generating the trace -- usually this contains the root Span (or at least the root span of trace for the virtual machine it is running in).
a variable argument list of Notes used to annotate the current Span.
a partial function which is passed an Either[Throwable, A]
as the result of the underlying program's run and which
returns a Vector
of zero or more Notes, possibly derived from the input result.
the underlying effectful program F[A]
that, when run, will calculate and record the trace of its execution.
When passed a top-level TraceContext, convert this TraceT
into its underlying effectful
program enhanced with the capability of tracing its execution.
When passed a top-level TraceContext, convert this TraceT
into its underlying effectful
program enhanced with the capability of tracing its execution.
the top-level TraceContext to apply to the TraceT
in order to transform it
to an F[A]
.
the underlying F[A]
enhanced to trace its execution.
Transforms this TraceT[F, A]
to a TraceT[F, Either[Throwable, A]]
where the left-hand side of the
Either
represents a failure of the underlying program F
and the right-hand side represents the
successful result.
Transforms this TraceT[F, A]
to a TraceT[F, Either[Throwable, A]]
where the left-hand side of the
Either
represents a failure of the underlying program F
and the right-hand side represents the
successful result. It is a way of handling non-fatal errors by turning them into scala.util.Either
values.
a TraceT[F, Either[Throwable, A]]
indicating that the underlying effectful program F
will not fail at the program level but rather will indicate success/failure at the application level via its
Either[Throwable, A]
result type.
Returns a TraceT[F, ?]
action that treats the source task as the
acquisition of a resource, which is then exploited by the use
function and then released
.
Returns a TraceT[F, ?]
action that treats the source task as the
acquisition of a resource, which is then exploited by the use
function and then released
.
The bracket
operation is the equivalent of the
try {} catch {} finally {}
statements from mainstream languages.
The bracket
operation installs the necessary exception handler
to release the resource in the event of an exception being raised
during the computation, or in case of cancellation.
If an exception is raised, then bracket
will re-raise the
exception after performing the release
. If the resulting
task gets canceled, then bracket
will still perform the
release
, but the yielded task will be non-terminating
(equivalent with IO.never
when F
is IO
, for example]).
See IO.bracket
scaladoc for further detail.
is a function that evaluates the resource yielded by
the source, yielding a result that will get generated by
the task returned by this bracket
function
is a function that gets called after use
terminates, either normally or in error, or if it gets
canceled, receiving as input the resource that needs to
be released
Returns a new TraceT[F, ?]
task that treats the source task as the
acquisition of a resource, which is then exploited by the use
function and then released
, with the possibility of
distinguishing between normal termination and cancellation, such
that an appropriate release of resources can be executed.
Returns a new TraceT[F, ?]
task that treats the source task as the
acquisition of a resource, which is then exploited by the use
function and then released
, with the possibility of
distinguishing between normal termination and cancellation, such
that an appropriate release of resources can be executed.
The bracketCase
operation is the equivalent of
try {} catch {} finally {}
statements from mainstream languages
when used for the acquisition and release of resources.
The bracketCase
operation installs the necessary exception handler
to release the resource in the event of an exception being raised
during the computation, or in case of cancellation.
In comparison with the simpler bracket version, this one
allows the caller to differentiate between normal termination,
termination in error and cancellation via an ExitCase
parameter.
is a function that evaluates the resource yielded by the source, yielding a result that will get generated by this function on evaluation
is a function that gets called after use
terminates, either normally or in error, or if it gets
canceled, receiving as input the resource that needs that
needs release, along with the result of use
(cancellation, error or successful result)
Generates a new TraceT[F, B]
from this instance using the supplied function A => TraceT[F, B]
.
Generates a new TraceT[F, B]
from this instance using the supplied function A => TraceT[F, B]
.
function from A
=> TraceT[F, B]
_Note that because TraceT[F, ?]
needs to apply its function of TraceContext[F] => F[?]
in order to
map over the underlying value, in order for it to be stack-safe, F
needs to have a Monad[F]
in
implicit scope in order to create a pure F in the suspension of the effect. This isn't a compile-time
requirement as you can have a non-stack-safe flatMap with just a FlatMap[F]
in scope as long
as you know you will not have deeply nested maps._
Returns a TraceT[F, ?]
action that ensures the finalizer
is always run.
Returns a TraceT[F, ?]
action that ensures the finalizer
is always run.
The guarantee
operation is the equivalent of the
try {} catch {} finally {}
statements from mainstream languages.
is an action that gets executed whoever this trace terminates, either normally or in error, or if it gets canceled
Returns a new TraceT[F, ?]
task that ensures the 'finalizer'
function is always run, with the possibility of
distinguishing between normal termination and cancellation.
Returns a new TraceT[F, ?]
task that ensures the 'finalizer'
function is always run, with the possibility of
distinguishing between normal termination and cancellation.
during the computation, or in case of cancellation.
In comparison with the simpler guarantee version, this one
allows the caller to differentiate between normal termination,
termination in error and cancellation via an ExitCase
parameter.
is a function that gets called after this trace
terminates, either normally or in error, or if it gets
canceled, receiving as input the result of use
(cancellation, error or successful result)
Handles an error by mapping it to a new TraceT
.
Handles an error by mapping it to a new TraceT
.
handler function which maps an error to a new TraceT
, possibly by recovering from it
new TraceT[F, A]
with error handling of the aforementioned f
function
Generates a new TraceT[F, B]
from this instance using the supplied function A => B
.
Generates a new TraceT[F, B]
from this instance using the supplied function A => B
.
function from A
=> B
_Note that because TraceT[F, ?]
needs to apply its function of TraceContext[F] => F[?]
in order to
map over the underlying value, in order for it to be stack-safe, F
needs to have a Monad[F]
in
implicit scope. This isn't a compile-time requirement as you can have a non-stack-safe map as long
as you know you will not have deeply nested maps._
Creates a new child Span from the current span represented by this instance, providing the capability
of annotating the span with notes based on the execution result of the F[A]
, using the
a custom Evaluator to determine success/failure of the F[A]
for the purposes of recording.
Creates a new child Span from the current span represented by this instance, providing the capability
of annotating the span with notes based on the execution result of the F[A]
, using the
a custom Evaluator to determine success/failure of the F[A]
for the purposes of recording.
For example:
queryProductsTraceT.newAnnotatedSpan( Span.Name("query-products-for-sale", Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) ) { case Right(saleProducts) => Vector(Note.string("sale-products", saleProducts.mkString(","))) }
a descriptive name, emitted when the span is recorded.
one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
a new instance of TraceT
representing a child span of this
.
Creates a new child Span from the current span represented by this instance, providing the capability
of annotating the span with notes based on the execution result of the F[A]
, using the
default Evaluator to determine success/failure of the F[A]
for the purposes of recording.
Creates a new child Span from the current span represented by this instance, providing the capability
of annotating the span with notes based on the execution result of the F[A]
, using the
default Evaluator to determine success/failure of the F[A]
for the purposes of recording.
For example:
queryProductsTraceT.newAnnotatedSpan( Span.Name("query-products-for-sale", Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) ) { case Right(saleProducts) => Vector(Note.string("sale-products", saleProducts.mkString(","))) }
a descriptive name, emitted when the span is recorded.
one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
a new instance of TraceT
representing a child span of this
.
Creates a new child span from the current span represented by this instance, providing for custom
evaluation and rendering of the underlying F[A]
when recording the Span.
Creates a new child span from the current span represented by this instance, providing for custom
evaluation and rendering of the underlying F[A]
when recording the Span.
queryProductsTraceT.newSpan( Span.Name("query-products-for-sale", Evaluator.resultToFailure[Vector[Product] Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) )
a descriptive name, emitted when the span is recorded.
an Evaluator which converts either a Throwable
or A
to an optional FailureDetail.
one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
a new instance of TraceT
representing a child span of this
.
Creates a new child Span from the current span represented by this instance, using the
default Evaluator to determine success/failure of the F[A]
for the purposes of span recording.
Creates a new child Span from the current span represented by this instance, using the
default Evaluator to determine success/failure of the F[A]
for the purposes of span recording.
For example:
queryProductsTraceT.newSpan( Span.Name("query-products-for-sale", Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) )
a descriptive name, emitted when the span is recorded.
one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
a new instance of TraceT
representing a child span of this
.
Lifts this program F
which computes A
into a TraceT[F, A]
context.
Lifts this program F
which computes A
into a TraceT[F, A]
context.
traceTOfA - a TraceT[F, A]
Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
, using the passed-in Evaluator
to determine the program's success/failure status.
Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
, using the passed-in Evaluator
to determine the program's success/failure status.
the TraceContext to use in generating the trace -- usually this contains the root Span (or at least the root span of trace for the virtual machine it is running in).
an Evaluator which converts either a Throwable
or A
to an optional FailureDetail
a variable argument list of Notes used to annotate the current Span.
the underlying effectful program F[A]
that, when run, will calculate and record the trace of its execution.
Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
.
Given the (usually) root TraceContext, convert this TraceT[A]
to its underlying effectful program F[A]
.
the TraceContext to use in generating the trace -- usually this contains the root Span (or at least the root span of trace for the virtual machine it is running in).
a variable argument list of Notes used to annotate the current Span.
the underlying effectful program F[A]
that, when run, will calculate and record the trace of its execution.
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
, providing the capability
of annotating the span with notes based on the execution result of the F[A]
, using the
a custom Evaluator to determine success/failure of the F[A]
for the purposes of recording.
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
, providing the capability
of annotating the span with notes based on the execution result of the F[A]
, using the
a custom Evaluator to determine success/failure of the F[A]
for the purposes of recording.
For example:
val io = IO(some computation) io.newAnnotatedSpan( Span.Name("query-products-for-sale", Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) ) { case Right(saleProducts) => Vector(Note.string("sale-products", saleProducts.mkString(","))) }
- a descriptive name, emitted when the span is recorded.
- one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
newTraceT - a new instance of TraceT
representing a child span.
(traceT: TraceEnrichedEffect[[A]TraceT[F, A], A]).newAnnotatedSpan(spanName, evaluator, notes)(resultAnnotator)(F)
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
,
providing the capability of annotating the span with notes based on the execution result of the F[A]
,
using the default Evaluator to determine success/failure of the F[A]
for the purposes of span recording.
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
,
providing the capability of annotating the span with notes based on the execution result of the F[A]
,
using the default Evaluator to determine success/failure of the F[A]
for the purposes of span recording.
For example:
val io = IO(some computation) io.newAnnotatedSpan( Span.Name("query-products-for-sale", Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) ) { case Right(saleProducts) => Vector(Note.string("sale-products", saleProducts.mkString(","))) }
- a descriptive name, emitted when the span is recorded.
- one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
newTraceT - a new instance of TraceT
representing a child span.
(traceT: TraceEnrichedEffect[[A]TraceT[F, A], A]).newAnnotatedSpan(spanName, notes)(resultAnnotator)(F)
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
, providing for custom
evaluation and rendering of the underlying F[A]
when recording the Span.
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
, providing for custom
evaluation and rendering of the underlying F[A]
when recording the Span.
For example:
val io = IO(some computation) io.newSpan( Span.Name("query-products-for-sale", Evaluator.resultToFailure[Vector[Product] Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) )
- a descriptive name, emitted when the span is recorded.
- an Evaluator which converts either a Throwable
or A
to an optional FailureDetail.
- one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
newTraceT - a new instance of TraceT
representing a child span.
(traceT: TraceEnrichedEffect[[A]TraceT[F, A], A]).newSpan(spanName, evaluator, notes)(F)
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
, using the
default Evaluator to determine success/failure of the F[A]
for the purposes of span recording.
Creates a new child Span in the TraceT[F, A]
created by lifting this F[A]
, using the
default Evaluator to determine success/failure of the F[A]
for the purposes of span recording.
For example:
val io = IO(some computation) io.newSpan( Span.Name("query-products-for-sale", Note.string("sale-date", date.toString), Note.double("sale-max-price", 80.50) )
- a descriptive name, emitted when the span is recorded.
- one or more Notes which annotate the span (often the input parameters to the F[A]
execution).
a new instance of TraceT
representing a child span.
(traceT: TraceEnrichedEffect[[A]TraceT[F, A], A]).newSpan(spanName, notes)(F)
Lifts this F[A]
into a TraceT[F, A] and then transforms that
TraceT to an equivalent
TraceT[F, A] where
the passed-in function will be executed at the finish of the underlying effectful program.
Lifts this F[A]
into a TraceT[F, A] and then transforms that
TraceT to an equivalent
TraceT[F, A] where
the passed-in function will be executed at the finish of the underlying effectful program.
- a function which is passed an optional Throwable
- defined if the program failed and
returns a TraceT[F, Unit]
, a program run only for its effect.
a new TraceT[F, A]
with the error handling of the aforementioned f
function
parameter.
(traceT: TraceEnrichedEffect[[A]TraceT[F, A], A]).bestEffortOnFinish(f)(F)
(Since version 1.5.0) use guaranteeCase on effect
Transforms this TraceT[F, A]
to an equivalent TraceT[F, A]
where a best-effort will be made
to execute the passed-in function on the finish of the underlying effectful program.
Transforms this TraceT[F, A]
to an equivalent TraceT[F, A]
where a best-effort will be made
to execute the passed-in function on the finish of the underlying effectful program. The function can't
be guaranteed to run in the face of interrupts, etc. It depends on the nature of the effectful program
itself.
function which is passed an optional Throwable
- defined if the program failed and
returns a TraceT[F, Unit]
, a program run only for its effect.
new TraceT[F, A]
with the error handling of the aforementioned f
function
(Since version 1.5.0) Use guaranteeCase instead
(Since version ) see corresponding Javadoc for more information.
This is the main construct of the library. It represents a function
TraceContext => F[A]
for an arbitraryF[_]
effectful program, conceptually similiar to acats.data.Kleisli
. The TraceContext holds the "current" Span information for the programF[A]
and this information, along with timing and result data derived whenF[A]
is run, is recorded via theEmitter
, also included in the TraceContext, when theF[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.