appsilon / shiny.telemetry

Easy logging of users activity and session events of your Shiny App

shiny.telemetry

Easy logging of users activity and session events of your Shiny App

The shiny.telemetry R package tracks events occurring on a user session, such as input changes and session duration, and stores them in a local or remote database.

It provides developers with the tools to help understand how users interact with Shiny dashboards and answer questions such as: which tabs/pages are more often visited, which inputs users are changing, what is the average length of a session, etc.

Install

The shiny.telemetry package can be installed from GitHub by using the remotes package:

remotes::install_github("Appsilon/shiny.telemetry", dependencies = TRUE)

With dependencies = TRUE the suggested packages (required to run some examples) will be installed in addition to mandatory dependencies.

How to use in a Shiny Dashboard?

shiny.telemetry allows for a minimal setup with only 3 commands that can track some information about the session:

• When session starts and ends
• The browser version used by the client
• Changes in the inputs (doesn't track values by default)

The code below runs a minimal example of a Shiny application that uses shiny.telemetry. The package will keep track of the session information and all changes to the numericInput.

Note: When using the dashboard nothing is happening from the user's perspective as all operation run in the background (either in the server or in Javascript).

library(shiny)
library(shiny.telemetry)

telemetry <- Telemetry$new() # 1. Initialize telemetry with default options

shinyApp(
  ui = fluidPage(
    use_telemetry(), # 2. Add necessary Javascript to Shiny
    numericInput("n", "n", 1),
    plotOutput('plot')
  ),
  server = function(input, output) {
    telemetry$start_session() # 3. Minimal setup to track events
    output$plot <- renderPlot({ hist(runif(input$n)) })
  }
)

When inspecting the code above, we can breakdown the 3 lines of code by:

1. Global Telemetry object that is used across the different sessions
2. Add necessary Javascript to the UI by calling use_telemetry(). It is used to track browser version.
3. Initialize the session-specific tracking by calling method start_session() of the Telemetry object.

How to access the data?

The developers and administrators of the dashboard can access the data that is gathered by shiny.telemetry via a Telemetry object or directly from DataStorage via the appropriate provider.

# After running the instrumented app
shiny.telemetry::Telemetry$new()$data_storage$read_event_data("2020-01-01", "2050-01-01")

# Default provider and path for Telemetry$new()
shiny.telemetry::DataStorageSQLite$new(db_path = "telemetry.sqlite")$read_event_data("2020-01-01", "2050-01-01")

The package includes an analytics dashboard to view the data. It is located at inst/examples/app/analytics and it should be modified so that it references the correct DataStorage provider and configuration.

Data providers

There are 3 different types of data providers that can range from local filesystem storage to a remote Plumber REST API instance.

• Local file:
  • SQLite using DataStorageSQLite class
  • Logfile using DataStorageLogFile class
• Remote SQL database:
  • MariaDB using DataStorageMariaDB class
  • PostgreSQL using DataStoragePostgreSQL class
  • MS SQL Server using DataStorageMSSQLServer class
• Plumber REST API using DataStoragePlumber class
  • In turn, the Plumber data provider will use one of the other classes above as the method of data storage.

The setup for plumber requires a valid Plumber instance running on the network and the communication can be protected. See Plumber deployment documentation for more information.

Debugging the Telemetry calls

The package uses the logger package internally with the shiny.telemetry namespace. To debug the shiny.telemetry calls in the dashboard, change the threshold of this namespace to DEBUG:

logger::log_threshold("DEBUG", namespace = "shiny.telemetry")

note: This command can be run before the Shiny call or by adding it to the .Rprofile.

Contributing

See CONTRIBUTING.

Appsilon

Appsilon is a Posit (formerly RStudio) Full Service Certified Partner.
Learn more at appsilon.com.

Get in touch [email protected]

Explore the Rhinoverse - a family of R packages built around Rhino!

shiny.telemetry's Issues

Organize a workshop with Ania

Move dashboard dependencies to suggest section

For tracking (the main functionality) we just need a few deps.

Show navigation events in the analytics app

Ability to setup basic telemetry with a single call

A single call in the UI and server should make it possible to track:

1. Logins and logouts.
2. Browser info.
3. All interactions with inputs (without logging the value).

Ability to track time spent in modals, tabs, etc.

1. Ask Ania/Kuba about the exact technical solution used for tabs.
2. Extend our test app and use it to prototype.

Deploy the test app using git-backed content

remove deprecated dependecies

eg. there's some shiny.admin relationships

PoC: plumber API to store and retrieve data

Ability to track JS events

Expand the test app to clarify.

Optimize element sizing so the analytics dashboard is readable

Currently, analytics dashboard does not seem to have a good layout because it lacks some styling. This task should only require editing the CSS (no changes to the logic).

Review and improve documentation

PoC: Create data API abstraction layer

• R6 class to manage the data calls
• Implement current db drivers

Use a single DB table

Update our storage schema as outlined in Telemetry Storage - Design Doc (Appsilon-internal).

Add option to avoid tracking value in inputs

Tracking only changes events and keep id (not the value itself)

Deploy the analytics app

Unify db connect methods for register and dashboard parts

For registering, only open connection is enough. For dashboard you need to specify config.

Instrument a selected demo app using the current API

/A few "easy" options to start with:

1. Few elements
   • drug-drug-interaction (experimental-shiny.telemetry branch)
   • entreprise dashboard
2. Map only (Olympic) (experimental-shiny.telemetry branch)
3. Tab (VisualizeRisk)

Write a design doc for storage schema

Link: Telemetry Storage - Design Doc (Appsilon-internal).

Make stats dashboard robust for nonexistent data

This should cover:

• no data at all in last month
• lack of specific actions (clicks, inputs, etc)

Retrieve username from session

Research competitors

Research what other tools are there for gathering telemetry. Some initial ideas:

1. Google Tag Manager
2. Adobe DTM
3. Teallium
4. Yahoo Tag Manager
5. Matomo (OSS)
6. heap.io
7. Hotjar
8. shinylogs (R package)

Relevant articles (Appsilon internal):

1. Tools For Monitoring User Adoption
2. User Adoption Monitoring

Organize a workshop to discuss instrumentation API

Conducted in three parts. Notes (Appsilon-internal): link.

log click doesn't have observe included

Refink current approach

Sprint 1 (2023-03-20 ⟶ 03-27)

Goal

1. Data storage backend API defined & a couple options prototyped.
2. Demo app instrumented.

Done

1. #21
2. #20
3. #27
4. #22

In progress:

1. #24 (2 of 3 selected apps instrumented)
2. #26 (PR ready)
3. #25 (PoC ready)

User specific stats: top panel errors

Maybe it's related to #3 but in User specific stats I get:

Column `new_users` must be length 14 (the group size) or one, not 38

Create a hex logo

Stats Panel dependencies

Dependencies for the analytics panels are all in Suggests (plotly, semantic.dashboard, ...)

Does it need to change and moved to Imports?

Generalize DB methods

Currently only SQLite and PostgreSQL are available

Sprint 3 (2023-04-03 ⟶ 04-10)

Goal

As it was just @averissimo and @kamilzyla in this Sprint, we decided to proceed without formal Sprint Goal and focus on:

1. Closing outstanding tasks.
2. Refining the DB schema.
3. Tracking navigation events.

Done

1. #50
2. #41
3. #39
4. #45

In progress:

1. #43
2. #65

Done in earlier PRs:

1. #48
2. #31

Stats dashboard should be modularized

Test out current functionality

Log browser should be added to session details not user log

Input tracking improvement

Ideas:

• track all inputs
• add regex as inclusion/exclusion criteria for tracking
• integrate namespace inclusion/exclusion criteria

Discussion

• from a conversion in a PR that was not in the scope (see

I am really confused at first what is the purpose of matching_values, but I guess this will be useful in select inputs, e.g. when one of the option is "", then we only want to observe values inside matching_values. This makes me think if it is also worthwhile to have another argument, e.g. unmatch = FALSE, when users have a lot of select inputs, so they only list the one they do not want to match in matching_values and then log the rest of input values.

Take measures against SQL injection

Make sure we protect the application against SQL injection by a malicious actor manipulating the input values

Change SQL code queries to use sqlInterpolate()

https://shiny.rstudio.com/articles/sql-injections.html

Prepare materials for release promotion

Goal

Bullet points or rough notes (will be edited by the Marketing Team) for a short announcement of a CRAN release (to be posted on Twitter / LinkedIn):

1. What can the package do for you?
2. Perhaps: a minimal example.
3. How to learn more?

Inspiration

(Appsilon-internal) See some past bullet points for inspiration:

1. Software engineering skills that Shiny Developers should know & how Rhino incorporates them
2. Cypress vs shinytest2
3. shiny.react & shiny.fluent feature overview

The end result can be a Twitter post like one of these:

1. shiny.router 0.3.0
2. Rhino 1.2

Launch the analytics app with a single function

1. Move the telemetry app to a separate directory.
2. Don't export the functions used internally by the telemetry app,
3. and instead have just a single exported function, e.g. analyticsApp().

PoC: Log file backend to store and retrieve data

move sqlite out of data storage file

allow reading for empty log files

Track "dashboard name" and "version"

Needed if we plan a feature that tracks multiple dashboards in a central storage solution

For example, a client that has 4 dashboards and doesn't want 4 different analytics dashboards

Chore: Clean up connectivity tools

• Remove unnecessary functions in R/connectivity-tools.R
• Most functions in this script are already covered by the DataStorage classes.

Sprint 2 (2023-03-27 ⟶ 04-03)

Goal

The whole package is tested in deployment (instrumented app, data storage backend, analytics app). The instrumentation API is convenient for the users.

Done

1. #16
2. #29
3. #24
4. #55
5. #53
6. #52
7. #40
8. #25
9. #26
10. #42

In progress:

1. #39
2. #45
3. #50
4. #41

[Feature]: Use pool for database requests.

Guidelines

• I agree to follow this project's Contributing Guidelines.

Description

We should use db connection pooling to improve the stability of this package.

Problem

Potential connection leaking, or an issue with connection may halt the application.

Proposed Solution

https://shiny.rstudio.com/articles/pool-basics.html

Alternatives Considered

No alternatives considered.

Deploy plumber API with log storage

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Pending Approval

These branches will be created by Renovate only once you click their checkbox below.

• chore(deps): update actions/cache action to v4
• chore(deps): update actions/checkout action to v4
• 🔐 Create all pending approval PRs at once 🔐

Detected dependencies

github-actions

.github/workflows/check_with_databases.yml

• actions/checkout v3
• r-lib/actions v2
• r-lib/actions v2
• r-lib/actions v2

.github/workflows/main.yml

• actions/checkout v3
• r-lib/actions v2
• r-lib/actions v2
• r-lib/actions v2

.github/workflows/pkgdown.yml

• actions/checkout v3
• r-lib/actions v2
• r-lib/actions v2
• r-lib/actions v2

.github/workflows/prepare_connect.yml

• actions/checkout v3
• r-lib/actions v2
• actions/cache v3

---

• Check this box to trigger a request for Renovate to run again on this repository

Add disconnect parameter to log_logout

Add runnable example in code

... not only in readme

Use LGPL-3 license

Remove shiny.admin from documentation

Remove obsolete DB code

Remove dead code:

• connectivity-tools.R (move parse_val)
• constants.R
• managing-users.R