OpenTelemetry.Span (OpenTelemetry API v1.5.0)
View SourceThis module contains macros for Span operations that update the active current Span in the current process. An example of creating an Event and adding it to the current Span:
require OpenTelemetry.Tracer, as: Tracer
require OpenTelemetry.Span, as: Span
span_ctx = Tracer.start_span("some-span")
...
Span.add_event(span_ctx, "ecto.query", query: query, total_time: total_time)
...
Span.end_span(span_ctx)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 end-to-end latency and, optionally, one or more sub-spans for its sub-operations.
Spans encapsulate:
- The span name
- An immutable SpanContext (
OpenTelemetry.span_ctx/0) that uniquely identifies the Span - A parent Span in the form of a Span (
OpenTelemetry.span/0), SpanContext (OpenTelemetry.span_ctx/0), orundefined - A start timestamp
- An end timestamp
- An ordered mapping of Attributes (
OpenTelemetry.attributes_map/0) - A list of Links to other Spans (
OpenTelemetry.link/0) - A list of timestamped Events (
OpenTelemetry.event/0) - A Status (
OpenTelemetry.status/0)
See specification
Summary
Functions
Add an event to the currently active Span.
Add a list of events to the currently active Span.
End the Span. Sets the end timestamp for the currently active Span. This has no effect on any child Spans that may exist of this Span.
End the Span. Sets the end timestamp for the currently active Span using the passed in timestamp if valid, current timestamp otherwise. This has no effect on any child Spans that may exist of this Span.
Get the hex-encoded trace context.
Get the lowercase hex encoded span ID.
Get the lowercase hex encoded trace ID.
Returns whether this Span is recording information like events, attributes, status, etc.
Returns true if the SpanContext has a non-zero TraceId and SpanId.
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.
Sets the Status of the currently active Span.
Get the SpanId of a Span.
Get the TraceId of a Span.
Get the Tracestate of a Span.
Updates the Span name.
Types
@type start_config() :: :otel_span.start_config()
@type start_opts() :: :otel_span.start_opts()
Functions
@spec add_event( OpenTelemetry.span_ctx(), OpenTelemetry.event_name(), OpenTelemetry.attributes_map() ) :: boolean()
Add an event to the currently active Span.
See specification
@spec add_events(OpenTelemetry.span_ctx(), [OpenTelemetry.event()]) :: boolean()
Add a list of events to the currently active Span.
See specification
End the Span. Sets the end timestamp for the currently active Span. This has no effect on any child Spans that may exist of this Span.
The Span Context is returned with is_recording set to false.
See specification
End the Span. Sets the end timestamp for the currently active Span using the passed in timestamp if valid, current timestamp otherwise. This has no effect on any child Spans that may exist of this Span.
The Span Context is returned with is_recording set to false.
See specification
@spec hex_span_ctx(OpenTelemetry.span_ctx() | nil) :: %{ otel_trace_id: OpenTelemetry.hex_trace_id(), otel_span_id: OpenTelemetry.hex_span_id(), otel_trace_flags: binary() } | %{}
Get the hex-encoded trace context.
@spec hex_span_id(OpenTelemetry.span_ctx()) :: OpenTelemetry.hex_span_id()
Get the lowercase hex encoded span ID.
@spec hex_trace_id(OpenTelemetry.span_ctx()) :: OpenTelemetry.hex_trace_id()
Get the lowercase hex encoded trace ID.
Returns whether this Span is recording information like events, attributes, status, etc.
See specification
Returns true if the SpanContext has a non-zero TraceId and SpanId.
See specification
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
See specification
@spec set_attribute( OpenTelemetry.span_ctx(), OpenTelemetry.attribute_key(), OpenTelemetry.attribute_value() ) :: boolean()
Set an attribute with key and value on the currently active Span.
See specification
@spec set_attributes(OpenTelemetry.span_ctx(), OpenTelemetry.attributes_map()) :: boolean()
Add a list of attributes to the currently active Span.
See specification
@spec set_status(OpenTelemetry.span_ctx(), OpenTelemetry.status()) :: boolean()
Sets the Status of the currently active Span.
If used, this will override the default Span Status, which is :unset.
Valid statuses are :ok, or :error. Calling this will also set the
status_code attribute to 1(:ok), or 2(:error).
See specification
@spec span_id(OpenTelemetry.span_ctx()) :: OpenTelemetry.span_id()
Get the SpanId of a Span.
@spec trace_id(OpenTelemetry.span_ctx()) :: OpenTelemetry.trace_id()
Get the TraceId of a Span.
@spec tracestate(OpenTelemetry.span_ctx()) :: OpenTelemetry.tracestate()
Get the Tracestate of a Span.
@spec update_name(OpenTelemetry.span_ctx(), OpenTelemetry.span_name()) :: 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 update_name 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.
See specification