Monitor Settings

This article will describe how the Telerik Analytics monitor behavior can be configured for different scenarios by creating it using various customized settings.

Creating the monitor

The monitor can be created in one of two ways (shown in pseudo-code):

Either with default settings:

monitor = Factory.CreateMonitor(productKey, version)

Or with custom settings:

settings = Factory.CreateSettings(productKey, version)

// adjust the settings for creating the monitor
settings.Something = something;

monitor = Factory.CreateMonitorFromSettings(settings)

The former create-method is simpler, but in practice many users end up using the latter, customized create-method.

The reasoning behind this approach is to enforce that mandatory settings are always provided and certain other settings can only be modified up to a certain point:

  • The productKey (and version on some platforms) is mandatory and cannot be omitted. They are therefore passed as mandatory parameters to the create-method.
  • The settings-object can be used to configure monitor behavior prior to creating or starting it. For example whether to use HTTP or HTTPS for network traffic.
  • Once created, the only accessible API methods are those on the monitor-object itself. For instance, at runtime you can still set and change the InstallationID but changing the properties on the settings instance has no effect on monitor behavior.

Monitor Settings

The remainder of this article will elaborate on each property of the settings object individually. Note that some properties may not be available on some platforms and that the code examples below are shown in pseudo code

DailyNetworkUtilizationInKB

settings.DailyNetworkUtilizationInKB = 1024;

Explicitly set a limit on the daily network utilization of the monitor. The utilization is accumulated based on the size of the payload for both upstream and downstream data and is enforced on a daily basis which resets at midnight (client time). If the limitation is reached, no data communication is attempted and the data is pending until the next day.

See also Data Lifecycle.

Location

settings.Location.Latitude = 55.669996;
settings.Location.Longitude = 12.539145;

The location of the monitor as GPS latitude and longitude coordinates. Use this property if you have access to GPS coordinates for the location of the application. If provided, these coordinates will be delivered to the servers as part of the data payload.

If provided, the GPS coordinates will be used to determine the geolocation of the session. If not provided, the Analytics servers will use a geolocation database to resolve the location based on the incoming IP address.

LoggingInterface

IAnalyticsMonitorLog log = new MyLoggingImplementation();
settings.LoggingInterface = log;

The integrated monitor is designed to provide error isolation and not propagate internal errors to the calling user. However, it is possible to get access to these internal errors as well as the internal status messages by assigning an appropriate implementation of the IAnalyticsMonitorLog interface to the LoggingInterface property. Note that on most platforms you can easily obtain a simple logging interface through a convenience method on the AnalyticsMonitorFactory class.

If assigned, the implementation will receive both error and informational logging messages that can be used for troubleshooting issues or for forwarding to an existing application log.

See also Logging Monitor Activity.

MaxStorageSizeInKB

settings.MaxStorageSizeInKB = 2048;

On some devices the disk space available may be limited or your application may decide to post some restrictions on the amount of disk space used by the monitor for storing the meta data. By assigning a value to the MaxStorageSizeInKB you can effectively limit the amount of data used for storing monitor meta data. You cannot assign this value below 1KB as the monitor requires a minimum of space for storing the most essential meta data.

Please note that the monitor also limits the amount of memory consumed while the application is running by removing excessive, un-delivered data from memory to avoid affecting the hosting application. This only applies in scenarios where there is no connectivity to the Analytics servers.

See also Data Lifecycle and Local Data Storage

ProductKey

The ProductKey property is a read only property for retrieving the value of the key by which the settings instance was constructed.

See also Add Analytics to Your Application

Proxy

settings.Proxy.ProxyConnectionString = "MyProxyServer:8080";
settings.Proxy.ProxyUserName = "foo";
settings.Proxy.ProxyPassword = "bar";

Where available the monitor instance will use the available proxy setup configured for the end user device. For some platforms it is possible to setup custom proxy settings to match specific deployment environments and in these cases the Proxy property is not exposed.

See also Network Traffic.

ServerUri

settings.ServerUri = new Uri("http://specialized.example.com");

By default, the monitor library will generate a default url to the server endpoint on the Analytics servers which is valid in almost all situations. This default url can be retrieved through the ServerUri property. However, your application may be deployed in a scenario where there are e.g. specific internal DNS rules or corporate settings applied to internet connectivity and for those scenarios you can assign to the ServerUri property to circumvent specific infrastructure concerns.

Make sure that the assigned value is redirected to the Analytics servers located at http(s)://monitor-eqatec.com. Hitting that url should return a simple textual document for verification.

See also Network Traffic.

StorageInterface

settings.StorageInterface = AnalyticsMonitorFactory.CreateStorage("path/to/desired/storage/folder");

By default the monitor library stores data locally on the end user device. This data include both meta data as well as the not yet delivered session data. Independently of other activity the monitor will make sure to persist the collected data to storage at least every minute to make sure all collected data is not lost in the event of e.g. application crashes. All data is also stored on calls to the Stop method.

The default location for this storage is dependent upon your specific platform. However you may need to take control of this storage location if the default location does not work for you for various reasons:

  • The default location is typically per user on the device and you may decide that you need to have all users share the same location and thus the same meta data about the monitor. Read more about how sharing the location for multiple users affects your installation data and statistics here.
  • Your deploying your application in a virtualized environment (like Citrix) and you need the monitor data to roam with the logged in user (which it does not do by default).
  • You want the stored data to be removed if you are uninstalling the application so you need to control precisely where the data is stored so that you can remove it as part of the software removal process.

As shown in the pseudo-code above, the AnalyticsMonitorFactory exposes a few convenience methods for creating a storage implementation, typically on the local filesystem or in isolated storages. You can, however, provide your own storage interface by implementing the IStorage interface, though this should not be needed in most cases.

See also Local Data Storage.

StorageSaveInterval

settings.StorageSaveInterval = 60sec;

The StorageSaveInterval defines the maximum allowed time before the internal state of the monitor is persisted to the storage interface. The monitor does persist the internal state as part of the background processing so this interval defines the maximum allowed time between these calls. As such, this interval defines the amount of data that would be lost if the application or device crashed without any shutdown procedure being executed.

By default, this is set to one minute. If you set the property to 0, no periodic persisting is performed.

See also Data Lifecycle.

SynchronizeAutomatically

settings.SynchronizeAutomatically = true;

By default, the monitor will autonomously control when data is delivered to the Analytics servers in the background. Your software should not have to care about this aspect as the monitor will handle disconnected scenarios and local caching of the data.

However, there may be certain scenarios where you want to explicitly affect when the monitor attempts to deliver data to the servers. Use the SynchronizeAutomatically flag (where available) to specify if the monitor should only begin to synchronize on explicit calls to the ForceSync method. Please note that the call to ForceSync only schedules a delivery of data and is not a blocking call.

See also Data Lifecycle.

TestMode

settings.TestMode = true;

By default, data is not marked as test data when sent from the monitor. Use this flag to mark this data as testing or internal data and this will affect the visibility of the data in the Analytics client.

See also Public and Internal Origin.

Version

settings.Version = new Version(1,2,3,4);

This property allows you to assign the version of your software when tracking data. Tracking the version allows you to better filter your data and understand trends and regressions in your software. On some platforms, this Version property is pre-filled with the version of the calling software while on other platforms the API requires you to explicitly specify the version as part of the construction of the monitor.

The version format is limited to the Major.Minor.Build.Revision format and only accepts numbers for all the four parts.

UseSSL

settings.UseSSL = true;

By default the monitor communicates with the Analytics servers on the http protocol using port 80. If the UseSSL property is set to true, the default communication to the Analytics servers will be using the https protocol on port 443 instead.

Please note that if you have assigned the ServerUri property explicitly, the UseSSL property is ignored.

See also Network Traffic.

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All Rights Reserved.