Title: 'R' 'SDK' and Exporters for 'OpenTelemetry'
Version: 0.2.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 contains the 'OpenTelemetry' 'SDK', and exporters. Use this package to export traces, metrics, logs from instrumented 'R' code. Use the 'otel' package to instrument your 'R' code for 'OpenTelemetry'.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2.9000
SystemRequirements: cmake, protobuf-compiler, libprotobuf, libcurl, zlib, GNU make
Imports: otel, utils
Suggests: callr, cli, curl, gh, jsonlite, processx, ps, rlang, spelling, testthat (≥ 3.0.0), webfakes, withr
Config/testthat/edition: 3
URL: https://otelsdk.r-lib.org, https://github.com/r-lib/otelsdk
Config/Needs/check: r-lib/otel, gaborcsardi/testthatlabs
Config/Needs/coverage: r-lib/otel, gaborcsardi/testthatlabs
Config/Needs/website: tidyverse/tidytemplate, r-lib/otel
BugReports: https://github.com/r-lib/otelsdk/issues
NeedsCompilation: yes
Packaged: 2025-09-05 13:04:35 UTC; gaborcsardi
Author: Gábor Csárdi [aut, cre], Posit Software, PBC ROR ID [cph, fnd], opentelemetry-cpp authors [ctb]
Maintainer: Gábor Csárdi <csardi.gabor@gmail.com>
Repository: CRAN
Date/Publication: 2025-09-10 08:00:06 UTC

otelsdk: 'R' 'SDK' and Exporters for 'OpenTelemetry'

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 contains the 'OpenTelemetry' 'SDK', and exporters. Use this package to export traces, metrics, logs from instrumented 'R' code. Use the 'otel' package to instrument your 'R' code for 'OpenTelemetry'.

Value

Not applicable.

Author(s)

Maintainer: Gábor Csárdi csardi.gabor@gmail.com

Other contributors:

See Also

Useful links:

Examples

# Run your R script with OpenTelemetry tracing:
# OTEL_TRACER_EXPORTER=otlp R -f myapp.R

Collecting Telemetry Data

Description

This page is about collecting telemetry data from instrumented R packages. If you need help with instrumenting your R package, see Getting Started in the otel package.

Value

Not applicable.

Usage

Setup

Setup for remote collectors

There are a lot of services that offer an OpenTelemetry collector for tracers, logs and metrics, many of them supporting all three of them. There are also local apps that work as a collector. We tried otelsdk with the following ones:

Grafana

Follow the documentation. Create an API token. You'll need to use the Grafana instrance ID as your username, and the token as the password in HTTP Basic auth. E.g. in R do this to get the base64 encoded token. instance-id is a (currently seven digit) number and a string with a glc_ prefix. 

openssl::base64_encode("<instance-id>:<api-token>")

Then use this encoded token to set the Authorization header: 

OTEL_EXPORTER_OTLP_PROTOCOL="http"
OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-central-0.grafana.net/otlp" \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic%20<base64-encoded-token>"
OTEL_RESOURCE_ATTRIBUTES="service.name=<name-of-your-app,service.namespace=<name-of-your-namespace>,deployment.environment=test"

Your endpoint URL is probably different, use the one that you see on your dashboard.

If you want to export logs and/or metrics, set these environment variables, respectively: 

OTEL_LOGS_EXPORTER=http
OTEL_LOG_LEVEL=debug
OTEL_METRICS_EXPORTER=http

It also makes sense to set the desired log level.

Grafana suggests running an OpenTelemetry collector on premise instead of sending telemetry data to them directly. But nevertheless you can start out without running your own collector, they call this "quick start" mode.

Pydantic Logfire

Create a project and a write token. Note that the URLs you need to use are different if you are within the EU! You probably need to replace us with eu in the URL if you are in the EU. Set these environment variables: 

OTEL_TRACES_EXPORTER=http
OTEL_EXPORTER_OTLP_ENDPOINT="https://logfire-us.pydantic.dev"
OTEL_EXPORTER_OTLP_HEADERS="Authorization=<your-write-token>"

For logs also set OTEL_LOGS_EXPORTER and the desired log level: 

OTEL_LOGS_EXPORTER=http
OTEL_LOG_LEVEL=debug

For exporting metrics also set 

OTEL_METRICS_EXPORTER=http

Setup for local collectors

otel-tui

otel-tui is a terminal app that supports traces, logs and metrics. It is great for development, as you can keep all your telemetry local while instrumenting your package or app. Follow the installation instructions and then run the app from a terminal: 

otel-tui

It listens on the default port, so the setup is very simple, set these environment variables (or a subset if you don't want metrics or logs): 

OTEL_TRACES_EXPORTER=http
OTEL_LOGS_EXPORTER=http
OTEL_LOG_LEVEL=debug
OTEL_METRICS_EXPORTER=http
otel-desktop-viewer

otel-desktop-viewer is similar to otel-tui, but has a web UI. Follow the installation instructions and start the app from a terminal: 

otel-desktop-viewer

It should start a new windows or tab in your local web browser. Set the usual environment variable for your R app: 

OTEL_TRACES_EXPORTER=http
Jaeger

If you have Docker, you can start a Jaeger container on the default port: 

docker run --rm --name jaeger \
 -p 16686:16686 \
 -p 4317:4317 \
 -p 4318:4318 \
 -p 5778:5778 \
 -p 9411:9411 \
 jaegertracing/jaeger:2.4.0

Go to ⁠http://localhost:16686/⁠ to view the Jaeger UI.

SigNoz

To run SigNoz locally with Docker, clone the repository at https://github.com/SigNoz/signoz: 

git clone --depth 1 https://github.com/SigNoz/signoz

and then run Docker Compose from the ⁠deploy/docker/⁠ subdirectory: 

cd deploy/docker
docker compose up

Go to ⁠http://localhost:8080⁠ to see the SigNoz UI.

Examples

# See above

Environment variables to configure otelsdk

Description

See also the Environment Variables in the otel package, which is charge of selecting the exporters to use.

Value

Not applicable.

The OpenTelemetry Specification

Most of these environment variables are based on the OpenTelemetry Specification, version 1.48.0.

The environment variables with an 'OTEL_R_' prefix are not (yet) in the standard, and are specific for the otel and otelsdk R packages.

General SDK Configuration

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.

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.

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.

Attribute Limits

OTLP/HTTP Exporters

These environment variables are used by tracer_provider_http, meter_provider_http and logger_provider_http.

For every set of environment variables, the signal specific ones have priority over the generic one.

OTLP/FILE Exporters

These environment variables are used by tracer_provider_file, meter_provider_file and logger_provider_file.

For every set of environment variables, the signal specific ones have priority over the generic one.

Batch Processor

These environment variables are used by tracer_provider_http, and logger_provider_http.

Metric Reader

These environment variables are used by meter_provider_http, meter_provider_stdstream meter_provider_memory and meter_provider_file.

Metric Exporters

These environment variables are used by meter_provider_http and meter_provider_memory.

Standard Stream Exporters

These environment variables are used by tracer_provider_stdstream, meter_provider_stdstream and logger_provider_stdstream.

The signal specific environment variables have priority over the generic one.

In-Memory Exporters

These environment variables are used by tracer_provider_memory and meter_provider_memory.

The signal specific environment variables have priority over the generic one.

Support Matrix of all OpenTelemetry Environment Variables for R

Name Supported
OTEL_SDK_DISABLED +
OTEL_RESOURCE_ATTRIBUTES +
OTEL_SERVICE_NAME +
OTEL_LOG_LEVEL +
OTEL_PROPAGATORS -
OTEL_BSP_SCHEDULE_DELAY +
OTEL_BSP_EXPORT_TIMEOUT -
OTEL_BSP_MAX_QUEUE_SIZE +
OTEL_BSP_MAX_EXPORT_BATCH_SIZE +
OTEL_EXPORTER_OTLP_ENDPOINT +
⁠OTEL_EXPORTER_OTLP_*_ENDPOINT⁠ +
OTEL_EXPORTER_OTLP_INSECURE -
⁠OTEL_EXPORTER_OTLP_*_INSECURE⁠ -
OTEL_EXPORTER_OTLP_CERTIFICATE +
⁠OTEL_EXPORTER_OTLP_*_CERTIFICATE⁠ +
OTEL_EXPORTER_OTLP_CLIENT_KEY +
⁠OTEL_EXPORTER_OTLP_*_CLIENT_KEY⁠ +
OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE +
⁠OTEL_EXPORTER_OTLP_CLIENT_*_CERTIFICATE⁠ +
OTEL_EXPORTER_OTLP_HEADERS +
⁠OTEL_EXPORTER_OTLP_*_HEADERS⁠ +
OTEL_EXPORTER_OTLP_COMPRESSION +
⁠OTEL_EXPORTER_OTLP_*_COMPRESSION⁠ +
OTEL_EXPORTER_OTLP_PROTOCOL +
⁠OTEL_EXPORTER_OTLP_*_PROTOCOL⁠ +
OTEL_EXPORTER_OTLP_SPAN_INSECURE (obsolete) -
OTEL_EXPORTER_OTLP_METRIC_INSECURE (obsolete) -
OTEL_EXPORTER_ZIPKIN_ENDPOINT -
OTEL_EXPORTER_ZIPKIN_TIMEOUT -
OTEL_EXPORTER_PROMETHEUS_HOST -
OTEL_EXPORTER_PROMETHEUS_PORT -
OTEL_TRACES_EXPORTER +
OTEL_METRICS_EXPORTER +
OTEL_LOGS_EXPORTER +
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT -
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT -
OTEL_SPAN_EVENT_COUNT_LIMIT -
OTEL_SPAN_LINK_COUNT_LIMIT -
OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT -
OTEL_LINK_ATTRIBUTE_COUNT_LIMIT -
OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT -
OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT -
OTEL_TRACES_SAMPLER -
OTEL_TRACES_SAMPLER_ARG -
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT (1) +
OTEL_ATTRIBUTE_COUNT_LIMIT (1) +
OTEL_METRIC_EXPORT_INTERVAL +
OTEL_METRIC_EXPORT_TIMEOUT +
OTEL_METRICS_EXEMPLAR_FILTER -
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE -
OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION -
OTEL_EXPERIMENTAL_CONFIG_FILE -

(1) In otel::as_attributes().

See Also

Environment Variables in otel

Examples

# To start an R session using the OTLP exporter:
# OTEL_TRACES_EXPORTER=http R -q -f script.R

File Size Options

Description

otel and otelsdk accept file size options in the following format:

Value

Not applicable.

Examples

# Maximum output file size is 128 MiB:
# OTEL_EXPORTER_OTLP_FILE_FILE_SIZE=128MiB

Time Interval Options

Description

otel and otelsdk accept time interval options in the following format:

When the time interval is specified in an environment variable, it may be:

Value

Not applicable.

Examples

# Write pending telemetry data to the output file every 5 seconds:
# OTEL_EXPORTER_OTLP_FILE_FLUSH_INTERVAL=5s

Logger provider to write log messages into a JSONL file.

Description

This is the OTLP file exporter. It writes logs to a JSONL file, each log is a line in the file, a valid JSON value. The line separator is ⁠\n⁠. The preferred file extension is jsonl.

Select this tracer provider with OTEL_LOGS_EXPORTER=otlp/file.

Value

logger_provider_file$new() returns an otel::otel_logger_provider object.

logger_provider_file$options() returns a named list, the current values of the options.

Usage

Externally: 

OTEL_LOGS_EXPORTER=otlp/file

From R: 

logger_provider_file$new(opts = NULL)
logger_provider_file$options()

Arguments

Options

File exporter options

Special placeholders are available for file_pattern and alias_pattern:

Examples

logger_provider_file$options()

Logger provider to log over HTTP

Description

This is the OTLP HTTP exporter.

Value

logger_provider_http$new() returns an otel::otel_logger_provider object.

logger_provider_http$options() returns a named list, the current values for all options.

Usage

Externally: 

OTEL_LOGS_EXPORTER=otlp

From R: 

logger_provider_http$new(opts = NULL)
logger_provider_http$options()

Arguments

Options

HTTP exporter options

Batch processor options

Examples

logger_provider_http$options()

Logger provider to write to the standard output or standard error or to a file

Description

Writes logs to the standard output or error, or to a file. Useful for debugging.

Value

logger_provider_stdstream$new() returns an otel::otel_logger_provider object.

logger_provider_stdstream$options() returns a named list, the current values of the options.

Usage

Externally: 

OTEL_LOGS_EXPORTER=console
OTEL_LOGS_EXPORTER=stderr

From R: 

logger_provider_stdstream$new(opts = NULL)
logger_provider_stdstream$options()

Arguments

opts: Named list of options. See below.

Options

Standard stream exporter options

Examples

logger_provider_stdstream$options()

Meter provider to collect metrics in JSONL files

Description

This is the OTLP file exporter. It writes measurements to a JSONL file, each measurement is a line in the file, a valid JSON value. The line separator is ⁠\n⁠. The preferred file extension is jsonl.

Select this tracer provider with OTEL_METRICS_EXPORTER=otlp/file.

Value

meter_provider_file$new() returns an otel::otel_meter_provider object.

meter_provider_file$options() returns a named list, the current values of the options.

Usage

Externally: 

OTEL_METRICS_EXPORTER=otlp/file

From R: 

meter_provider_file$new(opts = NULL)
meter_provider_file$options()

Arguments

Options

File exporter options

Special placeholders are available for file_pattern and alias_pattern:

Metric reader options

Examples

meter_provider_file$options()

Meter provider to send collected metrics over HTTP

Description

This is the OTLP HTTP exporter.

Select this tracer provider with OTEL_METRICS_EXPORTER=otlp.

Value

meter_provider_http$new() returns an otel::otel_meter_provider object.

meter_provider_http$options() returns a named list, the current values for all options.

Usage

Externally: 

OTEL_METRICS_EXPORTER=otlp

From R: 

meter_provider_http$new(opts = NULL)
meter_provider_http$options()

Arguments

Options

HTTP exporter options

Metric reader options

Metric exporter options

Examples

meter_provider_http$options()

In-memory meter provider for testing

Description

Collects metrics measurements in memory. This is useful for testing your instrumented R package or application.

with_otel_record() uses this meter provider. Use with_otel_record() in your tests to record telemetry and check that it is correct.

Value

meter_provider_memory$new() returns an otel::otel_meter_provider object. mp$get_metrics() returns a named list of recorded metrics.

meter_provider_memory$options() returns a named list, the current values for all options.

Usage

mp <- meter_provider_memory$new(opts = NULL)
mp$get_metrics()
meter_provider_memory$options()

mp$get_metrics() erases the internal buffer of the meter provider.

Arguments

Options

Memory exporter options

Metric reader options

Metric exporter options

Examples

meter_provider_memory$options()

Meter provider to write to the standard output or standard error or to a file

Description

Writes metrics measurements to the standard output or error, or to a file. Useful for debugging.

Value

meter_provider_stdstream$new() returns an otel::otel_meter_provider object.

meter_provider_stdstream$options() returns a named list, the current values of the options.

Usage

Externally: 

OTEL_METRICS_EXPORTER=console
OTEL_METRICS_EXPORTER=stderr

From R: 

meter_provider_stdstream$new(opts = NULL)
meter_provider_stdstream$options()

Arguments

opts: Named list of options. See below.

Options

Standard stream exporter options

Metric reader options

Examples

meter_provider_stdstream$options()

Tracer provider to write traces into a JSONL file

Description

This is the OTLP file exporter. It writes spans to a JSONL file, each span is a line in the file, a valid JSON value. The line separator is ⁠\n⁠. The preferred file extension is jsonl.

Select this tracer provider with OTEL_TRACES_EXPORTER=otlp/file.

Value

tracer_provider_file$new() returns an otel::otel_tracer_provider object.

tracer_provider_file$options() returns a named list, the current values of the options.

Usage

Externally: 

OTEL_TRACES_EXPORTER=otlp/file

From R: 

tracer_provider_file$new(opts = NULL)
tracer_provider_file$options()

Arguments

Options

File exporter options

Special placeholders are available for file_pattern and alias_pattern:

Examples

tracer_provider_file$options()

Tracer provider to export traces over HTTP

Description

This is the OTLP HTTP exporter.

Select this tracer provider with OTEL_TRACES_EXPORTER=otlp.

Value

tracer_provider_http$new() returns an otel::otel_tracer_provider object.

tracer_provider_http$options() returns a named list, the current values for all options.

Usage

Externally: 

OTEL_TRACES_EXPORTER=otlp

From R: 

tracer_provider_http$new(opts = NULL)
tracer_provider_http$options()

Arguments

Options

HTTP exporter options

Batch processor options

Examples

tracer_provider_http$options()

In-memory tracer provider for testing

Description

Collects spans in memory. This is useful for testing your instrumented R package or application.

with_otel_record() uses this tracer provider. Use with_otel_record() in your tests to record telemetry and check that it is correct.

Value

tracer_provider_memory$new() returns an otel::otel_tracer_provider object. tp$get_spans() returns a named list of recorded spans, with the span names as names.

tracer_provider_memory$options() returns a named list, the current values for all options.

Usage

tp <- tracer_provider_memory$new(opts = NULL)
tp$get_spans()
tracer_provider_memory$options()

tp$get_spans() erases the internal buffer of the tracer provider.

Arguments

Options

Memory exporter options

Examples

tracer_provider_memory$options()

Tracer provider to write to the standard output or standard error or to a file

Description

Writes spans to the standard output or error, or to a file. Useful for debugging.

Value

tracer_provider_stdstream$new() returns an otel::otel_tracer_provider object.

tracer_provider_stdstream$options() returns a named list, the current values of the options.

Usage

Externally: 

OTEL_TRACES_EXPORTER=console
OTEL_TRACES_EXPORTER=stderr

From R: 

tracer_provider_stdstream$new(opts = NULL)
tracer_provider_stdstream$options()

Arguments

opts: Named list of options. See below.

Options

Standard stream exporter options

Examples

tracer_provider_stdstream$options()

Record OpenTelemetry output, for testing purposes

Description

You can use this function to test that OpenTelemetry output is correctly generated for your package or application.

Usage

with_otel_record(
  expr,
  what = c("traces", "metrics"),
  tracer_opts = list(),
  meter_opts = list()
)

Arguments

expr

Expression to evaluate.

what

Character vector, type(s) of OpenTelemetry output to collect.

tracer_opts

Named list of options to pass to the tracer provider.

meter_opts

Named list of options to pass to the meter provider.

Details

It evaluates the supplied expression, collects OpenTelemetry output from it and returns it.

Note: with_otel_record() cannot record logs yet.

with_otel_record() uses tracer_provider_memory and meter_provider_memory internally.

Value

A list with the output for each output type. Entries:

Examples

spns <- with_otel_record({
  trc <- otel::get_tracer("mytracer")
  spn1 <- trc$start_local_active_span()
  spn2 <- trc$start_local_active_span("my")
  spn2$end()
  spn1$end()
  NULL
})
spns