feat: support new metrics firehose api with get_usage() (#404)

Co-authored-by: Neal Richardson <neal.p.richardson@gmail.com>

Author: toph-allen

.lintr

@@ -1,7 +1,7 @@
 linters: linters_with_defaults(
   line_length_linter = line_length_linter(120L),
   object_name_linter = object_name_linter(styles = c("snake_case", "symbols", "CamelCase")),
-  cyclocomp_linter = cyclocomp_linter(30L),
+  cyclocomp_linter = NULL, # Issues with R6 classes.
   object_length_linter(32L),
   indentation_linter = indentation_linter(hanging_indent_style = "tidy"),
   return_linter = NULL

DESCRIPTION

@@ -57,6 +57,7 @@ Suggests:
     rsconnect,
     spelling,
     testthat,
+    tidyr,
     webshot2,
     withr
 VignetteBuilder:

NAMESPACE

@@ -5,7 +5,9 @@ S3method("[",connect_tag_tree)
 S3method("[[",connect_tag_tree)
 S3method(api_build,op_base_connect)
 S3method(api_build,op_head)
+S3method(as.data.frame,connect_list_hits)
 S3method(as.data.frame,tbl_connect)
+S3method(as_tibble,connect_list_hits)
 S3method(connect_vars,op_base)
 S3method(connect_vars,op_single)
 S3method(connect_vars,tbl_connect)
@@ -97,6 +99,7 @@ export(get_tag_data)
 export(get_tags)
 export(get_thumbnail)
 export(get_timezones)
+export(get_usage)
 export(get_usage_shiny)
 export(get_usage_static)
 export(get_user_permission)
@@ -159,6 +162,7 @@ importFrom(rlang,"%||%")
 importFrom(rlang,":=")
 importFrom(rlang,arg_match)
 importFrom(rlang,is_string)
+importFrom(tibble,as_tibble)
 importFrom(utils,browseURL)
 importFrom(utils,capture.output)
 importFrom(utils,compareVersion)

NEWS.md

@@ -1,5 +1,10 @@
 # connectapi (development version)
 
+## New features
+
+- New `get_usage()` function returns content usage data from Connect's `GET
+  v1/instrumentation/content/hits` endpoint on Connect v2025.04.0 and higher.
+  (#390)
 
 ## Enhancements and fixes
 

R/connect.R

@@ -858,7 +858,9 @@ Connect <- R6::R6Class(
     docs = function(docs = "api", browse = TRUE) {
       stopifnot(docs %in% c("admin", "user", "api"))
       url <- paste0(self$server, "/__docs__/", docs)
-      if (browse) utils::browseURL(url)
+      if (browse) {
+        utils::browseURL(url)
+      }
       url
     },
 

R/get.R

@@ -526,6 +526,157 @@ get_usage_static <- function(
   return(out)
 }
 
+#' Get usage information for deployed content
+#'
+#' @description
+#' Retrieve content hits for all available content on the server. Available
+#' content depends on the user whose API key is in use. Administrator accounts
+#' will receive data for all content on the server. Publishers will receive data
+#' for all content they own or collaborate on.
+#'
+#' If no date-times are provided, all usage data will be returned.
+#'
+#' @param client A `Connect` R6 client object.
+#' @param from Optional date-time (`POSIXct` or `POSIXlt`). Only
+#'   records after this time are returned. If not provided, records
+#'   are returned back to the first record available.
+#' @param to Optional date-time (`POSIXct` or `POSIXlt`). Only records
+#'   before this time are returned. If not provided, all records up to
+#'   the most recent are returned.
+#'
+#' @return A list of usage records. Each record is a list with all elements
+#'   as character strings unless otherwise specified.
+#'
+#' * `id`: An integer identifier for the hit.
+#' * `user_guid`: The user GUID if the visitor is logged-in, `NULL` for
+#'   anonymous hits.
+#' * `content_guid`: The GUID of the visited content.
+#' * `timestamp`: The time of the hit in RFC3339 format.
+#' * `data`: A nested list with optional fields:
+#'     * `path`: The request path (if recorded).
+#'     * `user_agent`: The user agent string (if available).
+#'
+#' Use [as.data.frame()] or [tibble::as_tibble()] to convert to a flat
+#' table with parsed types. In the resulting data frame:
+#'
+#' * `timestamp` is parsed to `POSIXct`.
+#' * `path` and `user_agent` are extracted from the nested `data` field.
+#'
+#' By default, [as.data.frame()] attempts to extract the nested fields using
+#' the \pkg{tidyr} package. If \pkg{tidyr} is not available, or if you want to
+#' skip unnesting, call `as.data.frame(x, unnest = FALSE)` to leave `data` as
+#' a list-column.
+#'
+#' @details
+#'
+#' The data returned by `get_usage()` includes all content types. For Shiny
+#' content, the `timestamp` indicates the *start* of the Shiny session.
+#' Additional fields for Shiny and non-Shiny are available respectively from
+#' [get_usage_shiny()] and [get_usage_static()]. `get_usage_shiny()` includes a
+#' field for the session end time; `get_usage_static()` includes variant,
+#' rendering, and bundle identifiers for the visited content.
+#'
+#' When possible, however, we recommend using `get_usage()` over
+#' `get_usage_static()` or `get_usage_shiny()`, as it is faster and more efficient.
+#'
+#' @seealso [as.data.frame.connect_list_hits()], [as_tibble.connect_list_hits()]
+#'
+#' @examples
+#' \dontrun{
+#' client <- connect()
+#'
+#' # Fetch the last 2 days of hits
+#' usage <- get_usage(client, from = Sys.Date() - 2, to = Sys.Date())
+#'
+#' # Fetch usage after a specified date and convert to a data frame.
+#' usage <- get_usage(
+#'   client,
+#'   from = as.POSIXct("2025-05-02 12:40:00", tz = "UTC")
+#' )
+#'
+#' # Fetch all usage
+#' usage <- get_usage(client)
+#'
+#' # Convert to tibble or data frame
+#' usage_df <- tibble::as_tibble(usage)
+#'
+#' # Skip unnesting if tidyr is not installed
+#' usage_df <- as.data.frame(usage, unnest = FALSE)
+#' }
+#'
+#' @export
+get_usage <- function(client, from = NULL, to = NULL) {
+  error_if_less_than(client$version, "2025.04.0")
+
+  usage <- client$GET(
+    v1_url("instrumentation", "content", "hits"),
+    query = list(
+      from = make_timestamp(from),
+      to = make_timestamp(to)
+    )
+  )
+
+  class(usage) <- c("connect_list_hits", class(usage))
+  usage
+}
+
+#' Convert usage data to a data frame
+#'
+#' @description
+#' Converts an object returned by [get_usage()] into a data frame with parsed
+#' column types. By default, extracts `path` and `user_agent` from the `data`
+#' field, if available.
+#'
+#' @param x A `connect_list_hits` object (from [get_usage()]).
+#' @param row.names Passed to [base::as.data.frame()].
+#' @param optional Passed to [base::as.data.frame()].
+#' @param ... Passed to [base::as.data.frame()].
+#' @param unnest Logical; if `TRUE` (default), extracts nested fields using
+#'   \pkg{tidyr}. Set to `FALSE` to skip unnesting.
+#'
+#' @return A `data.frame` with one row per usage record.
+#' @export
+#' @method as.data.frame connect_list_hits
+as.data.frame.connect_list_hits <- function(
+  x,
+  row.names = NULL, # nolint
+  optional = FALSE,
+  ...,
+  unnest = TRUE
+) {
+  usage_df <- parse_connectapi_typed(x, connectapi_ptypes$usage)
+  if (unnest) {
+    if (!requireNamespace("tidyr", quietly = TRUE)) {
+      stop(
+        "`unnest = TRUE` requires tidyr. Install tidyr or set `unnest = FALSE`.",
+        call. = FALSE
+      )
+    }
+    usage_df <- tidyr::unnest_wider(
+      usage_df,
+      "data",
+      ptype = list(path = character(0), user_agent = character(0))
+    )
+  }
+  as.data.frame(usage_df, row.names = row.names, optional = optional, ...)
+}
+
+#' Convert usage data to a tibble
+#'
+#' @description
+#' Converts an object returned by [get_usage()] to a tibble via
+#' [as.data.frame.connect_list_hits()].
+#'
+#' @param x A `connect_list_hits` object.
+#' @param ... Passed to [as.data.frame()].
+#'
+#' @return A tibble with one row per usage record.
+#' @export
+#' @importFrom tibble as_tibble
+#' @method as_tibble connect_list_hits
+as_tibble.connect_list_hits <- function(x, ...) {
+  tibble::as_tibble(as.data.frame(x, ...))
+}
 
 #' Get Audit Logs from Posit Connect Server
 #'

R/parse.R

@@ -58,15 +58,19 @@ ensure_column <- function(data, default, name) {
       # manual fix because vctrs::vec_cast cannot cast double -> datetime or char -> datetime
       col <- coerce_datetime(col, default, name = name)
     }
+
     if (inherits(default, "fs_bytes") && !inherits(col, "fs_bytes")) {
       col <- coerce_fsbytes(col, default)
     }
+
     if (inherits(default, "integer64") && !inherits(col, "integer64")) {
       col <- bit64::as.integer64(col)
     }
+
     if (inherits(default, "list") && !inherits(col, "list")) {
       col <- list(col)
     }
+
     col <- vctrs::vec_cast(col, default, x_arg = name)
   }
   data[[name]] <- col
@@ -101,6 +105,7 @@ parse_connectapi <- function(data) {
   ))
 }
 
+
 coerce_fsbytes <- function(x, to, ...) {
   if (is.numeric(x)) {
     fs::as_fs_bytes(x)

R/ptype.R

@@ -1,5 +1,5 @@
 NA_datetime_ <- # nolint: object_name_linter
-  vctrs::new_datetime(NA_real_, tzone = "UTC")
+  vctrs::new_datetime(NA_real_, tzone = Sys.timezone())
 NA_list_ <- # nolint: object_name_linter
   list(list())
 
@@ -38,6 +38,13 @@ connectapi_ptypes <- list(
     "bundle_id" = NA_character_,
     "data_version" = NA_integer_
   ),
+  usage = tibble::tibble(
+    "id" = NA_integer_,
+    "user_guid" = NA_character_,
+    "content_guid" = NA_character_,
+    "timestamp" = NA_datetime_,
+    "data" = NA_list_
+  ),
   content = tibble::tibble(
     "guid" = NA_character_,
     "name" = NA_character_,

_pkgdown.yml

@@ -67,6 +67,8 @@ reference:
       Helpers to "get" data out of Connect
     contents:
       - starts_with("get")
+      - as.data.frame.connect_list_hits
+      - as_tibble.connect_list_hits
 
   - title: "Other"
     desc: >