View Source HatchTracing (HatchTracing v0.1.0)
Tracing features for elixir apps.
Just call use HatchTracing
in a module and you're good to go.
You'll probably just need to use the span
functions, as the other functions
are here just for compatibility. Check the Usage
section below.
All other functions in this module have the same name and arity from
OpenTelemetry.Tracer
. Whenever possible, these functions will actually be
defdelegate
. When not possible, this means that some quality-of-life was
added before calling the corresponding OpenTelemetry.Tracer
function.
usage
Usage
When you use HatchTracing
it will include all required modules to start
using tracing, as well as importing the span/1
, span/2
and span/3
functions.
defmodule MyModule do
use HatchTracing
def my_function do
span do
# ... some code here
end
end
end
on-span-names
On Span Names
By default, if no name is specified, the generated span name will include the module, function name and function arity.
Hatch.Portal.UseCases.Xablau.call/1
When adding custom names, keep in mind the official guideline for span names.
The span name concisely identifies the work represented by the Span, for example, an RPC method name, a function name, or the name of a subtask or stage within a larger computation. The span name SHOULD be the most general string that identifies a (statistically) interesting class of Spans, rather than individual Span instances while still being human-readable. That is, “get_user” is a reasonable name, while “get_user/314159”, where “314159” is a user ID, is not a good name due to its high cardinality. Generality SHOULD be prioritized over human-readability, like “get_account/{accountId}”.
Link to this section Summary
Functions
Setup the target module to use tracing tools.
Add an event to the currently active Span.
Add a list of events to the currently active Span.
Generate a valid start_opts map to start a trace.
Returns the currently active OpenTelemetry.span_ctx/0
.
Returns the OpenTelemetry.span_ctx/0
active in Context ctx
.
End the currently active Span and sets its end timestamp. This has no effect on any child Spans that may exist of this Span.
Record an exception as an event, following the semantics convetions for exceptions.
Set an attribute with key and value on the currently active Span.
Add a list of attributes to the currently active Span.
Takes a OpenTelemetry.span_ctx/0
and the Tracer sets it to the currently
active Span.
Takes a OpenTelemetry.Ctx.t/0
and the OpenTelemetry.span_ctx/0
and the
Tracer sets it to the current span in the pass Context.
Creates and sets the Status of the currently active Span.
Creates and sets the Status of the currently active Span.
This is a custom and simpler version of with_span
.
Starts a new span and does not make it the current active span of the current process.
Starts a new span and does not make it the current active span of the current process.
Updates the Span name.
Creates a new span which is set to the currently active Span in the Context of
the block. The Span is ended automatically when the block
completes and the
Context is what it was before the block.
Link to this section Functions
Setup the target module to use tracing tools.
It will also import the span
function for a quickstart.
Add an event to the currently active Span.
An event is a human-readable message on a span that represents “something happening” during it’s lifetime. For example, imagine a function that requires exclusive access to a resource that is under a mutex. An event could be created at two points - once, when we try to gain access to the resource, and another when we acquire the mutex.
A useful characteristic of events is that their timestamps are displayed as offsets from the beginning of the span, allowing you to easily see how much time elapsed between them.
Events can also have attributes of their own.
Reference: https://opentelemetry.io/docs/reference/specification/trace/api/#add-events
@spec add_events([OpenTelemetry.event()]) :: boolean()
Add a list of events to the currently active Span.
See also add_event/2
.
Reference: https://opentelemetry.io/docs/reference/specification/trace/api/#add-events
Generate a valid start_opts map to start a trace.
When overriding, make sure that the value is correct, as this function does not perform any checks.
Accepted keys: :kind, :attributes, :links, :start_time, and :is_recording.
Returns the currently active OpenTelemetry.span_ctx/0
.
Returns the OpenTelemetry.span_ctx/0
active in Context ctx
.
@spec end_span(:opentelemetry.timestamp() | :undefined) :: :opentelemetry.span_ctx() | :undefined
End the currently active Span and sets its end timestamp. This has no effect on any child Spans that may exist of this Span.
To end a specific span, see OpenTelemetry.Span.end_span/1
.
The Span in the current Context has its is_recording
set to false
.
@spec record_exception(Exception.t(), any(), any()) :: boolean()
Record an exception as an event, following the semantics convetions for exceptions.
If trace is not provided, the stacktrace is retrieved from Process.info/2
Set an attribute with key and value on the currently active Span.
Attributes are keys and values that are applied as metadata to your spans and are useful for aggregating, filtering, and grouping traces. Attributes can be added at span creation, or at any other time during the lifecycle of a span before it has completed.
If the value is a set (map, list or tuple), its value is converted to a format that is supported by OpenTelemetryApi.
Reference: https://opentelemetry.io/docs/reference/specification/common/attribute-naming/
Add a list of attributes to the currently active Span.
The list of attributes can be a plain list, keyword lists, maps or tuples.
Reference: https://opentelemetry.io/docs/reference/specification/common/attribute-naming/
Takes a OpenTelemetry.span_ctx/0
and the Tracer sets it to the currently
active Span.
Takes a OpenTelemetry.Ctx.t/0
and the OpenTelemetry.span_ctx/0
and the
Tracer sets it to the current span in the pass Context.
@spec set_status(OpenTelemetry.status()) :: boolean()
Creates and sets the Status of the currently active Span.
If used, this will override the default Span Status, which is :unset
.
Reference: https://opentelemetry.io/docs/reference/specification/trace/api/#set-status
@spec set_status(OpenTelemetry.status_code(), String.t()) :: boolean()
Creates and sets the Status of the currently active Span.
If used, this will override the default Span Status, which is :unset
.
Reference: https://opentelemetry.io/docs/reference/specification/trace/api/#set-status
This is a custom and simpler version of with_span
.
The order of parameters is slightly different in order to favour automatic name generation.
- start_opts: a map with starting options. Check the
start_otps/1
function for more information - name: a string with the name of the span (default to nil). When nil, the name will be automatically generated based on the caller context (module + function)
Creates a new span which is set to the currently active Span in the Context of
the block. The Span is ended automatically when the block
completes and the
Context is what it was before the block.
If the name is nil
, a span name is automatically generated based on the
module and function that started the span, like
Hatch.Portal.UseCases.Xablau.call/1
.
Starts a new span and does not make it the current active span of the current process.
The current active Span is used as the parent of the created Span.
A Span represents a single operation within a trace. Spans can be nested to form a trace tree. Each trace contains a root span, which typically describes the entire operation and, optionally, one or more sub-spans for its sub-operations.
Referece: https://opentelemetry.io/docs/reference/specification/trace/api/#span
Starts a new span and does not make it the current active span of the current process.
The current active Span is used as the parent of the created Span.
A Span represents a single operation within a trace. Spans can be nested to form a trace tree. Each trace contains a root span, which typically describes the entire operation and, optionally, one or more sub-spans for its sub-operations.
Referece: https://opentelemetry.io/docs/reference/specification/trace/api/#span
Updates the Span name.
It is highly discouraged to update the name of a Span after its creation. Span name is often used to group, filter and identify the logical groups of spans. And often, filtering logic will be implemented before the Span creation for performance reasons. Thus the name update may interfere with this logic.
The function name is called UpdateName to differentiate this function from the regular property setter. It emphasizes that this operation signifies a major change for a Span and may lead to re-calculation of sampling or filtering decisions made previously depending on the implementation.
Creates a new span which is set to the currently active Span in the Context of
the block. The Span is ended automatically when the block
completes and the
Context is what it was before the block.
See start_span/2
and end_span/0
.