View Source OpenTelemetry.Tracer (opentelemetry_api v1.1.1)

This module contains macros for Tracer operations around the lifecycle of the Spans within a Trace.

The Tracer is able to start a new Span as a child of the active Span of the current process, set a different Span to be the current Span by passing the Span's context, end a Span or run a code block within the context of a newly started span that is ended when the code block completes.

The macros start_span and with_span use the Tracer associated with the Application the module is included in. These Tracers are created at boot time for each loaded Application.

require OpenTelemetry.Tracer, as: Tracer

Tracer.with_span "span-1" do
  ... do something ...
end

Link to this section Summary

Functions

Add an event to the currently active Span.

Add a list of events to the currently active Span.

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.

Sets the Status of the currently active Span.

Creates and sets the Status of the currently active 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.

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 function

add_event(event, attributes)

View Source

Add an event to the currently active Span.

@spec add_events([OpenTelemetry.event()]) :: boolean()

Add a list of events to the currently active Span.

Returns the currently active OpenTelemetry.span_ctx/0.

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

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

Set an attribute with key and value on the currently active Span.

Link to this function

set_attributes(attributes)

View Source
@spec set_attributes(OpenTelemetry.attributes_map()) :: boolean()

Add a list of attributes to the currently active Span.

Link to this function

set_current_span(span_ctx)

View Source

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

Link to this function

set_current_span(ctx, span_ctx)

View Source

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()

Sets the Status of the currently active Span.

If used, this will override the default Span Status, which is :unset.

Link to this function

set_status(code, 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.

Link to this macro

start_span(name, opts \\ quote do %{} end)

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.

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.

@spec update_name(String.t()) :: 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

with_span(name, start_opts \\ quote do %{} end, 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.

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.