Type: Package
Title: Include Azure Application Insights in Shiny Apps
Version: 0.3.1
Description: Imports Azure Application Insights for web pages into Shiny apps via Microsoft's JavaScript snippet. Allows app developers to submit page tracking and submit events.
License: MIT + file LICENSE
BugReports: https://github.com/stefanedwards/AzureAppInsights/issues
Depends: R (≥ 4.0.0)
Imports: shiny (≥ 1.5.0), rlang (≥ 0.4.11), assertthat (≥ 0.2.0), jsonlite (≥ 1.7.2), lubridate (≥ 1.7)
Encoding: UTF-8
Suggests: testthat, here
RoxygenNote: 7.2.3
Collate: '0aux.R' 'AzureAppInsights-package.R' 'cfg.R' 'demo.R' 'include_snippet.R' 'tracking.R'
NeedsCompilation: no
Packaged: 2023-06-13 11:45:33 UTC; smhe
Author: Stefan McKinnon Edwards [aut, cre], Kamstrup A/S [cph]
Maintainer: Stefan McKinnon Edwards <smhe@kamstrup.com>
Repository: CRAN
Date/Publication: 2023-06-13 14:40:08 UTC

Azure Application Insights for web pages

Description

Add Azure Application Insights tracking to a Shiny App. Requires an active Azure subscription and Application Insights instrumentation key! Based on https://docs.microsoft.com/en-us/azure/azure-monitor/app/javascript / https://github.com/microsoft/ApplicationInsights-JS.

Details

Documentation in this page will be limited, as most is explained on the main page.

Supports so far only pageViews (automatically sent), autoTrackPageVisitTime (when configured with config), customEvents (see trackEvent).

Author(s)

Stefan McKinnon Edwards <smhe@kamstrup.dk>

See Also

Useful links:

Configure Azure Application Insights

Description

Ensures an instrumentationKey/connectionString and appId is provided.

Usage

config(
  appId,
  instrumentationKey,
  connectionString,
  autoTrackPageVisitTime = TRUE,
  ...
)

Arguments

appId

String for identifying your app, if you use same Application Insights for multiple apps.

instrumentationKey, connectionString

Credentials for sending to Application Insights. connectionString is preferred for newer accounts and must contain both InstrumentationKey and IngestionEndpoint.

autoTrackPageVisitTime

Submits how long time a user spent on the *previous* page (see website for more information).

...

Additional options, as given in https://docs.microsoft.com/en-us/azure/azure-monitor/app/javascript#configuration. No checks performed here.

Details

See https://docs.microsoft.com/en-us/azure/azure-monitor/app/javascript#configuration for explanation of options.

If jsonlite is playing tricks on the arguments given, wrap the value with I. E.g. if you want to force an atomic vector of length 1 to be parsed as an array, use I(3.14).

Value

List.

Demonstration of Application Insights

Description

Launches a simple demonstration of using Application Insights for Shiny apps. Requires that you have a Microsoft Azure Application Insights resource to send to; demonstration will still work – your metrics will just be sent to oblivion.

Usage

demo(
  connectionString,
  debug = TRUE,
  appId = "Test AzureAppInsights",
  launch.browser = FALSE,
  instrumentationKey
)

Arguments

connectionString, instrumentationKey

Credentials for sending to Application Insights. See arguments for config.

debug

Logical, see startAzureAppInsights.

appId

A id for this particular application.

launch.browser

Logical, see runApp.

Details

It may take some minutes before the values sent to Application Insights are visible in the logs on portal.azure.com.

If neither connectionString nor instrumentationKey is provided, a connection string is found in the environment variable AAI_CONNSTR.

Examples

connstr <- paste0(
  'InstrumentationKey=00000000-0000-0000-0000-000000000000;',
  'IngestionEndpoint=https://northeurope-0.in.applicationinsights.azure.com/;',
  'LiveEndpoint=https://northeurope.livediagnostics.monitor.azure.com/')
## Not run: 
 demo(connstr)

## End(Not run)

Check if string matches pattern for an instrumentation key.

Description

Check if string matches pattern for an instrumentation key.

Usage

is_instrumentation_key(x)

Arguments

x

A string containing nothing else but an instrumentation key.

Value

Logical value.

Include and run Azure Application Insights for web pages

Description

Include the JS snippet in your ui-function with includeAzureAppInsights and start the tracking with startAzureAppInsights in your server-function.

Usage

startAzureAppInsights(
  session,
  cfg,
  instance.name = "appInsights",
  ld = 0,
  useXhr = TRUE,
  crossOrigin = "anonymous",
  onInit = NULL,
  heartbeat = 3e+05,
  extras = list(),
  include.ip = FALSE,
  cookie.user = FALSE,
  debug = FALSE
)

includeAzureAppInsights(version = c("2.8.14", "2.7.0"))

Arguments

session

The session object passed to function given to shinyServer.

cfg

List-object from config.

instance.name

Global JavaScript Instance name defaults to "appInsights" when not supplied. NOT the app's name. Used for accessing the instance from other JavaScript routines.

ld

Defines the load delay (in ms) before attempting to load the sdk. -1 = block page load and add to head. (default) = 0ms load after timeout,

useXhr

Logical, use XHR instead of fetch to report failures (if available).

crossOrigin

When supplied this will add the provided value as the cross origin attribute on the script tag.

onInit

Once the application insights instance has loaded and initialized this callback function will be called with 1 argument – the sdk instance

heartbeat

Integer, how often should the heartbeat beat – or set to FALSE to disable.

extras

(Named) list of values to add to any tracking.

include.ip

Logical, adds ip to all tracking's customDimension. See note.

cookie.user

Logical, when TRUE sets a cookie with a random string and submits this along with any tracking with the key userid.

debug

Logical, JS loader uses console.log.

version

Version of the Application Insights JavaScript SDK to load.

Value

Methods sends data to client's browser; returns the sent list, invisibly.

Tracking users' ip-address

Generally, Azure's Application Insight does not collect the users' ip-address, due to it being somewhat sensitive data (link).

startAzureAppInsights however has the argument 'include.ip' which, when set to TRUE, will add the entry ip to all trackings. The tracked ip-address is taken from session$request$REMOTE_ADDR, which is an un-documented feature and may or may not be the users ip-address.

References

https://docs.microsoft.com/en-us/azure/azure-monitor/app/javascript and https://github.com/microsoft/ApplicationInsights-JS and https://learn.microsoft.com/en-us/azure/azure-monitor/app/ip-collection?tabs=net

Sends an event or set of metrics to Application Insights

Description

Use trackEvent for tracking a single event together with any extra properties.

Use trackMetric to track a summary of some measured metrics.

Usage

trackEvent(session, name, properties)

trackMetric(session, name, metrics, properties)

Arguments

session

The session object passed to function given to shinyServer.

name

Name of the event.

properties

List of properties to track. appId and any extras given in startAzureAppInsights is automatically inserted.

metrics

Numeric vector of values to calculate summary on. Non-finite values are removed.

Value

Method sends data to client's browser; returns the sent list, invisibly.

Tracking Metrics

Individual measured values are not sent to Application Insights. Instead, summaries of the values (mean, range, average, standard deviation) are sent. Note: Standard deviation doesn't quite work yet.

Before calculating summaries, non-finite values are removed (see is.finite). If there are no values in metrics, nothing is sent.