otel_tracer_provider -> otel_tracer -> otel_span -> otel_span_context
Not applicable.
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.)
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().
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.
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.
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().)
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.
span$add_event()Add a single event to the span.
name: Event name.
attributes: Attributes to add to the event. See as_attributes()
for supported R types. You may also use as_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.
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
the span$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.
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.
name: Attribute name.
value: Attribute value. See as_attributes() for supported R types.
You may also use as_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.
Other low level trace API:
get_default_tracer_provider(),
get_tracer(),
otel_span_context,
otel_tracer,
otel_tracer_provider,
tracer_provider_noop
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()