Spandex v3.0.1 Spandex View Source

The functions here call the corresponding functions on the configured adapter.

Link to this section Summary

Types

Used for Span and Trace IDs (type defined by adapters)

Unix timestamp in nanoseconds

Functions

Given a %SpanContext{}, resumes a trace from a different process or service

Given a trace_id and span_id, resumes a trace from a different process or service

Given a span struct, resumes a trace from a different process or service

Returns the current %SpanContext{} or an error

Returns the %Span{} struct for the currently-running span

Returns the id of the currently-running span

Returns the id of the currently-running trace

Returns the context from a given set of HTTP headers, as determined by the adapter

Finishes the current span

Finishes the current trace

Alters headers to include the outgoing HTTP headers necessary to continue a distributed trace, as determined by the adapter

Updates the current span with error details

Start a new span

Starts a new trace

Updates all spans, whether complete or in-progress

Updates the current span

Updates the top-most parent span

Link to this section Types

Link to this type headers() View Source
headers() ::
  [{atom(), binary()}]
  | [{binary(), binary()}]
  | %{required(binary()) => binary()}

Used for Span and Trace IDs (type defined by adapters)

Unix timestamp in nanoseconds

Link to this section Functions

Link to this function continue_trace(name, span_context, opts) View Source
continue_trace(String.t(), Spandex.SpanContext.t(), Keyword.t()) ::
  {:ok, Spandex.Trace.t()}
  | {:error, :disabled}
  | {:error, :trace_already_present}

Given a %SpanContext{}, resumes a trace from a different process or service.

Span updates for the top span may be passed in. They are skipped if they are invalid updates. As such, if you aren’t sure if your updates are valid, it is safer to perform a second call to update_span/2 and check the return value.

Link to this function continue_trace(name, trace_id, span_id, opts) View Source
continue_trace(String.t(), id(), id(), Keyword.t()) ::
  {:ok, Spandex.Trace.t()}
  | {:error, :disabled}
  | {:error, :trace_already_present}
This function is deprecated. Use continue_trace/3 instead.

Given a trace_id and span_id, resumes a trace from a different process or service.

Span updates for the top span may be passed in. They are skipped if they are invalid updates. As such, if you aren’t sure if your updates are valid, it is safer to perform a second call to update_span/2 and check the return value.

Link to this function continue_trace_from_span(name, span, opts) View Source
continue_trace_from_span(String.t(), Spandex.Span.t(), Spandex.Tracer.opts()) ::
  {:ok, Spandex.Trace.t()}
  | {:error, :disabled}
  | {:error, :trace_already_present}

Given a span struct, resumes a trace from a different process or service.

Span updates for the top span may be passed in. They are skipped if they are invalid updates. As such, if you aren’t sure if your updates are valid, it is safer to perform a second call to update_span/2 and check the return value.

Link to this function current_context(opts) View Source
current_context(Spandex.Tracer.opts()) ::
  {:ok, Spandex.SpanContext.t()}
  | {:error, :disabled}
  | {:error, :no_span_context}
  | {:error, :no_trace_context}

Returns the current %SpanContext{} or an error.

DEPRECATION WARNING

Expect changes to this in the future, as this will eventualy be refactored to only ever return a %SpanContext{}, or at least to always return something consistent.

Link to this function current_span(opts) View Source
current_span(Spandex.Tracer.opts()) :: Spandex.Span.t() | nil

Returns the %Span{} struct for the currently-running span

Link to this function current_span_id(opts) View Source
current_span_id(Spandex.Tracer.opts()) :: id() | nil

Returns the id of the currently-running span.

Link to this function current_trace_id(opts) View Source
current_trace_id(Spandex.Tracer.opts()) :: id() | nil

Returns the id of the currently-running trace.

Link to this function distributed_context(metadata, opts) View Source
distributed_context(Plug.Conn.t(), Spandex.Tracer.opts()) ::
  {:ok, Spandex.SpanContext.t()} | {:error, :disabled}
distributed_context(headers(), Spandex.Tracer.opts()) ::
  {:ok, Spandex.SpanContext.t()} | {:error, :disabled}

Returns the context from a given set of HTTP headers, as determined by the adapter.

Link to this function finish_span(opts) View Source
finish_span(Spandex.Tracer.opts()) ::
  {:ok, Spandex.Span.t()}
  | {:error, :disabled}
  | {:error, :no_trace_context}
  | {:error, :no_span_context}

Finishes the current span.

Span updates for that span may be passed in. They are skipped if they are invalid updates. As such, if you aren’t sure if your updates are valid, it is safer to perform a call to update_span/2 and check the return value before finishing the span.

Link to this function finish_trace(opts) View Source
finish_trace(Spandex.Tracer.opts()) ::
  {:ok, Spandex.Trace.t()} | {:error, :disabled} | {:error, :no_trace_context}

Finishes the current trace.

Span updates for the top span may be passed in. They are skipped if they are invalid updates. As such, if you aren’t sure if your updates are valid, it is safer to perform a call to update_span/2 and check the return value before finishing the trace.

Link to this function inject_context(headers, span_context, opts) View Source

Alters headers to include the outgoing HTTP headers necessary to continue a distributed trace, as determined by the adapter.

Link to this function span_error(exception, stacktrace, opts) View Source
span_error(Exception.t(), Enum.t(), Spandex.Tracer.opts()) ::
  {:ok, Spandex.Span.t()}
  | {:error, :disabled}
  | {:error, :no_trace_context}
  | {:error, :no_span_context}
  | {:error, [Optimal.error()]}

Updates the current span with error details.

In the case of an invalid value, validation errors are returned.

Link to this function start_span(name, opts) View Source
start_span(String.t(), Spandex.Tracer.opts()) ::
  {:ok, Spandex.Span.t()} | {:error, :disabled} | {:error, :no_trace_context}

Start a new span.

Span updates for that span may be passed in. They are skipped if they are invalid updates. As such, if you aren’t sure if your updates are valid, it is safer to perform a second call to update_span/2 and check the return value.

Link to this function start_trace(name, opts) View Source
start_trace(binary(), Spandex.Tracer.opts()) ::
  {:ok, Spandex.Trace.t()}
  | {:error, :disabled}
  | {:error, :trace_running}
  | {:error, [Optimal.error()]}

Starts a new trace.

Span updates for the first span may be passed in. They are skipped if they are invalid updates. As such, if you aren’t sure if your updates are valid, it is safer to perform a second call to update_span/2 and check the return value.

Link to this function update_all_spans(opts) View Source
update_all_spans(Spandex.Tracer.opts()) ::
  {:ok, Spandex.Trace.t()}
  | {:error, :disabled}
  | {:error, :no_trace_context}
  | {:error, [Optimal.error()]}

Updates all spans, whether complete or in-progress.

In the case of an invalid update for any span, validation errors are returned.

Link to this function update_span(opts, top? \\ false) View Source
update_span(Spandex.Tracer.opts(), boolean()) ::
  {:ok, Spandex.Span.t()}
  | {:error, :disabled}
  | {:error, :no_trace_context}
  | {:error, :no_span_context}
  | {:error, [Optimal.error()]}

Updates the current span.

In the case of an invalid update, validation errors are returned.

Link to this function update_top_span(opts) View Source
update_top_span(Spandex.Tracer.opts()) ::
  {:ok, Spandex.Span.t()}
  | {:error, :disabled}
  | {:error, :no_trace_context}
  | {:error, [Optimal.error()]}

Updates the top-most parent span.

Any spans that have already been started will not inherit any of the updates from that span. For instance, if you change service, it will not be reflected in already-started spans.

In the case of an invalid update, validation errors are returned.