Learn R Programming

otel (version 0.3.0)

start_span: Start an OpenTelemetry span.

Description

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
)

Value

An OpenTelemetry span (otel_span).

Arguments

name

Name of the span. If not specified, and tracing is enabled, then otel uses the name of the calling function as the span name, and also sets the code.function.name attribute to the function name, unless it is already set. otel prefixes this attribute with the package name, if the function is in a package. If otel cannot find the name of the calling function, e.g. at the top level, or for anonymous functions, the span name 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.

links

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.

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

Run this code
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()

Run the code above in your browser using DataLab