Document tracer name selection

R/otel-package.R

@@ -0,0 +1,34 @@
+#' @keywords internal
+"_PACKAGE"
+
+## usethis namespace: start
+## usethis namespace: end
+NULL
+
+#' Default tracer, meter, logger name for an R package
+#'
+#' The otel R package uses the `otel_tracer_name` variable from your
+#' package when it deducts the tracer (and meter and logger) name to use
+#' if [start_span()] (etc.) is called from your package.
+#'
+#' We suggest that you set this internal variable in your package to avoid
+#' having to specify the tracer name for every [start_span()] call.
+#'
+#' The [OpenTelemetry specification](
+#'   https://opentelemetry.io/docs/specs/otel/trace/api/#get-a-tracer
+#' ) 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`, then otel will use
+#'   `r.package.<package-name>` as the tracer name.
+#'
+#' @name otel_tracer_name
+NULL

README.Rmd

@@ -27,11 +27,18 @@ knitr::opts_chunk$set(
 [![Codecov test coverage](https://codecov.io/gh/r-lib/otel/graph/badge.svg)](https://app.codecov.io/gh/r-lib/otel)
 <!-- badges: end -->
 
-High-quality, ubiquitous, and portable telemetry to enable effective observability. [OpenTelemetry](https://opentelemetry.io/docs/) 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.
+High-quality, ubiquitous, and portable telemetry to enable effective
+observability. [OpenTelemetry](https://opentelemetry.io/docs/) 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.
 
-Use this package as a dependency if you want to instrument your R package or project for OpenTelemetry.
+Use this package as a dependency if you want to instrument your R package
+or project for OpenTelemetry.
 
-Use the [otelsdk](https://github.com/r-lib/otelsdk) to produce OpenTelemetry output from an R package or project that was instrumented with the otel package.
+Use the [otelsdk](https://github.com/r-lib/otelsdk) to produce
+OpenTelemetry output from an R package or project that was instrumented
+with the otel package.
 
 ## Installation
 
@@ -40,7 +47,8 @@ Use the [otelsdk](https://github.com/r-lib/otelsdk) to produce OpenTelemetry out
 > It probably works best with the latest commit of the
 > [otelsdk](https://github.com/r-lib/otelsdk) package.
 
-You can install the development version of otel from [GitHub](https://github.com/) with:
+You can install the development version of otel from
+[GitHub](https://github.com/) with:
 
 ``` r
 # install.packages("pak")
@@ -49,28 +57,51 @@ pak::pak("r-lib/otel")
 
 ## Usage
 
-* Call `otel::start_span()` to create a span. By default the span ends when the called function returns.
-* Use the `$set_attribute()`, `$add_event()`, `$add_link()` and `$set_status()` methods of a span to manipulate it.
-* See the [otelsdk](https://github.com/r-lib/otelsdk) package for producing output from an instrumented R package or project.
+* If you are instrumenting a package, set the internal `otel_tracer_name`
+  variable to your preferred tracer (and logger, meter) name.
+  See `?otel_tracer_name` for details.
+* Call `otel::start_span()` to create a span. By default the span ends when
+  the function that called it terminates.
+* Use the `$set_attribute()`, `$add_event()`, `$add_link()` and
+  `$set_status()` methods of a span to manipulate it.
+* See the [otelsdk](https://github.com/r-lib/otelsdk) package for producing
+  telemetry data from an instrumented R package or project.
 
 ## Zero-code instrumentation
 
-otel supports zero-code instrumentation 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.
-
-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.
+otel supports zero-code instrumentation 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.
+
+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.
 
 ## Production and development sessions
 
-Bye default otel and otelsdk run in production mode. In production mode otel (and otelsdk) functions never error. This behavior does not help catching errors early during the developent of the instrumented project. Set the `OTEL_ENV` environment variable to `dev` to switch to development mode, where otel and otelsdk functions fail on errors.
+Bye default otel and otelsdk run in production mode. In production mode
+otel (and otelsdk) functions never error. This behavior does not help
+catching errors early during the developent of the instrumented project.
+Set the `OTEL_ENV` environment variable to `dev` to switch to development
+mode, where otel and otelsdk functions fail on errors.
 
 ## Concurrency
 
-To support concurrency on a single thread, e.g. a Shiny app serving multiple
-requests at the same time, you can manage the lifetime and actication of the
-OpenTelemetry spans manually. We recommend the following practices for
-in-process concurrency:
+To support concurrency on a single thread, e.g. a Shiny app serving
+multiple requests at the same time, you can manage the lifetime and
+actication of the OpenTelemetry spans manually. We recommend the following
+practices for in-process concurrency:
 
 * Create a new long lasting span with `otel::start_span(scope = NULL)`.
 * Assign the returned span into the corresponding object of the concurrent
@@ -92,8 +123,11 @@ in-process concurrency:
 otel has convenience functions to tie otel sessions to Shiny sessions:
 
 * Use `start_shiny_app()` from the `global.R` file, before the app start up.
-* Use `start_shiny_session()` from the server function, at the start of a new session, and pass the Shiny session object to it.
-* Pass the OpenTelemetry session span to all `otel::start_span()` calls from reactive expressions, to make sure that they are logged to the correct session.
+* Use `start_shiny_session()` from the server function, at the start of a
+  new session, and pass the Shiny session object to it.
+* Pass the OpenTelemetry session span to all `otel::start_span()` calls
+  from reactive expressions, to make sure that they are logged to the
+  correct session.
 
 See the examples included in the otel package.
 

README.md

@@ -45,12 +45,15 @@ pak::pak("r-lib/otel")
 
 ## Usage
 
+- If you are instrumenting a package, set the internal
+  `otel_tracer_name` variable to your preferred tracer (and logger,
+  meter) name. See `?otel_tracer_name` for details.
 - Call `otel::start_span()` to create a span. By default the span ends
-  when the called function returns.
+  when the function that called it terminates.
 - Use the `$set_attribute()`, `$add_event()`, `$add_link()` and
   `$set_status()` methods of a span to manipulate it.
 - See the [otelsdk](https://github.com/r-lib/otelsdk) package for
-  producing output from an instrumented R package or project.
+  producing telemetry data from an instrumented R package or project.
 
 ## Zero-code instrumentation