Skip to content

Start an OpenTelemetry span.

Source: R/api.R
start_span.Rd

Creates a new OpenTelemetry span and starts it, without activating it.

Usually you want start_local_active_span() instead of start_span. start_local_active_span() also activates the span for the caller frame, and ends the span when the caller frame exits.

Usage

start_span(
  name = NULL,
  attributes = NULL,
  links = NULL,
  options = NULL,
  ...,
  tracer = NULL
)

Arguments

name

Name of the span. If not specified it will be "<NA>".

attributes

Span attributes. OpenTelemetry supports the following R types as attributes: `character, logical, double, integer. You may use as_attributes() to convert other R types to OpenTelemetry attributes.

A named list of links to other spans. Every link must be an OpenTelemetry span (otel_span) object, or a list with a span object as the first element and named span attributes as the rest.

options

A named list of span options. May include:

  • start_system_time: Start time in system time.

  • start_steady_time: Start time using a steady clock.

  • parent: A parent span or span context. If it is NA, then the span has no parent and it will be a root span. If it is NULL, then the current context is used, i.e. the active span, if any.

  • kind: Span kind, one of span_kinds: "internal", "server", "client", "producer", "consumer".

...

Additional arguments are passed to the start_span() method of the tracer.

tracer

A tracer object or the name of the tracer to use, see get_tracer(). If NULL then default_tracer_name() is used.

Value

An OpenTelemetry span (otel_span).

Details

Only use start_span() is you need to manage the span's activation manually. Otherwise use start_local_active_span().

You must end the span by calling end_span(). Alternatively you can also end it with local_active_span() or with_active_span() by setting end_on_exit = TRUE.

It is a good idea to end spans created with start_span() in an base::on.exit() call.

See also

Other OpenTelemetry trace API: Zero Code Instrumentation, end_span(), is_tracing_enabled(), local_active_span(), start_local_active_span(), tracing-constants, with_active_span()

Examples

fun <- function() {
  # start span, do not activate
  spn <- otel::start_span("myfun")
  # do not leak resources
  on.exit(otel::end_span(spn), add = TRUE)
  myfun <- function() {
     # activate span for this function
     otel::local_active_span(spn)
     # create child span
     spn2 <- otel::start_local_active_span("myfun/2")
  }

  myfun2 <- function() {
    # activate span for this function
    otel::local_active_span(spn)
    # create child span
    spn3 <- otel::start_local_active_span("myfun/3")
  }
  myfun()
  myfun2()
  end_span(spn)
}
fun()