General Behavior

This article describes general characteristics and behavior of the Analytics monitor API. The API is described in detail in the API Reference.

API calls outside Start/Stop are ignored

Any API calls placed prior to calling Start are simply ignored and will return without having any effect. The same goes for API calls made after Stop. (With two exceptions mentioned later.)

This means that you do not have to write code like this, because the call to TrackFeature is already ignored if the monitor has not yet been started:

if (monitor.Status.IsStarted)
  monitor.TrackFeature("SomeCategory.SomeFeature");

Disabling Analytics

It also means that the only thing you need to do to disable Analytics entirely is simply to not call Start.

This can be relevant if the end-user says "no" to tracking and you therefore wish to disable Analytics. In that case you do not need to place protective conditions around the API calls like this:

// DON'T DO THIS
if (isAnalyticsEnabled)
  monitor.TrackFeature("SomeCategory.SomeFeature");
...
if (isAnalyticsEnabled)
  monitor.TrackFeature("SomeOtherCategory.SomeOtherFeature");
...
if (isAnalyticsEnabled)
  monitor.Stop();

Instead, you only need to just disable the Start call and let all the other API calls be. Like so:

// Only enable Analytics if user approves
if (isAnalyticsEnabled)
  monitor.Start();
...
monitor.TrackFeature("SomeFeature");
...
monitor.TrackFeature("SomeOtherFeature");
monitor.Stop();

Exceptions

There are two exceptions to this rule:

  • Calling SetInstallationInfo will work even outside Start/Stop
  • Some platforms have an explicit disposal call Release that should be called after Stop.

API methods never fail

When talking about API method return codes it makes sense to look at two groups:

  • Factory methods to create monitor, settings, storage- and logging-objects
  • Instance methods on those created objects, e.g. on the monitor object

All API methods do rigorous parameter checking to ensure that they are valid. It is harmless to pass e.g. null to an API method expecting a string, so you do not need to do so to guard against passing invalid parameters.

Factory methods

If a factory create method (CreateSettings, CreateMonitor, etc) fails then it will produce an error on the platform's standard debug console and indicate the failure in this manner:

  • All .NET, AppBuilder, Java/Android, Javascript: throw an exception
  • Windows (C, C++), iOS, MacOS: return null

For instance, if you pass the string "Hello World" as the product key to CreateSettings on .NET then write the reason for that to the System.Diagnostics.Debug output and throw an exception that you should catch.

Instance methods

Instance methods (Start, Stop, TrackFeature, etc) never return errors if something is wrong. They are all void, so you never have to check their return codes (they have none) nor wrap them in try-catch exception handlers to ensure they do not throw exceptions (they will not). You just call them as they are.

In case of errors it will be logged to the logger specified by the settings. You can read more about this in the article on Logging Monitor Activity. By default there is no logging enabled and you must explicitly setup logging if you wish to do so.

For instance, if you pass a null string or a string exceeding the maximum feature name length to TrackFeature, then it will simply not track anything and will write the reason to the logger.

Rare error cases are not trapped

Not all error conditions can be caught by the monitor API. Here are some exceptions:

  • On .NET the StackOverflowException cannot be caught
  • Invoking methods on an invalid object (null or invalid pointer on e.g. C++) will typically fail without the monitor being involved at all
  • On Windows C++, both C++ and SEH exceptions are handled internally but some situations are uncatchable, such as passing an unaligned pointer argument that causes a SIGBUS signal.

API Calls are Non-Blocking

API calls are, with one exception, "non-blocking". This means that you do not have to e.g. create background threads to call the API methods for fear that they may take too long.

The one exception is Stop, which can be blocking for up to 2 seconds (by default). This is by design so the monitor can deliver accumulated statistics to the Analytics servers before the application shuts down.

You can read much more about this in the article on Monitor API Overhead.

Monitor is exposed an an interface

On all platforms, the monitor is exposed as an interface.

This means that you can easily substitute your own version of the monitor instance, if so desired. This can be useful for mocking and stubbing the monitor in unit tests.

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.