Telemetry: Telemetry class to manage analytics gathering at a global...
In Appsilon/shiny.stats: 'Shiny' App Usage Telemetry
Telemetry R Documentation
Telemetry class to manage analytics gathering at a global level
Description
An instance of this class will define metadata and data storage provider
for gathering telemetry analytics of a Shiny dashboard.
The name and version parameters will describe the dashboard name and
version to track using analytics, allowing to store the analytics data from
multiple dashboards in the same data storage provider. As well as
discriminate different versions of the dashboard.
The default data storage provider uses a local SQLite database, but this
can be customizable when instantiating the class, by using another one of
the supported providers (see DataStorage).
Debugging
Events are logged at the DEBUG level using the logger package.
To see the logs, you can set:
logger::log_threshold("DEBUG", namespace = "shiny.telemetry")
Active bindings
data_storageinstance of a class that inherits from
DataStorage. See the documentation on that class for more information.
app_namestring with name of dashboard
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Method new()
Constructor that initializes Telemetry instance with parameters.
Usage
Telemetry$new(
app_name = "(dashboard)",
data_storage = DataStorageSQLite$new(db_path = file.path("telemetry.sqlite"))
)
Arguments
app_name(optional) string that identifies the name of the dashboard.
By default it will store data with (dashboard).
data_storage(optional) DataStorage instance where telemetry
data is being stored.
It can take any of data storage providers by this package,
By default it will store in a SQLite local database in the current
working directory with filename telemetry.sqlite
version(optional) string that identifies the version of the
dashboard. By default it will use v0.0.0.
Method start_session()
Setup basic telemetry
Usage
Telemetry$start_session(
track_inputs = TRUE,
track_values = FALSE,
login = TRUE,
logout = TRUE,
browser_version = TRUE,
navigation_input_id = NULL,
session = shiny::getDefaultReactiveDomain(),
username = NULL,
track_anonymous_user = TRUE,
track_errors = TRUE
)
Arguments
track_inputsflag that indicates if the basic telemetry should
track the inputs that change value. TRUE by default
track_valuesflag that indicates if the basic telemetry should
track the values of the inputs that are changing. FALSE by default.
This parameter is ignored if track_inputs is FALSE
loginflag that indicates if the basic telemetry should
track when a session starts. TRUE by default.
logoutflag that indicates if the basic telemetry should
track when the session ends. TRUE by default.
browser_versionflag that indicates that the browser version
should be tracked.TRUE by default.
navigation_input_idstring or vector of strings that represent
input ids and which value should be tracked as navigation events. i.e.
a change in the value represent a navigation to a page or tab.
By default, no navigation is tracked.
sessionShinySession object or NULL to identify the current
Shiny session.
usernameCharacter with username. If set, it will overwrite username
from session object.
track_anonymous_userflag that indicates to track anonymous user.
A cookie is used to track same user without login over multiple sessions,
This is only activated if none of the automatic methods produce a username
and when a username is not explicitly defined.TRUE by default.
track_errorsflag that indicates if the basic telemetry should
track the errors. TRUE by default. if using shiny version < 1.8.1,
it can auto log errors only in UI output functions.
By using latest versions of shiny, it can auto log all types of errors.
Returns
Nothing. This method is called for side effects.
Method log_navigation()
Log an input change as a navigation event
Usage
Telemetry$log_navigation(input_id, session = shiny::getDefaultReactiveDomain())
Arguments
input_idstring that identifies the generic input in the Shiny
application so that the function can track and log changes to it.
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_navigation_manual()
Log a navigation event manually by indicating the id (as input id)
Usage
Telemetry$log_navigation_manual(
navigation_id,
value,
session = shiny::getDefaultReactiveDomain()
)
Arguments
navigation_idstring that identifies navigation event.
valuestring that indicates a value for the navigation
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_login()
Log when session starts
Usage
Telemetry$log_login(
username = NULL,
session = shiny::getDefaultReactiveDomain()
)
Arguments
usernamestring with username from current session
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_logout()
Log when session ends
Usage
Telemetry$log_logout(
username = NULL,
session = shiny::getDefaultReactiveDomain()
)
Arguments
usernamestring with username from current session
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_click()
Log an action click
Usage
Telemetry$log_click(id, session = shiny::getDefaultReactiveDomain())
Arguments
idstring that identifies a manual click to the dashboard.
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_browser_version()
Log the browser version
Usage
Telemetry$log_browser_version(session = shiny::getDefaultReactiveDomain())
Arguments
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_button()
Track a button and track changes to this input (without storing the
values)
Usage
Telemetry$log_button(
input_id,
track_value = FALSE,
session = shiny::getDefaultReactiveDomain()
)
Arguments
input_idstring that identifies the button in the Shiny
application so that the function can track and log changes to it.
track_valueflag that indicates if the basic telemetry should
track the value of the input that are changing. FALSE by default.
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_all_inputs()
Automatic tracking of all input changes in the App. Depending on the
parameters, it may only track a subset of inputs by excluding patterns
or by including specific vector of input_ids.
Usage
Telemetry$log_all_inputs(
track_values = FALSE,
excluded_inputs = c("browser_version"),
excluded_inputs_regex = NULL,
include_input_ids = NULL,
session = shiny::getDefaultReactiveDomain()
)
Arguments
track_valuesflag that indicates if the basic telemetry should
track the values of the inputs that are changing. FALSE by default.
This parameter is ignored if track_inputs is FALSE.
excluded_inputsvector of input_ids that should not be tracked.
By default it doesn't track browser version, which is added by this
package.
excluded_inputs_regexvector of input_ids that should not be
tracked. All Special characters will be escaped.
include_input_idsvector of input_ids that will be tracked.
This input_ids should be an exact match and will be given priority
over exclude list.
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_input()
Track changes of a specific input id.
Usage
Telemetry$log_input(
input_id,
track_value = FALSE,
matching_values = NULL,
input_type = "text",
session = shiny::getDefaultReactiveDomain()
)
Arguments
input_idstring (or vector of strings) that identifies the
generic input in the Shiny application so that the function can track and
log changes to it.
When the input_id is a vector of strings, the function will behave just
as calling log_input one by one with the same arguments.
track_valueflag that indicates if the basic telemetry should
track the value of the input that are changing. FALSE by default.
matching_valuesAn object specified possible values to register.
input_type"text" to registered bare input value, "json" to parse
value from JSON format.
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for its side effects.
Method log_input_manual()
Log a manual input value.
This can be called in telemetry and is also used as a layer between
log_input family of functions and actual log event.
It creates the correct payload to log the event internally.
Usage
Telemetry$log_input_manual(
input_id,
value = NULL,
session = shiny::getDefaultReactiveDomain()
)
Arguments
input_idstring that identifies the generic input in the Shiny
application so that the function can track and log changes to it.
value(optional) scalar value or list with the value to register.
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_custom_event()
Log a manual event
Usage
Telemetry$log_custom_event(
event_type,
details = NULL,
session = shiny::getDefaultReactiveDomain()
)
Arguments
event_typestring that identifies the event type
details(optional) scalar value or list with the value to register.
sessionShinySession object or NULL to identify the current
Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_error()
Log a manual error event
Usage
Telemetry$log_error(
output_id,
message,
session = shiny::getDefaultReactiveDomain()
)
Arguments
output_idstring that refers to the output element where the error occurred.
messagestring that describes the error.
sessionShinySession object or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_errors()
Track errors as they occur in observe and reactive
Usage
Telemetry$log_errors(session = shiny::getDefaultReactiveDomain())
Arguments
sessionShinySession object or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method clone()
The objects of this class are cloneable with this method.
Usage
Telemetry$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
DataStorage which this function wraps.
Examples
log_file_path <- tempfile(fileext = ".txt")
telemetry <- Telemetry$new(
data_storage = DataStorageLogFile$new(log_file_path = log_file_path)
) # 1. Initialize telemetry with default options
#
# Use in a shiny application
if (interactive()) {
library(shiny)
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)) })
}
)
}
#
# Manual logging of Telemetry that can be used inside Shiny Application
# to further customize the events to be tracked.
session <- shiny::MockShinySession$new() # Create dummy session (only for example purposes)
class(session) <- c(class(session), "ShinySession")
telemetry$log_click("a_button", session = session)
telemetry$log_error("global", message = "An error has occured")
telemetry$log_custom_event("a_button", list(value = 2023), session = session)
telemetry$log_custom_event("a_button", list(custom_field = 23), session = session)
# Manual call login with custom username
telemetry$log_login("ben", session = session)
# Read all data
telemetry$data_storage$read_event_data()
file.remove(log_file_path)
#
# Using SQLite
db_path <- tempfile(fileext = ".sqlite")
telemetry_sqlite <- Telemetry$new(
data_storage = DataStorageSQLite$new(db_path = db_path)
)
telemetry_sqlite$log_custom_event("a_button", list(value = 2023), session = session)
telemetry_sqlite$log_custom_event("a_button", list(custom_field = 23), session = session)
# Read all data from time range
telemetry_sqlite$data_storage$read_event_data("2020-01-01", "2055-01-01")
file.remove(db_path)
Appsilon/shiny.stats documentation built on Dec. 18, 2024, 6:14 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Telemetry | R Documentation |
Telemetry class to manage analytics gathering at a global level
Description
An instance of this class will define metadata and data storage provider for gathering telemetry analytics of a Shiny dashboard.
The name and version parameters will describe the dashboard name and
version to track using analytics, allowing to store the analytics data from
multiple dashboards in the same data storage provider. As well as
discriminate different versions of the dashboard.
The default data storage provider uses a local SQLite database, but this
can be customizable when instantiating the class, by using another one of
the supported providers (see DataStorage).
Debugging
Events are logged at the DEBUG level using the logger package.
To see the logs, you can set:
logger::log_threshold("DEBUG", namespace = "shiny.telemetry")
Active bindings
data_storageinstance of a class that inherits from
DataStorage. See the documentation on that class for more information.app_namestring with name of dashboard
Methods
Public methods
Method new()
Constructor that initializes Telemetry instance with parameters.
Usage
Telemetry$new(
app_name = "(dashboard)",
data_storage = DataStorageSQLite$new(db_path = file.path("telemetry.sqlite"))
)Arguments
app_name(optional) string that identifies the name of the dashboard. By default it will store data with
(dashboard).data_storage(optional)
DataStorageinstance where telemetry data is being stored. It can take any of data storage providers by this package, By default it will store in a SQLite local database in the current working directory with filenametelemetry.sqliteversion(optional) string that identifies the version of the dashboard. By default it will use
v0.0.0.
Method start_session()
Setup basic telemetry
Usage
Telemetry$start_session( track_inputs = TRUE, track_values = FALSE, login = TRUE, logout = TRUE, browser_version = TRUE, navigation_input_id = NULL, session = shiny::getDefaultReactiveDomain(), username = NULL, track_anonymous_user = TRUE, track_errors = TRUE )
Arguments
track_inputsflag that indicates if the basic telemetry should track the inputs that change value.
TRUEby defaulttrack_valuesflag that indicates if the basic telemetry should track the values of the inputs that are changing.
FALSEby default. This parameter is ignored iftrack_inputsisFALSEloginflag that indicates if the basic telemetry should track when a session starts.
TRUEby default.logoutflag that indicates if the basic telemetry should track when the session ends.
TRUEby default.browser_versionflag that indicates that the browser version should be tracked.
TRUEby default.navigation_input_idstring or vector of strings that represent input ids and which value should be tracked as navigation events. i.e. a change in the value represent a navigation to a page or tab. By default, no navigation is tracked.
sessionShinySessionobject or NULL to identify the current Shiny session.usernameCharacter with username. If set, it will overwrite username from session object.
track_anonymous_userflag that indicates to track anonymous user. A cookie is used to track same user without login over multiple sessions, This is only activated if none of the automatic methods produce a username and when a username is not explicitly defined.
TRUEby default.track_errorsflag that indicates if the basic telemetry should track the errors.
TRUEby default. if using shiny version <1.8.1, it can auto log errors only in UI output functions. By using latest versions of shiny, it can auto log all types of errors.
Returns
Nothing. This method is called for side effects.
Method log_navigation()
Log an input change as a navigation event
Usage
Telemetry$log_navigation(input_id, session = shiny::getDefaultReactiveDomain())
Arguments
input_idstring that identifies the generic input in the Shiny application so that the function can track and log changes to it.
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_navigation_manual()
Log a navigation event manually by indicating the id (as input id)
Usage
Telemetry$log_navigation_manual( navigation_id, value, session = shiny::getDefaultReactiveDomain() )
Arguments
navigation_idstring that identifies navigation event.
valuestring that indicates a value for the navigation
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_login()
Log when session starts
Usage
Telemetry$log_login( username = NULL, session = shiny::getDefaultReactiveDomain() )
Arguments
usernamestring with username from current session
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_logout()
Log when session ends
Usage
Telemetry$log_logout( username = NULL, session = shiny::getDefaultReactiveDomain() )
Arguments
usernamestring with username from current session
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_click()
Log an action click
Usage
Telemetry$log_click(id, session = shiny::getDefaultReactiveDomain())
Arguments
idstring that identifies a manual click to the dashboard.
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_browser_version()
Log the browser version
Usage
Telemetry$log_browser_version(session = shiny::getDefaultReactiveDomain())
Arguments
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_button()
Track a button and track changes to this input (without storing the values)
Usage
Telemetry$log_button( input_id, track_value = FALSE, session = shiny::getDefaultReactiveDomain() )
Arguments
input_idstring that identifies the button in the Shiny application so that the function can track and log changes to it.
track_valueflag that indicates if the basic telemetry should track the value of the input that are changing.
FALSEby default.sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_all_inputs()
Automatic tracking of all input changes in the App. Depending on the
parameters, it may only track a subset of inputs by excluding patterns
or by including specific vector of input_ids.
Usage
Telemetry$log_all_inputs(
track_values = FALSE,
excluded_inputs = c("browser_version"),
excluded_inputs_regex = NULL,
include_input_ids = NULL,
session = shiny::getDefaultReactiveDomain()
)Arguments
track_valuesflag that indicates if the basic telemetry should track the values of the inputs that are changing.
FALSEby default. This parameter is ignored iftrack_inputsisFALSE.excluded_inputsvector of input_ids that should not be tracked. By default it doesn't track browser version, which is added by this package.
excluded_inputs_regexvector of input_ids that should not be tracked. All Special characters will be escaped.
include_input_idsvector of input_ids that will be tracked. This input_ids should be an exact match and will be given priority over exclude list.
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_input()
Track changes of a specific input id.
Usage
Telemetry$log_input( input_id, track_value = FALSE, matching_values = NULL, input_type = "text", session = shiny::getDefaultReactiveDomain() )
Arguments
input_idstring (or vector of strings) that identifies the generic input in the Shiny application so that the function can track and log changes to it.
When the
input_idis a vector of strings, the function will behave just as callinglog_inputone by one with the same arguments.track_valueflag that indicates if the basic telemetry should track the value of the input that are changing.
FALSEby default.matching_valuesAn object specified possible values to register.
input_type"text"to registered bare input value,"json"to parse value fromJSONformat.sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for its side effects.
Method log_input_manual()
Log a manual input value.
This can be called in telemetry and is also used as a layer between log_input family of functions and actual log event. It creates the correct payload to log the event internally.
Usage
Telemetry$log_input_manual( input_id, value = NULL, session = shiny::getDefaultReactiveDomain() )
Arguments
input_idstring that identifies the generic input in the Shiny application so that the function can track and log changes to it.
value(optional) scalar value or list with the value to register.
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_custom_event()
Log a manual event
Usage
Telemetry$log_custom_event( event_type, details = NULL, session = shiny::getDefaultReactiveDomain() )
Arguments
event_typestring that identifies the event type
details(optional) scalar value or list with the value to register.
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_error()
Log a manual error event
Usage
Telemetry$log_error( output_id, message, session = shiny::getDefaultReactiveDomain() )
Arguments
output_idstring that refers to the output element where the error occurred.
messagestring that describes the error.
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method log_errors()
Track errors as they occur in observe and reactive
Usage
Telemetry$log_errors(session = shiny::getDefaultReactiveDomain())
Arguments
sessionShinySessionobject or NULL to identify the current Shiny session.
Returns
Nothing. This method is called for side effects.
Method clone()
The objects of this class are cloneable with this method.
Usage
Telemetry$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
DataStorage which this function wraps.
Examples
log_file_path <- tempfile(fileext = ".txt")
telemetry <- Telemetry$new(
data_storage = DataStorageLogFile$new(log_file_path = log_file_path)
) # 1. Initialize telemetry with default options
#
# Use in a shiny application
if (interactive()) {
library(shiny)
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)) })
}
)
}
#
# Manual logging of Telemetry that can be used inside Shiny Application
# to further customize the events to be tracked.
session <- shiny::MockShinySession$new() # Create dummy session (only for example purposes)
class(session) <- c(class(session), "ShinySession")
telemetry$log_click("a_button", session = session)
telemetry$log_error("global", message = "An error has occured")
telemetry$log_custom_event("a_button", list(value = 2023), session = session)
telemetry$log_custom_event("a_button", list(custom_field = 23), session = session)
# Manual call login with custom username
telemetry$log_login("ben", session = session)
# Read all data
telemetry$data_storage$read_event_data()
file.remove(log_file_path)
#
# Using SQLite
db_path <- tempfile(fileext = ".sqlite")
telemetry_sqlite <- Telemetry$new(
data_storage = DataStorageSQLite$new(db_path = db_path)
)
telemetry_sqlite$log_custom_event("a_button", list(value = 2023), session = session)
telemetry_sqlite$log_custom_event("a_button", list(custom_field = 23), session = session)
# Read all data from time range
telemetry_sqlite$data_storage$read_event_data("2020-01-01", "2055-01-01")
file.remove(db_path)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.