Add basic Open Telemetry instrumentation for all requests.

This commit wraps all requests in an Open Telemetry span that abides by
the semantic conventions for HTTP clients [0] (insofar as I understand
them).

Right now this instrumentation is opt in: `otel` is in `Suggests`, and
tracing must be enabled (e.g. via the `OTEL_TRACES_EXPORTER` environment
variable). Otherwise this is costless at runtime.

For example:

    library(otelsdk)

    Sys.setenv(OTEL_TRACES_EXPORTER = "stderr")

    request("https://google.com") |>
      req_perform()

I'm not sure that `otel` needs to move to `Imports`, because by design
users actually need the `otelsdk` package to enable tracing anyway.

The major limitation right now is that we don't propagate the trace
context to the server [1], because `otel` doesn't have an explicit
mechanism for this yet.

[0]: https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client-span
[1]: https://www.w3.org/TR/trace-context/

Signed-off-by: Aaron Jacobs <[email protected]>

Author: atheriel

DESCRIPTION

@@ -39,6 +39,7 @@ Suggests:
     knitr,
     later (>= 1.4.0),
     nanonext,
+    otel (>= 0.0.0.9000),
     paws.common,
     promises,
     rmarkdown,
@@ -56,4 +57,5 @@ Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
 Remotes:  
-    r-lib/webfakes
+    r-lib/webfakes,
+    r-lib/otel

NEWS.md

@@ -1,6 +1,7 @@
 # httr2 (development version)
 
 * `req_url_query()` now re-calculates n lengths when using `.multi = "explode"` to avoid select/recycling issues (@Kevanness, #719).
+* httr2 will now emit OpenTelemetry traces for all requests when tracing is enabled. Requires the `otelsdk` package (@atheriel, #729).
 
 # httr2 1.1.2
 

R/req-perform-connection.R

@@ -71,7 +71,11 @@ req_perform_connection <- function(req, blocking = TRUE, verbosity = NULL) {
     if (!is.null(resp)) {
       close(resp)
     }
+    span <- start_span(req, tries)
     resp <- req_perform_connection1(req, handle, blocking = blocking)
+    # Note: this is a bit misleading. We might not want to end the span until
+    # the response has been read to completion.
+    end_span(span, req, resp)
 
     if (retry_is_transient(req, resp)) {
       tries <- tries + 1

R/req-perform.R

@@ -110,8 +110,11 @@ req_perform <- function(
     sys_sleep(delay, "for retry backoff")
     n <- n + 1
 
+    # TODO: This does not yet handle trace context propagation.
+    span <- start_span(req, tries)
     resp <- req_perform1(req, path = path, handle = handle)
     req_completed(req_prep)
+    end_span(span, req, resp)
 
     if (retry_is_transient(req, resp)) {
       tries <- tries + 1
@@ -280,3 +283,67 @@ is_path <- function(x) inherits(x, "httr2_path")
 resp_show_body <- function(resp) {
   resp$request$policies$show_body %||% FALSE
 }
+
+# Starts an Open Telemetry span that abides by the semantic conventions for
+# HTTP clients.
+#
+# See: https://opentelemetry.io/docs/specs/semconv/http/http-spans/#http-client-span
+start_span <- function(req, tries, tracer = NULL, scope = parent.frame()) {
+  if (!is_installed("otel")) {
+    return(NULL)
+  }
+  tracer <- tracer %||% otel::get_tracer("httr2")
+  if (!tracer$is_enabled()) {
+    # Return a no-op span when tracing is disabled.
+    return(tracer$start_span())
+  }
+  method <- req$method %||% "GET"
+  parsed <- url_parse(req$url)
+  default_port <- 443L
+  if (parsed$scheme == "http") {
+    default_port <- 80L
+  }
+  # Follow the semantic conventions and redact credentials in the URL, when
+  # present.
+  if (!is.null(parsed$username)) {
+    parsed$username <- "REDACTED"
+  }
+  if (!is.null(parsed$password)) {
+    parsed$password <- "REDACTED"
+  }
+  tracer$start_span(
+    name = method,
+    options = list(kind = "CLIENT"),
+    # Ensure we set attributes relevant to sampling at span creation time.
+    attributes = compact(list(
+      "http.request.method" = method,
+      "server.address" = parsed$hostname,
+      "server.port" = parsed$port %||% default_port,
+      "url.full" = url_build(parsed),
+      "http.request.resend_count" = if (tries > 1) tries
+    )),
+    scope = scope
+  )
+}
+
+end_span <- function(span, req, resp) {
+  if (is.null(span) || !span$is_recording()) {
+    return(invisible(span))
+  }
+  if (is_error(resp)) {
+    span$set_status("error")
+    # Surface the underlying curl error class.
+    span$set_attribute("error.type", class(resp$parent)[1])
+    return(span$end())
+  }
+  span$set_attribute("http.response.status_code", resp_status(resp))
+  if (error_is_error(req, resp)) {
+    span$set_status("error", resp_status_desc(resp))
+    # The semantic conventions recommend using the status code as a string for
+    # these cases.
+    span$set_attribute("error.type", as.character(resp_status(resp)))
+  } else {
+    span$set_status("ok")
+  }
+  span$end()
+}