Title: | 'OpenTelemetry' 'R' 'API' |
Version: | 0.1.0 |
Description: | 'OpenTelemetry' is a collection of tools, 'APIs', and 'SDKs' used to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior. This package implements the 'OpenTelemetry' 'API': https://opentelemetry.io/docs/specs/otel/ Use this package as a dependency if you want to instrument your R package for 'OpenTelemetry'. |
License: | MIT + file LICENSE |
Encoding: | UTF-8 |
RoxygenNote: | 7.3.2.9000 |
Depends: | R (≥ 3.6.0) |
Suggests: | callr, cli, glue, otelsdk, processx, shiny, spelling, testthat (≥ 3.0.0), utils, withr |
Config/Needs/website: | tidyverse/tidytemplate |
Config/testthat/edition: | 3 |
URL: | https://otel.r-lib.org, https://github.com/r-lib/otel |
Additional_repositories: | https://github.com/r-lib/otelsdk/releases/download/devel |
NeedsCompilation: | no |
Packaged: | 2025-07-28 22:10:33 UTC; gaborcsardi |
Author: | Gábor Csárdi [aut, cre] |
Maintainer: | Gábor Csárdi <csardi.gabor@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2025-07-31 10:00:24 UTC |
Environment variables to configure otel
Description
This manual page contains the environment variables you can use to configure the otel package. Start with the 'Selecting exporters' section below if you want to produce telemetry data for an instrumented R package.
See also the Environment Variables in the otelsdk package, which is charge of the data collection configuration.
Details
You need set these environment variables when configuring the collection of telemetry data, unless noted otherwise.
Production or Development Environment
OTEL_ENV
By default otel runs in production mode. In production mode otel functions never error. Errors in the telemetry code will not stop the monitored application.
This behavior is not ideal for development, where one would prefer to catch errors early. Set
OTEL_ENV=dev
to run otel in development mode, where otel functions fail on error, make it easier to fix errors.
Selecting Exporters
otel is responsible for selecting the providers to use for traces, logs and metrics. You can use the environment variables below to point the otel functions to the desired providers.
If none of these environment variables are set, then otel will not emit any telemetry data.
See the otelsdk package for configuring the selected providers.
OTEL_TRACES_EXPORTER
The name of the selected tracer provider. See
get_default_tracer_provider()
for the possible values.
OTEL_R_TRACES_EXPORTER
R specific version of OTEL_TRACES_EXPORTER
.
OTEL_LOGS_EXPORTER
The name of the selected logger provider. See
get_default_logger_provider()
for the possible values.
OTEL_R_LOGS_EXPORTER
R specific version of OTEL_LOGS_EXPORTER
.
OTEL_METRICS_EXPORTER
The name of the selected meter provider. See
get_default_meter_provider()
for the possible values.
OTEL_R_METRICS_EXPORTER
R specific version of OTEL_METRICS_EXPORTER
.
Suppressing Instrumentation Scopes (R Packages)
otel has two environment variables to fine tune which instrumentation scopes (i.e. R packages, typically) emit telemetry data. By default, i.e. if neither of these are set, all packages emit telemetry data.
OTEL_R_EMIT_SCOPES
Set this environment variable to a comma separated string of
instrumentation scope names or R package names to restrict telemetry to
these packages only. The name of the instrumentation scope is the same
as the name of the tracer, logger or meter, see default_tracer_name()
.
You can mix package names and instrumentation scope names and you can also use wildcards (globbing). For example the value
OTEL_R_EMIT_SCOPES="org.r-lib.*,dplyr"
selects all packages with an instrumentation scope that starts with
org.r-lib.
and also dplyr.
OTEL_R_SUPPRESS_SCOPES
Set this environment variable to a comma separated string of
instrumentation scope names or R package names to suppress telemetry
data from these packages. The name of the instrumentation scope is the same
as the name of the tracer, logger or meter, see default_tracer_name()
.
You can mix package names and instrumentation scope names and you can also use wildcards (globbing). For example the value
OTEL_R_SUPPRESS_SCOPES="org.r-lib.*,dplyr"
excludes packages with an instrumentation scope that starts with
org.r-lib.
and also dplyr.
Zero Code Instrumentation
otel can instrument R packages for OpenTelemetry data collection
without changing their source code. This relies on changing the code
of the R functions manually using base::trace()
and can be configured
using environment variables.
OTEL_R_INSTRUMENT_PKGS
Set OTEL_R_INSTRUMENT_PKGS
to a comma separated list of packages to
instrument. The automatic instrumentation happens when the otel package
is loaded, so in general it is best to set this environment variable
before loading R.
OTEL_R_INSTRUMENT_PKGS_<pkg>_INCLUDE
For an automatically instrumented package, set this environment variable
to only instrument a subset of its functions. It is parsed as a comma
separated string of function names, which may also include ?
and *
wildcards (globbing).
OTEL_R_INSTRUMENT_PKGS_<pkg>_EXCLUDE
For an automatically instrumented package, set this environment variable
to exclude some functions from instrumentation. It has the same syntax
as its *_INCLUDE
pair. If both are set, then inclusion is applied
and the exclusion.
Others
OTEL_ATTRIBUTE_COUNT_LIMIT
Set this environment variable to limit the number of attributes for a single span, log record, metric measurement, etc. If unset, the default limit is 128 attributes.
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT
Set this environment variable to limit the length of vectors in attributes for a single span, log record, metric measurement, etc. If unset, there is no limit on the lengths of vectors in attributes.
Value
Not applicable.
See Also
Environment Variables in otelsdk
Examples
# To start an R session using the OTLP exporter:
# OTEL_TRACES_EXPORTER=http R -q -f script.R
Getting Started
Description
This page is about instrumenting you R package or project for OpenTelemetry. If you want to start collecting OpenTelemetry data for instrumented packages, see Collecting Telemetry Data in the otelsdk package.
About OpenTelemetry
OpenTelemetry is an observability framework. OpenTelemetry is a collection of tools, APIs, and SDKs used to instrument, generate, collect, and export telemetry data such as metrics, logs, and traces, for analysis in order to understand your software’s performance and behavior.
For an introduction to OpenTelemetry, see the OpenTelemetry website docs.
The otel and otelsdk R packages
Use the otel package as a dependency if you want to instrument your R package or project for OpenTelemetry.
Use the otelsdk package to produce OpenTelemetry output from an R package or project that was instrumented with the otel package.
Complete Example
To instrument your package with otel, you need to do a couple of steps. In this section we show how to instrument the callr package.
Add the otel package as a dependency
The first step is to add the otel package as a dependency. otel is a very
lightweight package, so may want to add it as a hard dependency. This has
the advantage that you don't need to check if otel is installed every time
you call an otel function. Add otel to the Imports
section in
DESCRIPTION
:
Imports: otel
Alternatively, you may add otel as a soft dependency. Add otel to the
Suggests
section in DESCRIPTION
:
Suggests: otel
If you add otel in Suggests
, then it makes sense to create a helper
function that checks if otel is installed and also that tracing is enabled
for the caller. You can put this function in any R file, e.g. R/utils.R
is a nice place for it:
is_otel_tracing <- function() { requireNamespace("otel", quietly = TRUE) && otel::is_tracing_enabled() }
Choose a tracer name
Every package should have its own tracer with a name that is unique for the
package. See default_tracer_name()
for tips on choosing a good tracer
name. Set the otel_tracer_name
variable to the tracer name. No need to
export this symbol. In callr, we'll add
otel_tracer_name <- "org.r-lib.callr"
to the R/callr-package.R
file.
Create spans for selected functions
Select the functions you want to add tracing to. It is overkill to add tracing to small functions that are called lots of times. It makes sense to add spans to the main functions of the package.
The callr package has various ways of starting another R process and then running R code in it. We'll add tracing to the
-
callr::r()
-
callr::rcmd()
-
callr::rscript()
functions first.
We add to callr::r()
in eval.R
:
if (is_otel_tracing()) { otel::start_local_active_span( "callr::r", attributes = otel::as_attributes(options) ) }
We use the
is_otel_tracing()
helper function, defined above.-
start_local_active_span()
starts a span and also activates it. It also sets up an exit handler that ends the span when the caller function (callr::r()
) exits. -
options
contain a long list of user-provided and other option, we add these to the span as attributes.
We add essentially the same code to callr::rcmd()
:
if (is_otel_tracing()) { otel::start_local_active_span( "callr::rcmd", attributes = otel::as_attributes(options) ) }
And to callr::rscript()
:
if (is_otel_tracing()) { otel::start_local_active_span( "callr::rscript", attributes = otel::as_attributes(options) ) }
Concurrency
An instance of the callr::r_session
R6 class represents persistent
R background processes. We want to collect all spans from an R process into
the same trace. Since the R processes are running concurrently, their
(sub)spans will not form the correct hierarchy if we use the default,
timing-based otel mechanism to organize spans into trees. We need to
manage the lifetime and activation of the spans that represent the R
processes manually.
A generic strategy for handling concurrency in otel is:
Create a new long lasting span with
start_span()
. (I.e. notstart_local_active_span()
!)Assign the returned span into the corresponding object of the concurrent and/or asynchronous computation. Every span has a finalizer that closes the span.
When running code that belongs to the concurrent computation represented by the span, activate it for a specific R scope by calling
with_active_span()
orlocal_active_span()
.When the concurrent computation ends, close the span manually with its
$end()
method orend_span()
. (Otherwise it would be only closed at the next garbage collection, assuming there are no references to it.)
This code goes into the constructor of the r_session
object:
if (is_otel_tracing()) { private$options$otel_session <- otel::start_span( "callr::r_session", attributes = otel::as_attributes(options) ) }
The finalize()
method (the finalizer) gets a call to close the span:
if (is_otel_tracing()) { private$options$otel_session$end() }
We also add (sub)spans to other operations, e.g. the read()
method gets
if (is_otel_tracing()) { otel::local_session(private$options$otel_session) spn <- otel::start_local_active_span("callr::r_session$read") }
Testing
To test your instrumentation, you need to install the otelsdk package and you also need a local or remote OpenTelemetry collector.
I suggest you use otel-tui
,
a terminal OpenTelemetry viewer. To configure it, use the http
exporter,
see Environment Variables:
OTEL_TRACES_EXPORTER=http R -q
Development mode
By default otel functions never error, to avoid taking down a production app. For development this is not ideal, we want to catch errors early. I suggest you always turn on development mode when instrumenting a package:
OTEL_ENV=dev
Context propagation
OpenTelemetry supports distributed tracing. A span (context) can be serialized, copied to another process, and there it can be used to create child spans.
For applications communicating via HTTP the serialized span context is transmitted in HTTP headers. For our callr example we can copy the context to the R subprocess in environment variables.
For example in the callr:r()
code we may write:
if (is_otel_tracing()) { otel::start_local_active_span( "callr::r", attributes = otel::as_attributes(options) ) hdrs <- otel::pack_http_context() names(hdrs) <- toupper(names(hdrs)) options$env[names(hdrs)] <- hdrs }
options$env
contains the environment variables callr will set in the
newly started R process. This is where we need to add the output of
pack_http_context()
, which contains the serialized representation
of the active span, if there is any.
Additionally, the subprocess needs to pick up the span context from the
environment variables. The callr:::common_hook()
internal function
contains the code that the subprocess runs at startup. Here we need to
add:
has_otel <- nzchar(Sys.getenv("TRACEPARENT")) && requireNamespace("otel", quietly = TRUE) assign(envir = env$`__callr_data__`, "has_otel", has_otel) if (has_otel) { hdrs <- as.list(c( traceparent = Sys.getenv("TRACEPARENT"), tracestate = Sys.getenv("TRACESTATE"), baggage = Sys.getenv("BAGGAGE") )) prtctx <- otel::extract_http_context(hdrs) reg.finalizer( env$`__callr_data__`, function(e) e$otel_span$end(), onexit = TRUE ) assign( envir = env$`__callr_data__`, "otel_span", otel::start_span( "callr subprocess", options = list(parent = prtctx) ) ) }
First we check if the TRACEPARENT
environment variable is set. This
contains the serialization of the parent span. If it exists and the otel
package is also available, then we extract the span context from the
environment variables, and start a new span that is a child span or the
remote span obtained from the environment variables. We also set up a
finalizer that closes this span when the R process terminates.
Examples
# See above
Zero Code Instrumentation
Description
otel supports zero-code instrumentation (ZCI) via the
OTEL_INSTRUMENT_R_PKGS
environment variable. Set this to a comma
separated list of package names, the packages that you want to
instrument. Then otel will hook up base::trace()
to produce
OpenTelemetry output from every function of these packages.
Details
By default all functions of the listed packages are instrumented. To
instrument a subset of all functions set the
OTEL_INSTRUMENT_R_PKGS_<PKG>_INCLUDE
environment variable to a list of
glob expressions. <PKG>
is the package name in all capital letters.
Only functions that match to at least one glob expression will be
instrumented.
To exclude functions from instrumentation, set the
OTEL_INSTRUMENT_R_PKGS_<PKG>_EXCLUDE
environment variable to a list of
glob expressions. <PKG>
is the package name in all capital letters.
Functions that match to at least one glob expression will not be
instrumented. Inclusion globs are applied before exclusion globs.
Caveats
If the user calls base::trace()
on an instrumented function, that
deletes the instrumentation, since the second base::trace()
call
overwrites the first.
Value
Not applicable.
See Also
Other OpenTelemetry trace API:
end_span()
,
is_tracing_enabled()
,
local_active_span()
,
start_local_active_span()
,
start_span()
,
tracing-constants
,
with_active_span()
Examples
# To run an R script with ZCI:
# OTEL_TRACES_EXPORTER=http OTEL_INSTRUMENT_R_PKGS=dplyr,tidyr R -q -f script.R
R objects as OpenTelemetry attributes
Description
Convert a list of R objects to a form that is suitable as OpenTelemetry attributes.
Usage
as_attributes(x)
Arguments
x |
A list of R objects, to be used as OpenTelemetry attributes. |
Value
A named list that can be used as the attributes
argument to
the start_span()
method of otel_tracer, the log()
method of
otel_logger, etc.
If x
is not named, or some names are the empty string or NA
, then
integer numbers as used for the missing or invalid names.
If some elements in x
are not of the natively supported R types in
OpenTelemetry (character, logical, double, integer), then
their printed form is captured using utils::capture.output()
.
Limits
The number of attributes can be limited with the OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT environment variable. The default is 128.
The length of the each attribute (vector) can be limited with the
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT environment variable. The default is
Inf
. Note that this is applied to
the length of each attribute as an R vector. E.g. it does not
currently limit the number of characters in individual strings.
Examples
as_attributes(list(
number = 1.0,
vector = 1:10,
string = "otel",
string_vector = letters,
object = mtcars
))
Increase an OpenTelemetry counter
Description
Increase an OpenTelemetry counter
Usage
counter_add(name, value = 1L, attributes = NULL, context = NULL, meter = NULL)
Arguments
name |
Name of the counter. |
value |
Value to add to the counter, defaults to 1. |
attributes |
Additional attributes to add. |
context |
Span context. If missing the active context is used, if any. |
meter |
Meter object (otel_meter). Otherwise it is passed to
|
Value
The counter object (otel_counter), invisibly.
See Also
Other OpenTelemetry metrics instruments:
gauge_record()
,
histogram_record()
,
up_down_counter_add()
Other OpenTelemetry metrics API:
gauge_record()
,
histogram_record()
,
is_measuring_enabled()
,
up_down_counter_add()
Examples
otel::counter_add("total-session-count", 1)
Default tracer name (and meter and logger name) for an R package
Description
Exporters, like the ones in the otelsdk package, can use this function to determine the default tracer name, if the instrumentation author hasn't specified one. If you are an instrumentation author, you probably do not need to call this function directly, but do read on to learn about choosing and setting the tracer name.
Usage
default_tracer_name(name = NULL)
Arguments
name |
Custom tracer name. If |
Details
About tracer names
The name of a tracer identifies an OpenTelemetry instrumentation scope. Instrumentation scopes can be used to organize the collected telemetry data. otel can also use instrumentation scopes to suppress emitting unneeded telemetry data, see 'Environment Variables'.
For the otel R package it makes sense to create a separate instrumentation scope for each R package that emits telemetry data. otel can do this automatically, with some from the package author.
Setting the tracer name
As a package author, you can define the otel_tracer_name
symbol in
your package and set it do the desired tracer name. For example, the
callr package has this in an .R
file:
otel_tracer_name <- "org.r-lib.callr"
See below for tips on choosing a tracer name.
If you don't like the default tracer name, you can call get_tracer()
(or get_logger()
or get_meter()
manually with the desired name.
Automatic tracer name detection in otel
This is the detailed algorithm that otel uses in default_tracer_name
:
Using
base::topenv()
it finds the calling package (or other top level environment), recursively.It ignores the otel and otelsdk packages while searching.
If it finds the base environment or the global environment, then it returns
org.project.R
as the tracer name.Otherwise it looks for the
otel_tracer_name
symbol inside the top level environment it has found. If this symbol exists then it must be a string scalar and otel will use it as the tracer name.If this symbol does not exist, then otel will use
r.package.<environment-name>
as the tracer name.<environment-name>
is usually the package name.
Choosing a tracer name
The OpenTelemetry specification recommends using a tracer name that identifies the instrumentation scope, i.e. your package.
Some tips on choosing the tracer name:
If your R package can be associated with a URL, you can use the "reverse" of that URL. E.g. since the callr package's online manual is at https://callr.r-lib.org, it can use
org.r-lib.callr
.If your R package belongs to your company, you can use the "reverse" of the company URL, possibly with an additional prefix. E.g. for the shiny R package by Posit,
co.posit.r-package.shiny
seems like a good name.If you don't set
otel_tracer_name
, thendefault_tracer_name
will user.package.<package-name>
as the tracer name.
Value
A list with entries:
-
name
: The supplied or auto-detected tracer name. -
package
: Auto-detected package name orNA
. -
on
: Whether tracing is enabled for this package.
Examples
default_tracer_name()
End an OpenTelemetry span
Description
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()
.
Usage
end_span(span)
Arguments
span |
The span to end. |
Value
Nothing.
See Also
Other OpenTelemetry trace API:
Zero Code Instrumentation
,
is_tracing_enabled()
,
local_active_span()
,
start_local_active_span()
,
start_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()
Extract a span context from HTTP headers received from a client
Description
The return value can be used as the parent
option when starting
a span.
Usage
extract_http_context(headers)
Arguments
headers |
A named list with one or two strings: |
Value
And otel_span_context object.
See Also
Examples
hdr <- otel::pack_http_context()
ctx <- otel::extract_http_context()
ctx$is_valid()
Record a value of an OpenTelemetry gauge
Description
Record a value of an OpenTelemetry gauge
Usage
gauge_record(name, value, attributes = NULL, context = NULL, meter = NULL)
Arguments
name |
Name of the gauge |
value |
Value to record. |
attributes |
Additional attributes to add. |
context |
Span context. If missing the active context is used, if any. |
meter |
Meter object (otel_meter). Otherwise it is passed to
|
Value
The gauge object (otel_gauge), invisibly.
See Also
Other OpenTelemetry metrics instruments:
counter_add()
,
histogram_record()
,
up_down_counter_add()
Other OpenTelemetry metrics API:
counter_add()
,
histogram_record()
,
is_measuring_enabled()
,
up_down_counter_add()
Examples
otel::gauge_record("temperature", 27)
Returns the active span context
Description
This is sometimes useful for logs or metrics, to associate logging and metrics reporting with traces.
Usage
get_active_span_context()
Details
Note that logs and metrics instruments automatically use the current span context, so often you don't need to call this function explicitly.
Value
The active span context, an otel_span_context object.
If there is no active span context, then an invalid span context is
returned, i.e. spc$is_valid()
will be FALSE
for the returned spc
.
Examples
fun <- function() {
otel::start_local_active_span("fun")
fun2()
}
fun2 <- function() {
otel::log("Log message", span_context = otel::get_active_span_context())
}
fun()
Get the default logger provider
Description
The logger provider defines how logs are exported when collecting telemetry data. It is unlikely that you need to call this function directly, but read on to learn how to configure which exporter to use.
Usage
get_default_logger_provider()
Details
If there is no default set currently, then it creates and sets a default.
The default logger provider is created based on the OTEL_R_LOGS_EXPORTER environment variable. This environment variable is specifically for R applications with OpenTelemetry support.
If this is not set, then the generic OTEL_LOGS_EXPORTER environment variable is used. This applies to all applications that support OpenTelemetry and use the OpenTelemetry SDK.
The following values are allowed:
-
none
: no traces are exported. -
stdout
orconsole
: uses otelsdk::logger_provider_stdstream, to write traces to the standard output. -
stderr
: uses otelsdk::logger_provider_stdstream, to write traces to the standard error. -
http
orotlp
: uses otelsdk::logger_provider_http, to send traces through HTTP, using the OpenTelemetry Protocol (OTLP). -
otlp/file
uses otelsdk::logger_provider_file to write logs to a JSONL file. -
<package>::<provider>
: will select the<provider>
object from the<package>
package to use as a logger provider. It calls<package>::<provider>$new()
to create the new logger provider. If this fails for some reason, e.g. the package is not installed, then it throws an error.
Value
The default logger provider, an otel_logger_provider object.
See Also
Other low level logs API:
get_logger()
,
logger_provider_noop
,
otel_logger
,
otel_logger_provider
Examples
get_default_logger_provider()
Get the default meter provider
Description
The meter provider defines how metrics are exported when collecting telemetry data. It is unlikely that you need to call this function directly, but read on to learn how to configure which exporter to use.
Usage
get_default_meter_provider()
Details
If there is no default set currently, then it creates and sets a default.
The default meter provider is created based on the OTEL_R_METRICS_EXPORTER environment variable. This environment variable is specifically for R applications with OpenTelemetry support.
If this is not set, then the generic OTEL_METRICS_EXPORTER environment variable is used. This applies to all applications that support OpenTelemetry and use the OpenTelemetry SDK.
The following values are allowed:
-
none
: no metrics are exported. -
stdout
orconsole
: uses otelsdk::meter_provider_stdstream, to write metrics to the standard output. -
stderr
: uses otelsdk::meter_provider_stdstream, to write metrics to the standard error. -
http
orotlp
: uses otelsdk::meter_provider_http, to send metrics through HTTP, using the OpenTelemetry Protocol (OTLP). -
otlp/file
uses otelsdk::meter_provider_file to write metrics to a JSONL file. -
<package>::<provider>
: will select the<provider>
object from the<package>
package to use as a meter provider. It calls<package>::<provider>$new()
to create the new meter provider. If this fails for some reason, e.g. the package is not installed, then it throws an error.
Value
The default meter provider, an otel_meter_provider object.
See Also
Other low level metrics API:
get_meter()
,
meter_provider_noop
,
otel_counter
,
otel_gauge
,
otel_histogram
,
otel_meter
,
otel_meter_provider
,
otel_up_down_counter
Examples
get_default_meter_provider()
Get the default tracer provider
Description
The tracer provider defines how traces are exported when collecting telemetry data. It is unlikely that you need to call this function directly, but read on to learn how to configure which exporter to use.
Usage
get_default_tracer_provider()
Details
If there is no default set currently, then it creates and sets a default.
The default tracer provider is created based on the OTEL_R_TRACES_EXPORTER environment variable. This environment variable is specifically for R applications with OpenTelemetry support.
If this is not set, then the generic OTEL_TRACES_EXPORTER environment variable is used. This applies to all applications that support OpenTelemetry and use the OpenTelemetry SDK.
The following values are allowed:
-
none
: no traces are exported. -
stdout
orconsole
: uses otelsdk::tracer_provider_stdstream, to write traces to the standard output. -
stderr
: uses otelsdk::tracer_provider_stdstream, to write traces to the standard error. -
http
orotlp
: uses otelsdk::tracer_provider_http, to send traces through HTTP, using the OpenTelemetry Protocol (OTLP). -
otlp/file
uses otelsdk::tracer_provider_file to write traces to a JSONL file. -
<package>::<provider>
: will select the<provider>
object from the<package>
package to use as a tracer provider. It calls<package>::<provider>$new()
to create the new tracer provider. If this fails for some reason, e.g. the package is not installed, then it throws an error.
Value
The default tracer provider, an otel_tracer_provider object. See otel_tracer_provider for its methods.
See Also
Other low level trace API:
get_tracer()
,
otel_span
,
otel_span_context
,
otel_tracer
,
otel_tracer_provider
,
tracer_provider_noop
Examples
get_default_tracer_provider()
Get a logger from the default logger provider
Description
Get a logger from the default logger provider
Usage
get_logger(
name = NULL,
minimum_severity = NULL,
version = NULL,
schema_url = NULL,
attributes = NULL,
...,
provider = NULL
)
Arguments
name |
Name of the new tracer. If missing, then deduced automatically. |
minimum_severity |
A log level, the minimum severity log messages to log. See log_severity_levels. |
version |
Optional. Specifies the version of the instrumentation
scope if the scope has a version (e.g. R package version).
Example value: |
schema_url |
Optional. Specifies the Schema URL that should be recorded in the emitted telemetry. |
attributes |
Optional. Specifies the instrumentation scope attributes to associate with emitted telemetry. |
... |
Additional arguments are passed to the |
provider |
Tracer provider to use. If |
Value
An otel_logger object.
See Also
Other low level logs API:
get_default_logger_provider()
,
logger_provider_noop
,
otel_logger
,
otel_logger_provider
Examples
myfun <- function() {
lgr <- otel::get_logger()
otel::log("Log message", logger = lgr)
}
myfun()
Get a meter from the default meter provider
Description
Get a meter from the default meter provider
Usage
get_meter(
name = NULL,
version = NULL,
schema_url = NULL,
attributes = NULL,
...,
provider = NULL
)
Arguments
name |
Name of the new tracer. If missing, then deduced automatically. |
version |
Optional. Specifies the version of the instrumentation
scope if the scope has a version (e.g. R package version).
Example value: |
schema_url |
Optional. Specifies the Schema URL that should be recorded in the emitted telemetry. |
attributes |
Optional. Specifies the instrumentation scope attributes to associate with emitted telemetry. |
... |
Additional arguments are passed to the |
provider |
Meter provider to use. If |
Value
An otel_meter object.
See Also
Other low level metrics API:
get_default_meter_provider()
,
meter_provider_noop
,
otel_counter
,
otel_gauge
,
otel_histogram
,
otel_meter
,
otel_meter_provider
,
otel_up_down_counter
Examples
myfun <- function() {
mtr <- otel::get_meter()
ctr <- mtr$create_counter("session-count")
ctr$add(1)
}
myfun()
Get a tracer from the default tracer provider
Description
Calls get_default_tracer_provider()
to get the default tracer
provider. Then calls its $get_tracer()
method to create a new tracer.
Usage
get_tracer(
name = NULL,
version = NULL,
schema_url = NULL,
attributes = NULL,
...,
provider = NULL
)
Arguments
name |
Name of the new tracer. If missing, then deduced
automatically using |
version |
Optional. Specifies the version of the instrumentation
scope if the scope has a version (e.g. R package version).
Example value: |
schema_url |
Optional. Specifies the Schema URL that should be recorded in the emitted telemetry. |
attributes |
Optional. Specifies the instrumentation scope attributes to associate with emitted telemetry. |
... |
Additional arguments are passed to the |
provider |
Tracer provider to use. If |
Details
Usually you do not need to call this function directly, because
start_local_active_span()
calls it for you.
Calling get_tracer()
multiple times with the same name
(or same
auto-deduced name) will return the same (internal) tracer object.
(Even if the R external pointer objects representing them are
different.)
A tracer is only deleted if its tracer provider is deleted and garbage collected.
Value
An OpenTelemetry tracer, an otel_tracer object.
See Also
Other low level trace API:
get_default_tracer_provider()
,
otel_span
,
otel_span_context
,
otel_tracer
,
otel_tracer_provider
,
tracer_provider_noop
Examples
myfun <- function() {
trc <- otel::get_tracer()
spn <- trc$start_span()
on.exit(otel::end_span(spn), add = TRUE)
otel::local_active_span(spn, end_on_exit = TRUE)
}
myfun()
Record a value of an OpenTelemetry histogram
Description
Record a value of an OpenTelemetry histogram
Usage
histogram_record(name, value, attributes = NULL, context = NULL, meter = NULL)
Arguments
name |
Name of the histogram. |
value |
Value to record. |
attributes |
Additional attributes to add. |
context |
Span context. If missing the active context is used, if any. |
meter |
Meter object (otel_meter). Otherwise it is passed to
|
Value
The histogram object (otel_histogram), invisibly.
See Also
Other OpenTelemetry metrics instruments:
counter_add()
,
gauge_record()
,
up_down_counter_add()
Other OpenTelemetry metrics API:
counter_add()
,
gauge_record()
,
is_measuring_enabled()
,
up_down_counter_add()
Examples
otel::histogram_record("response-time", 0.2)
Check whether OpenTelemetry logging is active
Description
This is useful for avoiding computation when logging is inactive.
Usage
is_logging_enabled(severity = "info", logger = NULL)
Arguments
severity |
Check if logs are emitted at this severity level. |
logger |
Logger object (otel_logger), or a logger name, the
instrumentation scope, to pass to |
Details
It calls get_logger()
with name
and then it calls the logger's
$is_enabled()
method.
Value
TRUE
is OpenTelemetry logging is active, FALSE
otherwise.
See Also
Other OpenTelemetry logs API:
log()
,
log_severity_levels
Examples
fun <- function() {
if (otel::is_logging_enabled()) {
xattr <- calculate_some_extra_attributes()
otel::log("Starting fun", attributes = xattr)
}
# ...
}
Check whether OpenTelemetry metrics collection is active
Description
This is useful for avoiding computation when metrics collection is inactive.
Usage
is_measuring_enabled(meter = NULL)
Arguments
meter |
Meter object (otel_meter), or a meter name, the
instrumentation scope, to pass to |
Details
It calls get_meter()
with name
and then it calls the meter's
$is_enabled()
method.
Value
TRUE
is OpenTelemetry metrics collection is active,
FALSE
otherwise.
See Also
Other OpenTelemetry metrics API:
counter_add()
,
gauge_record()
,
histogram_record()
,
up_down_counter_add()
Examples
fun <- function() {
if (otel::is_measuring_enabled()) {
xattr <- calculate_some_extra_attributes()
otel::counter_add("sessions", 1, attributes = xattr)
}
# ...
}
Check if tracing is active
Description
Checks whether OpenTelemetry tracing is active. This can be useful to avoid unnecessary computation when tracing is inactive.
Usage
is_tracing_enabled(tracer = NULL)
Arguments
tracer |
Tracer object (otel_tracer). It can also be a tracer
name, the instrumentation scope, or |
Details
It calls get_tracer()
with name
and then it calls the tracer's
$is_enabled()
method.
Value
TRUE
is OpenTelemetry tracing is active, FALSE
otherwise.
See Also
Other OpenTelemetry trace API:
Zero Code Instrumentation
,
end_span()
,
local_active_span()
,
start_local_active_span()
,
start_span()
,
tracing-constants
,
with_active_span()
Examples
fun <- function() {
if (otel::is_tracing_enabled()) {
xattr <- calculate_some_extra_attributes()
otel::start_local_active_span("fun", attributes = xattr)
}
# ...
}
Activate an OpenTelemetry span for an R scope
Description
Activates the span for the caller (or other) frame.
Usually you need this function for spans created with start_span()
,
which does not activate the new span. Usually you don't need it for
spans created with start_local_active_span()
, because it activates
the new span automatically.
Usage
local_active_span(span, end_on_exit = FALSE, activation_scope = parent.frame())
Arguments
span |
The OpenTelemetry span to activate. |
end_on_exit |
Whether to end the span when exiting the activation scope. |
activation_scope |
The scope to activate the span for, defaults to the caller frame. |
Details
When the frame ends, the span is deactivated and the previously active span will be active again, if there was any.
It is possible to activate the same span for multiple R frames.
Value
Nothing.
See Also
Other OpenTelemetry trace API:
Zero Code Instrumentation
,
end_span()
,
is_tracing_enabled()
,
start_local_active_span()
,
start_span()
,
tracing-constants
,
with_active_span()
Other tracing for concurrent code:
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()
Log an OpenTelemetry log message
Description
Log an OpenTelemetry log message
Usage
log(msg, ..., severity = "info", .envir = parent.frame(), logger = NULL)
log_trace(msg, ..., .envir = parent.frame(), logger = NULL)
log_debug(msg, ..., .envir = parent.frame(), logger = NULL)
log_info(msg, ..., .envir = parent.frame(), logger = NULL)
log_warn(msg, ..., .envir = parent.frame(), logger = NULL)
log_error(msg, ..., .envir = parent.frame(), logger = NULL)
log_fatal(msg, ..., .envir = parent.frame(), logger = NULL)
Arguments
msg |
Log message, may contain R expressions to evaluate within braces. |
... |
Additional arguments are passed to the |
severity |
Log severity, a string, one of "trace", "trace2", "trace3", "trace4", "debug", "debug2", "debug3", "debug4", "info", "info2", "info3", "info4", "warn", "warn2", "warn3", "warn4", "error", "error2", "error3", "error4", "fatal", "fatal2", "fatal3", "fatal4". |
.envir |
Environment to evaluate the interpolated expressions of the log message in. |
logger |
Logger to use. If not an OpenTelemetry logger object
(otel_logger), then it passed to |
Details
log_trace()
is the same as log()
with severity_level
"trace".
log_debug()
is the same as log()
with severity_level
"debug".
log_info()
is the same as log()
with severity_level
"info".
log_warn()
is the same as log()
with severity_level
"warn".
log_error)
is the same as log()
with severity_level
"error".
log_fatal()
is the same as log()
with severity_level
"fatal".
Value
The logger, invisibly.
See Also
Other OpenTelemetry logs API:
is_logging_enabled()
,
log_severity_levels
Examples
host <- "my.db.host"
port <- 6667
otel::log("Connecting to database at {host}:{port}")
OpenTelemetry log severity levels
Description
A named integer vector, the severity levels in numeric form. The names are the severity levels in text form. otel functions accept both forms as severity levels, but the text form is more readable.
Value
Not applicable.
See Also
Other OpenTelemetry logs API:
is_logging_enabled()
,
log()
Examples
log_severity_levels
No-op logger provider
Description
This is the logger provider (otel_logger_provider) otel uses when logging is disabled.
Details
All methods are no-ops or return objects that are also no-ops.
Value
Not applicable.
See Also
Other low level logs API:
get_default_logger_provider()
,
get_logger()
,
otel_logger
,
otel_logger_provider
Examples
logger_provider_noop$new()
No-op Meter Provider
Description
This is the meter provider (otel_meter_provider) otel uses when metrics collection is disabled.
Details
All methods are no-ops or return objects that are also no-ops.
Value
Not applicable.
See Also
Other low level metrics API:
get_default_meter_provider()
,
get_meter()
,
otel_counter
,
otel_gauge
,
otel_histogram
,
otel_meter
,
otel_meter_provider
,
otel_up_down_counter
Examples
meter_provider_noop$new()
OpenTelemetry Counter Object
Description
otel_meter_provider -> otel_meter -> otel_counter, otel_up_down_counter, otel_histogram, otel_gauge
Details
Usually you do not need to deal with otel_counter objects directly.
counter_add()
automatically sets up a meter and creates a counter
instrument, as needed.
A counter object is created by calling the create_counter()
method
of an otel_meter_provider()
.
You can use the add()
method to increment the counter by a positive
amount.
In R counters are represented by double values.
Value
Not applicable.
Methods
counter$add()
Increment the counter by a fixed amount.
Usage
counter$add(value, attributes = NULL, span_context = NULL, ...)
Arguments
-
value
: Value to increment the counter with. -
attributes
: Additional attributes to add. -
span_context
: Span context. If missing, the active context is used, if any.
Value
The counter object itself, invisibly.
See Also
Other low level metrics API:
get_default_meter_provider()
,
get_meter()
,
meter_provider_noop
,
otel_gauge
,
otel_histogram
,
otel_meter
,
otel_meter_provider
,
otel_up_down_counter
Examples
mp <- get_default_meter_provider()
mtr <- mp$get_meter()
ctr <- mtr$create_counter("session")
ctr$add(1)
OpenTelemetry Gauge Object
Description
otel_meter_provider -> otel_meter -> otel_counter, otel_up_down_counter, otel_histogram, otel_gauge
Details
Usually you do not need to deal with otel_gauge objects directly.
gauge_record()
automatically sets up a meter and creates a
gauge instrument, as needed.
A gauge object is created by calling the create_gauge()
method
of an otel_meter_provider()
.
You can use the record()
method to record the current value.
In R gauge values are represented by doubles.
Value
Not applicable.
Methods
gauge$record()
Update the statistics with the specified amount.
Usage
gauge$record(value, attributes = NULL, span_context = NULL, ...)
Arguments
-
value
: A numeric value. The current absolute value. -
attributes
: Additional attributes to add. -
span_context
: Span context. If missing, the active context is used, if any.
Value
The gauge object itself, invisibly.
See Also
Other low level metrics API:
get_default_meter_provider()
,
get_meter()
,
meter_provider_noop
,
otel_counter
,
otel_histogram
,
otel_meter
,
otel_meter_provider
,
otel_up_down_counter
Examples
mp <- get_default_meter_provider()
mtr <- mp$get_meter()
gge <- mtr$create_gauge("response-time")
gge$record(1.123)
OpenTelemetry Histogram Object
Description
otel_meter_provider -> otel_meter -> otel_counter, otel_up_down_counter, otel_histogram, otel_gauge
Details
Usually you do not need to deal with otel_histogram objects directly.
histogram_record()
automatically sets up a meter and creates a
histogram instrument, as needed.
A histogram object is created by calling the create_histogram()
method
of an otel_meter_provider()
.
You can use the record()
method to update the statistics with the
specified amount.
In R histogram values are represented by doubles.
Value
Not applicable.
Methods
histogram$record()
Update the statistics with the specified amount.
Usage
histogram$record(value, attributes = NULL, span_context = NULL, ...)
Arguments
-
value
: A numeric value to record. -
attributes
: Additional attributes to add. -
span_context
: Span context. If missing, the active context is used, if any.
Value
The histogram object itself, invisibly.
See Also
Other low level metrics API:
get_default_meter_provider()
,
get_meter()
,
meter_provider_noop
,
otel_counter
,
otel_gauge
,
otel_meter
,
otel_meter_provider
,
otel_up_down_counter
Examples
mp <- get_default_meter_provider()
mtr <- mp$get_meter()
hst <- mtr$create_histogram("response-time")
hst$record(1.123)
OpenTelemetry Logger Object
Description
otel_logger_provider -> otel_logger
Details
Usually you do not need to deal with otel_logger objects directly.
log()
automatically sets up the logger for emitting the logs.
A logger object is created by calling the get_logger()
method of an
otel_logger_provider.
You can use the log()
method of the logger object to emit logs.
Typically there is a separate logger object for each instrumented R package.
Value
Not applicable.
Methods
logger$is_enabled()
Whether the logger is active and emitting logs at a certain severity level.
This is equivalent to the is_logging_enabled()
function.
Usage
logger$is_enabled(severity = "info", event_id = NULL)
Arguments
-
severity
: Check if logs are emitted at this severity level. -
event_id
: Not implemented yet.
Value
Logical scalar.
logger$get_minimum_severity()
Get the current minimum severity at which the logger is emitting logs.
Usage
logger_get_minimum_severity()
Value
Named integer scalar.
logger$set_minimum_severiry()
Set the minimum severity for emitting logs.
Usage
logger$set_minimum_severity(minimum_severity)
Arguments
-
minimum_severity
: Log severity, a string, one of "trace", "trace2", "trace3", "trace4", "debug", "debug2", "debug3", "debug4", "info", "info2", "info3", "info4", "warn", "warn2", "warn3", "warn4", "error", "error2", "error3", "error4", "fatal", "fatal2", "fatal3", "fatal4".
Value
Nothing.
logger$log()
Log an OpenTelemetry log message.
Usage
logger$log( msg = "", severity = "info", span_context = NULL, span_id = NULL, trace_id = NULL, trace_flags = NULL, timestamp = SYs.time(), observed_timestamp = NULL, attributes = NULL, .envir = parent.frame() )
Arguments
-
msg
: Log message, may contain R expressions to evaluate within braces. -
severity
: Log severity, a string, one of "trace", "trace2", "trace3", "trace4", "debug", "debug2", "debug3", "debug4", "info", "info2", "info3", "info4", "warn", "warn2", "warn3", "warn4", "error", "error2", "error3", "error4", "fatal", "fatal2", "fatal3", "fatal4". -
span_context
: An otel_span_context object to associate the log message with a span. -
span_id
: Alternatively tospan_context
, you can also specifyspan_id
,trace_id
andtrace_flags
to associate a log message with a span. -
trace_id
: Alternatively tospan_context
, you can also specifyspan_id
,trace_id
andtrace_flags
to associate a log message with a span. -
trace_flags
: Alternatively tospan_context
, you can also specifyspan_id
,trace_id
andtrace_flags
to associate a log message with a span. -
timestamp
: Time stamp, defaults to the current time. This is the time the logged event occurred. -
observed_timestamp
: Observed time stamp, this is the time the event was observed. -
attributes
: Optional attributes, seeas_attributes()
for the possible values. -
.envir
: Environment to evaluate the interpolated expressions of the log message in. '
Value
The logger object, invisibly.
logger$trace()
The same as logger$log()
, with severity = "trace"
.
logger$debug()
The same as logger$log()
, with severity = "debug"
.
logger$info()
The same as logger$log()
, with severity = "info"
.
logger$warn()
The same as logger$log()
, with severity = "warn"
.
logger$error()
The same as logger$log()
, with severity = "error"
.
logger$fatal()
The same as logger$log()
, with severity = "fatal"
.
See Also
Other low level logs API:
get_default_logger_provider()
,
get_logger()
,
logger_provider_noop
,
otel_logger_provider
Examples
lp <- get_default_logger_provider()
lgr <- lp$get_logger()
platform <- utils::sessionInfo()$platform
lgr$log("This is a log message from {platform}.", severity = "trace")
OpenTelemetry Logger Provider Object
Description
otel_logger_provider -> otel_logger
Details
The logger provider defines how logs are exported when collecting telemetry data. It is unlikely that you need to use logger provider objects directly.
Usually there is a single logger provider for an R app or script.
Typically the logger provider is created automatically, at the first
log()
call. otel decides which logger provider class to use based on
Environment Variables.
Value
Not applicable.
Implementations
Note that this list is updated manually and may be incomplete.
-
logger_provider_noop: No-op logger provider, used when no logs are emitted.
-
otelsdk::logger_provider_file: Save logs to a JSONL file.
-
otelsdk::logger_provider_http: Send logs to a collector over HTTP/OTLP.
-
otelsdk::logger_provider_stdstream: Write logs to standard output or error or to a file. Primarily for debugging.
Methods
logger_provider$get_logger()
Get or create a new logger object.
Usage
logger_provider$get_logger( name = NULL, version = NULL, schema_url = NULL, attributes = NULL )
Arguments
-
name
Logger name. It makes sense to reuse the tracer name as the logger name. Seeget_logger()
anddefault_tracer_name()
. -
version
: Optional. Specifies the version of the instrumentation scope if the scope has a version (e.g. R package version). Example value:"1.0.0"
. -
schema_url
: Optional. Specifies the Schema URL that should be recorded in the emitted telemetry. -
attributes
: Optional. Specifies the instrumentation scope attributes to associate with emitted telemetry. Seeas_attributes()
for allowed values. You can also useas_attributes()
to convert R objects to OpenTelemetry attributes.
Value
An OpenTelemetry logger (otel_logger) object.
See also
get_default_logger_provider()
, get_logger()
.
logger_provider$flush()
Force any buffered logs to flush. Logger providers might not implement this method.
Usage
logger_provider$flush()
Value
Nothing.
See Also
Other low level logs API:
get_default_logger_provider()
,
get_logger()
,
logger_provider_noop
,
otel_logger
Examples
lp <- otel::get_default_logger_provider()
lgr <- lp$get_logger()
lgr$is_enabled()
OpenTelemetry Meter Object
Description
otel_meter_provider -> otel_meter -> otel_counter, otel_up_down_counter, otel_histogram, otel_gauge
Details
Usually you do not need to deal with otel_meter objects directly.
counter_add()
, up_down_counter_add()
, histogram_record()
and
gauge_record()
automatically set up the meter and uses it to create
instruments.
A meter object is created by calling the get_meter()
method of an
otel_meter_provider.
You can use the create_counter()
, create_up_down_counter()
,
create_histogram()
, create_gauge()
methods of the meter object to
create instruments.
Typically there is a separate meter object for each instrumented R package.
Value
Not applicable.
Methods
meter$is_enabled()
Whether the meter is active and emitting measurements.
This is equivalent to the is_measuring_enabled()
function.
Usage
meter$is_enabled()
Value
Logical scalar.
meter$create_counter()
Create a new counter instrument.
Usage
create_counter(name, description = NULL, unit = NULL)
Arguments
-
name
: Name of the instrument. -
description
: Optional description. -
unit
: Optional measurement unit. If specified, it should use units from Unified Code for Units of Measure, according to the OpenTelemetry semantic conventions.
Value
An OpenTelemetry counter (otel_counter) object.
meter$create_up_down_counter()
Create a new up-down counter instrument.
Usage
create_up_down_counter(name, description = NULL, unit = NULL)
Arguments
-
name
: Name of the instrument. -
description
: Optional description. -
unit
: Optional measurement unit. If specified, it should use units from Unified Code for Units of Measure, according to the OpenTelemetry semantic conventions.
Value
An OpenTelemetry counter (otel_up_down_counter) object.
meter$create_histogram()
Create a new histogram.
Usage
create_histogram(name, description = NULL, unit = NULL)
Arguments
-
name
: Name of the instrument. -
description
: Optional description. -
unit
: Optional measurement unit. If specified, it should use units from Unified Code for Units of Measure, according to the OpenTelemetry semantic conventions.
Value
An OpenTelemetry histogram (otel_histogram) object.
meter$create_gauge()
Create a new gauge.
Usage
create_gauge(name, description = NULL, unit = NULL)
Arguments
-
name
: Name of the instrument. -
description
: Optional description. -
unit
: Optional measurement unit. If specified, it should use units from Unified Code for Units of Measure, according to the OpenTelemetry semantic conventions.
Value
An OpenTelemetry gauge (otel_gauge) object.
See Also
Other low level metrics API:
get_default_meter_provider()
,
get_meter()
,
meter_provider_noop
,
otel_counter
,
otel_gauge
,
otel_histogram
,
otel_meter_provider
,
otel_up_down_counter
Examples
mp <- get_default_meter_provider()
mtr <- mp$get_meter()
ctr <- mtr$create_counter("session")
ctr$add(1)
OpenTelemetry meter provider objects
Description
otel_meter_provider -> otel_meter -> otel_counter, otel_up_down_counter, otel_histogram, otel_gauge
Details
The meter provider defines how metrics are exported when collecting telemetry data. It is unlikely that you need to use meter provider objects directly.
Usually there is a single meter provider for an R app or script.
Typically the meter provider is created automatically, at the first
counter_add()
, up_down_counter_add()
, histogram_record()
,
gauge_record()
or get_meter()
call. otel decides which meter
provider class to use based on Environment Variables.
Value
Not applicable.
Implementations
Note that this list is updated manually and may be incomplete.
-
meter_provider_noop: No-op meter provider, used when no metrics are emitted.
-
otelsdk::meter_provider_file: Save metrics to a JSONL file.
-
otelsdk::meter_provider_http: Send metrics to a collector over HTTP/OTLP.
-
otelsdk::meter_provider_memory: Collect emitted metrics in memory. For testing.
-
otelsdk::meter_provider_stdstream: Write metrics to standard output or error or to a file. Primarily for debugging.
Methods
meter_provider$get_meter()
Get or create a new meter object.
Usage
meter_provider$get_meter( name = NULL, version = NULL, schema_url = NULL, attributes = NULL )
Arguments
-
name
: Meter name, seeget_meter()
. -
version
: Optional. Specifies the version of the instrumentation scope if the scope has a version (e.g. R package version). Example value:"1.0.0"
. -
schema_url
: Optional. Specifies the Schema URL that should be recorded in the emitted telemetry. -
attributes
: Optional. Specifies the instrumentation scope attributes to associate with emitted telemetry. Seeas_attributes()
for allowed values. You can also useas_attributes()
to convert R objects to OpenTelemetry attributes.
Value
Returns an OpenTelemetry meter (otel_meter) object.
See also
get_default_meter_provider()
, get_meter()
.
meter_provider$flush()
Force any buffered metrics to flush. Meter providers might not implement this method.
Usage
meter_provider$flush()
Value
Nothing.
meter_provider$shutdown()
Stop the meter provider. Stops collecting and emitting measurements.
Usage
meter_provider$shurdown()
Value
Nothing
See Also
Other low level metrics API:
get_default_meter_provider()
,
get_meter()
,
meter_provider_noop
,
otel_counter
,
otel_gauge
,
otel_histogram
,
otel_meter
,
otel_up_down_counter
Examples
mp <- otel::get_default_meter_provider()
mtr <- mp$get_meter()
mtr$is_enabled()
OpenTelemetry Span Object
Description
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.)
Value
Not applicable.
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.
Usage
span$add_event(name, attributes = NULL, timestamp = NULL)
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.
Value
The span object itself, invisibly.
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.
Usage
span$end(options = NULL, status_code = NULL)
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.
Value
The span object itself, invisibly.
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.
Usage
span$get_context()
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.
Usage
span$is_recording()
Value
A logical scalar, TRUE
if the span is recorded.
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.
Usage
span$record_exception(error_condition, attributes, ...)
Arguments
-
error_condition
: An R error object to record. -
attributes
: Additional attributes to add to the exception event. -
...
: Passed to thespan$add_event()
method.
Value
The span object itself, invisibly.
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.
Usage
span$set_attribute(name, value)
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.
Value
The span object itself, invisibly.
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.
Usage
span$set_status(status_code, description = NULL)
Arguments
-
status_code
: Possible values: unset, ok, error. -
description
: Optional description, a string.
Value
The span itself, invisibly.
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.
Usage
span$update_name(name)
Arguments
-
name
: String, the new span name.
Value
The span object itself, invisibly.
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()
An OpenTelemetry Span Context object
Description
otel_tracer_provider -> otel_tracer -> otel_span -> otel_span_context
Details
This is a representation of a span that can be serialized, copied to other processes, and it can be used to create new child spans.
Value
Not applicable.
Methods
span_context$get_span_id()
Get the id of the span.
Usage
span_context$get_span_id()
Value
String scalar, a span id. For invalid spans it is invalid_span_id.
span_context$get_trace_flags()
Get the trace flags of a span.
See the specification for more details on trace flags.
Usage
span_context$get_trace_flags()
Value
A list with entries:
-
is_sampled
: logical flag, whether the trace of the span is sampled. IfFALSE
then the caller is not recording the trace. See details in the specification. -
is_random
: logical flag, it specifies how trace ids are generated. See details in the specification.
span_context$get_trace_id()
Get the id of the trace the span belongs to.
Usage
span_context$get_trace_id()
Value
A string scalar, a trace id. For invalid spans it is invalid_trace_id.
span_context$is_remote()
Whether the span was propagated from a remote parent.
Usage
span_context$is_remote()
Value
A logical scalar.
span_context$is_sampled()
Whether the span is sampled. This is the same as the is_sampled
trace flags, see get_trace_flags()
above.
Usage
span_context$is_sampled()
Value
Logical scalar.
span_context$is_valid()
Whether the span is valid. Sometimes otel functions return an
invalid span or a span context referring to an invalid span. E.g.
get_active_span_context()
does that if there is no active span.
is_valid()
checks if the span is valid.
An span id of an invalid span is invalid_span_id.
Usage
span_context$is_valid()
Value
A logical scalar.
span_context$to_http_headers()
Serialize the span context into one or more HTTP headers that can be transmitted to other processes or servers, to create a distributed trace.
The other process can deserialize these headers into a span context that can be used to create new remote spans.
Usage
span_context$to_http_headers()
Value
A named character vector, the HTTP header representation of the span
context. Usually includes a traceparent
header. May include other
headers.
See Also
Other low level trace API:
get_default_tracer_provider()
,
get_tracer()
,
otel_span
,
otel_tracer
,
otel_tracer_provider
,
tracer_provider_noop
Examples
spc <- get_active_span_context()
spc$get_trace_flags()
spc$get_trace_id()
spc$get_span_id()
spc$is_remote()
spc$is_sampled()
spc$is_valid()
spc$to_http_headers()
OpenTelemetry Tracer Object
Description
otel_tracer_provider -> otel_tracer -> otel_span -> otel_span_context
Details
Usually you do not need to deal with otel_tracer objects directly.
start_local_active_span()
(and start_span()
) automatically
sets up the tracer and uses it to create spans.
A tracer object is created by calling the get_tracer()
method of an
otel_tracer_provider.
You can use the start_span()
method of the tracer object to create a
span.
Typically there is a separate tracer object for each instrumented R package.
Value
Not applicable.
Methods
tracer$start_span()
Creates and starts a new span.
It does not activate the new span.
It is equivalent to the start_span()
function.
Usage
tracer_start_span( name = NULL, attributes = NULL, links = NULL, options = 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 useas_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 isNA
, then the span has no parent and it will be a root span. If it isNULL
, 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".
-
Value
A new otel_span object.
tracer$is_enabled()
Whether the tracer is active and recording traces.
This is equivalent to the is_tracing_enabled()
function.
Usage
tracer$is_enabled()
Value
Logical scalar.
tracer$flush()
Flush the tracer provider: force any buffered spans to flush. Tracer providers might not implement this method.
Usage
tracer$flush()
Value
Nothing.
See Also
Other low level trace API:
get_default_tracer_provider()
,
get_tracer()
,
otel_span
,
otel_span_context
,
otel_tracer_provider
,
tracer_provider_noop
Examples
tp <- get_default_tracer_provider()
trc <- tp$get_tracer()
trc$is_enabled()
OpenTelemetry Tracer Provider Object
Description
otel_tracer_provider -> otel_tracer -> otel_span -> otel_span_context
Details
The tracer provider defines how traces are exported when collecting telemetry data. It is unlikely that you'd need to use tracer provider objects directly.
Usually there is a single tracer provider for an R app or script.
Typically the tracer provider is created automatically, at the first
start_local_active_span()
or start_span()
call. otel decides which
tracer provider class to use based on Environment Variables.
Value
Not applicable.
Implementations
Note that this list is updated manually and may be incomplete.
-
tracer_provider_noop: No-op tracer provider, used when no traces are emitted.
-
otelsdk::tracer_provider_file: Save traces to a JSONL file.
-
otelsdk::tracer_provider_http: Send traces to a collector over HTTP/OTLP.
-
otelsdk::tracer_provider_memory: Collect emitted traces in memory. For testing.
-
otelsdk::tracer_provider_stdstream: Write traces to standard output or error or to a file. Primarily for debugging.
Methods
tracer_provider$get_tracer()
Get or create a new tracer object.
Usage
tracer_provider$get_tracer( name = NULL, version = NULL, schema_url = NULL, attributes = NULL )
Arguments
-
name
: Tracer name, seeget_tracer()
. -
version
: Optional. Specifies the version of the instrumentation scope if the scope has a version (e.g. R package version). Example value:"1.0.0"
. -
schema_url
: Optional. Specifies the Schema URL that should be recorded in the emitted telemetry. -
attributes
: Optional. Specifies the instrumentation scope attributes to associate with emitted telemetry. Seeas_attributes()
for allowed values. You can also useas_attributes()
to convert R objects to OpenTelemetry attributes.
Value
Returns an OpenTelemetry tracer (otel_tracer) object.
See also
get_default_tracer_provider()
, get_tracer()
.
tracer_provider$flush()
Force any buffered spans to flush. Tracer providers might not implement this method.
Usage
tracer_provider$flush()
Value
Nothing.
See Also
Other low level trace API:
get_default_tracer_provider()
,
get_tracer()
,
otel_span
,
otel_span_context
,
otel_tracer
,
tracer_provider_noop
Examples
tp <- otel::get_default_tracer_provider()
trc <- tp$get_tracer()
trc$is_enabled()
OpenTelemetry Up-Down Counter Object
Description
otel_meter_provider -> otel_meter -> otel_counter, otel_up_down_counter, otel_histogram, otel_gauge
Details
Usually you do not need to deal with otel_up_down_counter objects directly.
up_down_counter_add()
automatically sets up a meter and creates an
up-down counter instrument, as needed.
An up-down counter object is created by calling the
create_up_down_counter()
method of an otel_meter_provider()
.
You can use the add()
method to increment or decrement the counter.
In R up-down counters are represented by double values.
Value
Not applicable.
Methods
up_down_counter$add()
Increment or decrement the up-down counter by a fixed amount.
Usage
up_down_counter$add(value, attributes = NULL, span_context = NULL, ...)
Arguments
-
value
: Value to increment of decrement the up-down counter with. -
attributes
: Additional attributes to add. -
span_context
: Span context. If missing, the active context is used, if any.
Value
The up-down counter object itself, invisibly.
See Also
Other low level metrics API:
get_default_meter_provider()
,
get_meter()
,
meter_provider_noop
,
otel_counter
,
otel_gauge
,
otel_histogram
,
otel_meter
,
otel_meter_provider
Examples
mp <- get_default_meter_provider()
mtr <- mp$get_meter()
ctr <- mtr$create_up_down_counter("session")
ctr$add(1)
Pack the currently active span context into standard HTTP OpenTelemetry headers
Description
The returned headers can be sent over HTTP, or set as environment variables for subprocesses.
Usage
pack_http_context()
Value
A named character vector, with lowercase names. It might be an empty vector, e.g. if tracing is disabled.
See Also
Examples
hdr <- otel::pack_http_context()
ctx <- otel::extract_http_context()
ctx$is_valid()
Start and activate a span
Description
Creates, starts and activates an OpenTelemetry span.
Usually you want this functions instead of start_span()
, which does
not activate the new span.
Usage
start_local_active_span(
name = NULL,
attributes = NULL,
links = NULL,
options = NULL,
...,
tracer = NULL,
activation_scope = parent.frame(),
end_on_exit = TRUE
)
Arguments
name |
Name of the span. If not specified it will be |
attributes |
Span attributes. OpenTelemetry supports the following
R types as attributes: 'character, logical, double, integer.
You may use |
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:
|
... |
Additional arguments are passed to the |
tracer |
A tracer object or the name of the tracer to use, see
|
activation_scope |
The R scope to activate the span for. Defaults to the caller frame. |
end_on_exit |
Whether to also end the span when the activation scope exits. |
Details
If end_on_exit
is TRUE
(the default), then it also ends the span
when the activation scope finishes.
Value
The new OpenTelemetry span object (of class otel_span), invisibly. See otel_span for information about the returned object.
See Also
Other OpenTelemetry trace API:
Zero Code Instrumentation
,
end_span()
,
is_tracing_enabled()
,
local_active_span()
,
start_span()
,
tracing-constants
,
with_active_span()
Examples
fn1 <- function() {
otel::start_local_active_span("fn1")
fn2()
}
fn2 <- function() {
otel::start_local_active_span("fn2")
}
fn1()
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
)
Arguments
name |
Name of the span. If not specified it will be |
attributes |
Span attributes. OpenTelemetry supports the following
R types as attributes: 'character, logical, double, integer.
You may use |
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:
|
... |
Additional arguments are passed to the |
tracer |
A tracer object or the name of the tracer to use, see
|
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.
Value
An OpenTelemetry span (otel_span).
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()
No-op tracer provider
Description
This is the tracer provider (otel_tracer_provider) otel uses when tracing is disabled.
Details
All methods are no-ops or return objects that are also no-ops.
Value
Not applicable.
See Also
Other low level trace API:
get_default_tracer_provider()
,
get_tracer()
,
otel_span
,
otel_span_context
,
otel_tracer
,
otel_tracer_provider
Examples
tracer_provider_noop$new()
OpenTelemetry tracing constants
Description
Various constants related OpenTelemetry tracing.
Usage
invalid_trace_id
invalid_span_id
span_kinds
span_status_codes
Details
invalid_trace_id
invalid_trace_id
is a string scalar, an invalid trace id. If there is
no active span, then get_active_span_context()
returns a span context
that has an invalid trace id.
invalid_span_id
invalid_span_id
is a string scalar, an invalid span id. If there is
no active span, then get_active_span_context()
returns a span context
that has an invalid span id.
span_kinds
span_kinds
is a character vector listing all possible span kinds.
See the OpenTelemetry specification for
when to use which.
span_status_codes
span_status_codes
is a character vector listing all possible span
status codes. You can set the status code of a a span with the
set_status()
method of otel_span objects. If not set explicitly,
and the span is ended automatically (by start_local_active_span()
,
local_active_span()
or with_active_span()
), then otel sets the
status automatically to "ok" or "error", depending on whether the span
ended during handling an error.
Value
Not applicable.
See Also
Other OpenTelemetry trace API:
Zero Code Instrumentation
,
end_span()
,
is_tracing_enabled()
,
local_active_span()
,
start_local_active_span()
,
start_span()
,
with_active_span()
Examples
invalid_trace_id
invalid_span_id
span_kinds
span_status_codes
Increase or decrease an OpenTelemetry up-down counter
Description
Increase or decrease an OpenTelemetry up-down counter
Usage
up_down_counter_add(
name,
value = 1L,
attributes = NULL,
context = NULL,
meter = NULL
)
Arguments
name |
Name of the up-down counter. |
value |
Value to add to or subtract from the counter, defaults to 1. |
attributes |
Additional attributes to add. |
context |
Span context. If missing the active context is used, if any. |
meter |
Meter object (otel_meter). Otherwise it is passed to
|
Value
The up-down counter object (otel_up_down_counter), invisibly.
See Also
Other OpenTelemetry metrics instruments:
counter_add()
,
gauge_record()
,
histogram_record()
Other OpenTelemetry metrics API:
counter_add()
,
gauge_record()
,
histogram_record()
,
is_measuring_enabled()
Examples
otel::up_down_counter_add("session-count", 1)
Evaluate R code with an active OpenTelemetry span
Description
Activates the span for evaluating an R expression.
Usually you need this function for spans created with start_span()
,
which does not activate the new span. Usually you don't need it for
spans created with start_local_active_span()
, because it activates
the new span automatically.
Usage
with_active_span(span, expr, end_on_exit = FALSE)
Arguments
span |
The OpenTelemetry span to activate. |
expr |
R expression to evaluate. |
end_on_exit |
Whether to end after evaluating the R expression. |
Details
After expr
is evaluated (or an error occurs), the span is deactivated
and the previously active span will be active again, if there was any.
It is possible to activate the same span for multiple R frames.
Value
The return value of expr
.
See Also
Other OpenTelemetry trace API:
Zero Code Instrumentation
,
end_span()
,
is_tracing_enabled()
,
local_active_span()
,
start_local_active_span()
,
start_span()
,
tracing-constants
Other tracing for concurrent code:
local_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() {
otel::with_active_span(spn, {
# create child span
spn2 <- otel::start_local_active_span("myfun/2")
})
}
myfun2 <- function() {
otel::with_active_span(spn, {
# create child span
spn3 <- otel::start_local_active_span("myfun/3")
})
}
myfun()
myfun2()
end_span(spn)
}
fun()