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

Link to this macro

__using__(opts)

View Source (macro)

Setup the target module to use tracing tools.

It will also import the span function for a quickstart.

Link to this function

add_event(name, attributes \\ %{})

View Source
@spec add_event(atom() | binary(), list() | tuple() | map()) :: boolean()

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

Link to this function

build_span_opts(opts \\ [])

View Source
@spec build_span_opts(Keyword.t()) :: map()

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.

Link to this function

current_span_ctx(context)

View Source

Returns the OpenTelemetry.span_ctx/0 active in Context ctx.

Link to this function

end_span(timestamp \\ :undefined)

View Source
@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.

Link to this function

record_exception(exception, trace \\ nil, attributes \\ [])

View Source
@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

Link to this function

set_attribute(key, value)

View Source
@spec set_attribute(String.t(), any()) :: boolean()

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/

Link to this function

set_attributes(key, values)

View Source
@spec set_attributes(String.t(), any()) :: boolean()

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/

Link to this function

set_current_span(span_context)

View Source
@spec set_current_span(any()) :: any()

Takes a OpenTelemetry.span_ctx/0 and the Tracer sets it to the currently active Span.

Link to this function

set_current_span(context, span_context)

View Source
@spec set_current_span(any(), any()) :: any()

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

Link to this function

set_status(status, message)

View Source
@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

Link to this macro

span(start_opts \\ quote do %{} end, name \\ nil, list)

View Source (macro)

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.

Link to this macro

start_span(name, opts)

View Source (macro)

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

Link to this macro

start_span(ctx, name, opts)

View Source (macro)

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

@spec update_name(binary()) :: boolean()

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.

Link to this macro

valid_name(name)

View Source (macro)
Link to this macro

valid_opts(opts)

View Source (macro)
Link to this macro

with_span(name, start_opts \\ quote do %{} end, list)

View Source (macro)
Link to this macro

with_span(ctx, name, start_opts, list)

View Source (macro)

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.