otel_tracer_provider -> otel_tracer -> otel_span -> otel_span_context
Details
An otel_span object represents an OpenTelemetry span.
Use start_local_active_span() or start_span() to create and start
a span.
Call end_span() to end a span explicitly. (See
start_local_active_span() and local_active_span() to end a span
automatically.)
Lifetime
The span starts when it is created in the start_local_active_span()
or start_span() call.
The span ends when end_span() is called on it, explicitly or
automatically via start_local_active_span() or local_active_span().
Activation
After a span is created it may be active or inactively, independently of its lifetime. A live span (i.e. a span that hasn't ended yet) may be inactive. While this is less common, a span that has ended may still be active.
When otel creates a new span, it sets the parent span of the new span to the active span by default.
Automatic spans
start_local_active_span() creates a new span, starts it and activates
it for the caller frame. It also automatically ends the span when the
caller frame exits.
Manual spans
start_span() creates a new span and starts it, but it does not
activate it. You must activate the span manually using
local_active_span() or with_active_span(). You must also end the
span manually with an end_span() call. (Or the end_on_exit argument
of local_active_span() or with_active_span().)
Parent spans
OpenTelemetry spans form a hierarchy: a span can refer to a parent span. A span without a parent span is called a root span. A trace is a set of connected spans.
When otel creates a new span, it sets the parent span of the new span to the active span by default.
Alternatively, you can set the parent span of the new span manually.
You can also make the new span be a root span, by setting parent = NA
in options to the start_local_active_span() or start_span() call.
Methods
span$add_event()
Add a single event to the span.
Arguments
name: Event name.attributes: Attributes to add to the event. Seeas_attributes()for supported R types. You may also useas_attributes()to convert an R object to an OpenTelemetry attribute value.timestamp: A base::POSIXct object. If missing, the current time is used.
span$end()
End the span. Calling this method is equivalent to calling the
end_span() function on the span.
Spans created with start_local_active_span() end automatically by
default. You must end every other span manually, by calling end_span,
or using the end_on_exit argument of local_active_span() or
with_active_span().
Calling the span$end() method (or end_span()) on a span multiple
times is not an error, the first call ends the span, subsequent calls do
nothing.
Arguments
options: Named list of options. Possible entry:end_steady_time: A base::POSIXct object that will be used as a steady timer.
status_code: Span status code to set before ending the span, see thespan$set_status()method for possible values.
span$get_context()
Get a span's span context. The span context is an otel_span_context object that can be serialized, copied to other processes, and it can be used to create new child spans.
Value
An otel_span_context object.
span$is_recording()
Checks whether a span is recorded. If tracing is off, or the span ended already, or the sampler decided not to record the trace the span belongs to.
span$record_exception()
Record an exception (error, usually) event for a span.
If the span was created with start_local_active_span(), or it was
ended automatically with local_active_span() or with_active_span(),
then otel records exceptions automatically, and you don't need to call
this function manually.
You can still use it to record exceptions that are not R errors.
span$set_attribute()
Set a single attribute. It is better to set attributes at span creation, instead of calling this method later, since samplers can only make decisions based on attributes present at span creation.
Arguments
name: Attribute name.value: Attribute value. Seeas_attributes()for supported R types. You may also useas_attributes()to convert an R object to an OpenTelemetry attribute value.
span$set_status()
Set the status of the span.
If the span was created with start_local_active_span(), or it was
ended automatically with local_active_span() or with_active_span(),
then otel sets the status of the span automatically to ok or error,
depending on whether an error happened in the frame the span was
activated for.
Otherwise the default span status is unset, and you need to set it
manually.
span$update_name()
Update the span's name. Overrides the name give in
start_local_active_span() or start_span().
It is undefined whether a sampler will use the original or the new name.
See also
Other low level trace API:
get_default_tracer_provider(),
get_tracer(),
otel_span_context,
otel_tracer,
otel_tracer_provider,
tracer_provider_noop
Examples
fn <- function() {
trc <- otel::get_tracer("myapp")
spn <- trc$start_span("fn")
# ...
spn$set_attribute("key", "value")
# ...
on.exit(spn$end(status_code = "error"), add = TRUE)
# ...
spn$end(status_code = "ok")
}
fn()