Improve analytics (#3088)

* Improve analytics

We have a requirement to track information in several different providers. However, this may slow down CLI's operations as each track (at least for some of the providers) may last around 100-300ms.
In order to track in multiple analytics provider without slowing down CLI commands, move the tracking to a new process. The process is detached from CLI, so when CLI finishes its work it will exit, while the child process will remain alive until it sends all required information. The new process is called `analytics-broker-process`, it is detached from CLI, but it there's IPC channel between them, so CLI can send information to be tracked. Just before CLI dies, it will send "finish" message to the `broker` process and the IPC channel will be closed.

In CLI implement a new `analytics-service`, so when the methods `track`, `trackFeature` and `trackException` are called, instead of tracking directly in CLI's process (i.e. the old implementation), to send information to the broker process.
The only exception is tracking of the answer if user allows us to send anonymous statistics. As this action requires user interaction, it is executed in CLI's process, a new eqatec analytics monitor is started and the answer is sent to it. After that the analytics is stopped. In case the answer is "yes" and there is more information that we want to track in the current process, it will be send to broker and tracked in all providers. In case the answer is "no", no other data will be tracked.

The broker process is started from analytics process once per process, i.e. on each CLI process (which have something to track) there's a corresponding `analytics-broker-process`. Once it is initialized, it sends BrokerReadyToReceive message to CLI and CLI knows that it can start sending tracking information. Initialization phase is creating a new instance of AnalyticsBroker and attaching handlers for `message` and `disconnect` events. The AnalyitcsBroker itself has a single purpose - sends tracking data to all available prociders. Currently the only provider is `eqatecAnalyticsProvider`. Once CLI sends "finish" message (or `analytics-broker-process` receives `disconnect` event), the process sends information to all providers that there's nothing more to be tracked. When all providers finish their work, they should disocnnect themselves from the broker process and it will exit gracefully.

`EqatecAnalyticsProvider` is used to track features and exceptions in Progress Telerik Analytics. Our requirement is to track features in two projects (same data should be send to both of them) and exceptions in another project. Each of them should be in a separate child process, so failure in one of them will not reflect the others. So the provider starts all required processes. When broker sends information to the provider, it sends it to all required child processes, for example if a feature should be tracked, the provider will send information for it to the two processes used for feature tracking.

Each eqatec child process is a new Node.js  process runnign `eqatec-analytics-process`. Again - this is a detached process. Once it is initialized, it sends "EqatecAnalyticsReadyToReceive" message to the `EqatecAnalyitcsProvider` and it knows it can send information to the new child process. The initialization phase is creation of new instance of `EqatectAnalyticsService`, attaching to "message" and "disconnect" events. Once `EqatecAnalyitcsProvider` receives `EqatecAnalyticsReadyToReceive` message, it sends initialization data for the eqatec monitor. It includes the analytics project API key, user id, current sessions count, etc. The information is persisted in a file on user's machine, so this file should be updated from a single process. As we might have 3 eqatec analytics processes, the provider is the only place where the file should be read and updated.

When `eqatec-analytics-process` receives initialization data, it creates a new instance of the `EqatectAnalyticsService` class with it. However a monitor is not started yet. It will be started when there's something to be tracked, i.e. once `eqatec-analytics-process` receives feature or exception to be tracked.

When `eqatec-analytics-process` receives "finish" message, it awaits all pending requests and after that disconnets itself from the parent. In case this operation fails, the process just exits, which will allow the parent to exit gracefully.

Remove the public `startEqatecMonitor` method from API - it has not been used.

* Craete all eqatec analytics monitors in the broker process

Eqatec Analytics monitors can be created in the broker process directly instead of starting multiple child processes. So delete some unneeded files and move tracking of `AcceptUsageReporting` out of CLI process.

* Add tracking to Google Analytics

Add new methods to track information in Google Analytics(GA). As the data that we want to track is different than the one we track in Eqatec Analytics, call the new methods whenever we want to send some information to GA.
Change the broker process to send information to Eqatec Analytics when we want to track feature or exception and to GA only when the new method for tracking there is called.

In Google Analytics (GA) we track two types of data - pages (called pageviews) and events. Each command is tracked as a page - we only track the name of the command as a page:
* `tns build android` will be tracked as visited page - `build android`
* `tns run` will be tracked as visited page - `run`

When we want to track some additional actions that happen during execution of each command, we send events to GA. Each event has the following data:
* category - currently we do not have a specific category for each action, so it is hardcoded to "CLI".
* action - this is the real action that will be tracked, for example `Build`, `LiveSync`, `Deploy`, etc.
* label - contains specific inforamation for the current action, for example what is the platform, device type, etc. In many cases we send labels with a lot of information, but as the value must be string, we use `_` as a separator. For example:
  * Action `Build` may have the following label: `Android_Debug_Incremental`. This is `<platform>_<build configuration>_<build type>`.
  * Action `LiveSync` may have the following label: `Android_Emulator_5.1`. This is `<platform>_<device type>_<device os version>`.

Custom dimensions
For each additional data may be send to GA via Custom Dimensions. More about them can be found [here](https://support.google.com/analytics/answer/2709828). We are using several custom dimensions, most of them have hit scope, i.e. their values are saved for the current hit (event or page), but may be changed for the next time. The only exclusion is `session id` - it has session scope, so whenever it is sent, the new value overwrites the values of the "session id" property in all hits of the current session.
One interesting custom dimension is `Client` - it will be set to the value of `--analyticsClient` in case it is passed. In case not, we'll set it to "CLI" when terminal is interactive and "Unknown" when terminal is not interactive.

Sessions - what is session for GA
In Eqatec Analytics we call `stopMonitor` at the end of each command. So the session there is one command. In GA we've decided to keep the default way of measuring a session - a session is stopped when there are 30 inactive minutes, i.e. no data is sent from 30 minutes. This allows us to investigate the behavior and the flow of commands a user is executing in a single session (during the day for example).

Client ID and User ID:
Currently we do not send User ID to GA, we use Client ID instead as sending User IDs requires different logic and agreements. For us all users are anonymous.

User-Agent
When sending requests to GA, we need to set correct User-Agent, so GA will be able to understand the Operating System. For each OS the string is painfully specific... Current implementation works fine for Windows, Linux and macOS.

Implementation
In order to send data to GA, we are using a `universal-analytics` npm package. We cannot use Google's default libraries (`analytics.js`, `gtag.js`) as they are written for browser. So the only way to track data is to use the Measurement Protocol (directly send http requests). However, `universal-analytics` package provides a very good abstraction over the Measurement Protocol, so we are using it instead of implementing each call.

More information about Measurement protocol:
https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters

* Fix hanging commands

In case the command is not related to LiveSync, once it finishes its work, CLI process should end. However, this works only on Windows, as the broker child process there is really detached from the parent. On macOS and Linux, the 'ipc' channel between the broker process and CLI, keeps both alive. So use the 'dispose' method, which is called at the end of command execution and disconnect the broker process. In case we are in LiveSync case, set shouldDispose to false and this way the broker will be kept alive. Once Ctrl + C is used to end the CLI process, send the finish message to broker and it will disconnect itself from CLI.

Author: rosen-vladimirov

.vscode/launch.json

@@ -67,8 +67,19 @@
 		{
 			"type": "node",
 			"request": "attach",
-			"name": "Attach to Process",
-			"port": 5858,
+			"name": "Attach to Broker Process",
+			// In case you want to debug Analytics Broker process, add `--debug-brk=9897` (or --inspect-brk=9897) when spawning analytics-broker-process.
+			"port": 9897,
+			"sourceMaps": true
+		},
+
+		{
+			"type": "node",
+			"request": "attach",
+			"name": "Attach to Eqatec Process",
+			// In case you want to debug Eqatec Analytics process, add `--debug-brk=9855` (or --inspect-brk=9855) when spawning eqatec-analytics-process.
+			// NOTE: Ensure you set it only for one of the analytics processes.
+			"port": 9855,
 			"sourceMaps": true
 		}
 

PublicAPI.md

@@ -394,21 +394,6 @@ tns.npm.view(["nativescript"], {}).then(result => {
 });
 ```
 
-## analyticsService
-Provides a way to configure analytics.
-
-### startEqatecMonitor
-* Definition:
-```TypeScript
-/**
- * Starts analytics monitor with provided key.
- * @param {string} projectApiKey API key with which to start analytics monitor.
- * @returns {Promise<void>}.
- */
-startEqatecMonitor(projectApiKey: string): Promise<void>;
-```
-
-
 ## debugService
 Provides methods for debugging applications on devices. The service is also event emitter, that raises the following events:
 * `connectionError` event - this event is raised when the debug operation cannot start on iOS device. The causes can be:

lib/bootstrap.ts

@@ -30,7 +30,9 @@ $injector.require("androidDebugService", "./services/android-debug-service");
 
 $injector.require("userSettingsService", "./services/user-settings-service");
 $injector.require("analyticsSettingsService", "./services/analytics-settings-service");
-$injector.requirePublic("analyticsService", "./services/analytics-service");
+$injector.require("analyticsService", "./services/analytics/analytics-service");
+$injector.require("eqatecAnalyticsProvider", "./services/analytics/eqatec-analytics-provider");
+$injector.require("googleAnalyticsProvider", "./services/analytics/google-analytics-provider");
 
 $injector.require("emulatorSettingsService", "./services/emulator-settings-service");
 

lib/commands/run.ts

@@ -5,7 +5,6 @@ export class RunCommandBase implements ICommand {
 
 	public platform: string;
 	constructor(protected $platformService: IPlatformService,
-		protected $liveSyncService: ILiveSyncService,
 		protected $projectData: IProjectData,
 		protected $options: IOptions,
 		protected $devicePlatformsConstants: Mobile.IDevicePlatformsConstants,

lib/common

@@ -73,7 +73,7 @@ export class StaticConfig extends StaticConfigBase implements IStaticConfig {
 	}
 
 	public get PATH_TO_BOOTSTRAP(): string {
-		return path.join(__dirname, "bootstrap");
+		return path.join(__dirname, "bootstrap.js");
 	}
 
 	public async getAdbFilePath(): Promise<string> {

lib/config.ts

@@ -103,3 +103,21 @@ export const enum NativePlatformStatus {
 	requiresPrepare = "2",
 	alreadyPrepared = "3"
 }
+
+export const enum DebugTools {
+	Chrome = "Chrome",
+	Inspector = "Inspector"
+}
+
+export const enum TrackActionNames {
+	Build = "Build",
+	CreateProject = "Create project",
+	Debug = "Debug",
+	Deploy = "Deploy",
+	LiveSync = "LiveSync"
+}
+
+export const enum BuildStates {
+	Clean = "Clean",
+	Incremental = "Incremental"
+}

lib/constants.ts

@@ -13,3 +13,4 @@ $injector.requirePublicClass("localBuildService", "./services/local-build-servic
 // We need this because some services check if (!$options.justlaunch) to start the device log after some operation.
 // We don't want this behaviour when the CLI is required as library.
 $injector.resolve("options").justlaunch = true;
+$injector.resolve<IStaticConfig>("staticConfig").disableAnalytics = true;

lib/nativescript-cli-lib-bootstrap.ts

@@ -1,7 +1,6 @@
 import { createGUID } from "../common/helpers";
 
 class AnalyticsSettingsService implements IAnalyticsSettingsService {
-	private static SESSIONS_STARTED_OBSOLETE_KEY = "SESSIONS_STARTED";
 	private static SESSIONS_STARTED_KEY_PREFIX = "SESSIONS_STARTED_";
 
 	constructor(private $userSettingsService: UserSettings.IUserSettingsService,
@@ -12,16 +11,12 @@ class AnalyticsSettingsService implements IAnalyticsSettingsService {
 		return true;
 	}
 
-	public async getUserId(): Promise<string> {
-		let currentUserId = await this.$userSettingsService.getSettingValue<string>("USER_ID");
-		if (!currentUserId) {
-			currentUserId = createGUID(false);
-
-			this.$logger.trace(`Setting new USER_ID: ${currentUserId}.`);
-			await this.$userSettingsService.saveSetting<string>("USER_ID", currentUserId);
-		}
+	public getUserId(): Promise<string> {
+		return this.getSettingValueOrDefault("USER_ID");
+	}
 
-		return currentUserId;
+	public getClientId(): Promise<string> {
+		return this.getSettingValueOrDefault(this.$staticConfig.ANALYTICS_INSTALLATION_ID_SETTING_NAME);
 	}
 
 	public getClientName(): string {
@@ -33,14 +28,8 @@ class AnalyticsSettingsService implements IAnalyticsSettingsService {
 	}
 
 	public async getUserSessionsCount(projectName: string): Promise<number> {
-		const oldSessionCount = await this.$userSettingsService.getSettingValue<number>(AnalyticsSettingsService.SESSIONS_STARTED_OBSOLETE_KEY);
-
-		if (oldSessionCount) {
-			// remove the old property for sessions count
-			await this.$userSettingsService.removeSetting(AnalyticsSettingsService.SESSIONS_STARTED_OBSOLETE_KEY);
-		}
-
-		return await this.$userSettingsService.getSettingValue<number>(this.getSessionsProjectKey(projectName)) || oldSessionCount || 0;
+		const sessionsCountForProject = await this.$userSettingsService.getSettingValue<number>(this.getSessionsProjectKey(projectName));
+		return sessionsCountForProject || 0;
 	}
 
 	public async setUserSessionsCount(count: number, projectName: string): Promise<void> {
@@ -50,5 +39,17 @@ class AnalyticsSettingsService implements IAnalyticsSettingsService {
 	private getSessionsProjectKey(projectName: string): string {
 		return `${AnalyticsSettingsService.SESSIONS_STARTED_KEY_PREFIX}${projectName}`;
 	}
+
+	private async getSettingValueOrDefault(settingName: string): Promise<string> {
+		let guid = await this.$userSettingsService.getSettingValue<string>(settingName);
+		if (!guid) {
+			guid = createGUID(false);
+
+			this.$logger.trace(`Setting new ${settingName}: ${guid}.`);
+			await this.$userSettingsService.saveSetting<string>(settingName, guid);
+		}
+
+		return guid;
+	}
 }
 $injector.register("analyticsSettingsService", AnalyticsSettingsService);

lib/services/analytics-service.ts

@@ -0,0 +1,60 @@
+import * as fs from "fs";
+import { AnalyticsBroker } from "./analytics-broker";
+
+const pathToBootstrap = process.argv[2];
+if (!pathToBootstrap || !fs.existsSync(pathToBootstrap)) {
+	throw new Error("Invalid path to bootstrap.");
+}
+
+// After requiring the bootstrap we can use $injector
+require(pathToBootstrap);
+
+const analyticsBroker = $injector.resolve<IAnalyticsBroker>(AnalyticsBroker, { pathToBootstrap });
+let trackingQueue: Promise<void> = Promise.resolve();
+
+let sentFinishMsg = false;
+let receivedFinishMsg = false;
+
+const sendDataForTracking = async (data: ITrackingInformation) => {
+	trackingQueue = trackingQueue.then(() => analyticsBroker.sendDataForTracking(data));
+	await trackingQueue;
+};
+
+const finishTracking = async (data?: ITrackingInformation) => {
+	if (!sentFinishMsg) {
+		sentFinishMsg = true;
+
+		data = data || { type: TrackingTypes.Finish };
+		const action = async () => {
+			await sendDataForTracking(data);
+			process.disconnect();
+		};
+
+		if (receivedFinishMsg) {
+			await action();
+		} else {
+			// In case we've got here without receiving "finish" message from parent (receivedFinishMsg is false)
+			// there might be various reasons, but most probably the parent is dead.
+			// However, there's no guarantee that we've received all messages. So wait some time before sending finish message to children.
+			setTimeout(async () => {
+				await action();
+			}, 1000);
+		}
+	}
+};
+
+process.on("message", async (data: ITrackingInformation) => {
+	if (data.type === TrackingTypes.Finish) {
+		receivedFinishMsg = true;
+		await finishTracking(data);
+		return;
+	}
+
+	await sendDataForTracking(data);
+});
+
+process.on("disconnect", async () => {
+	await finishTracking();
+});
+
+process.send(AnalyticsMessages.BrokerReadyToReceive);

lib/services/analytics-settings-service.ts

@@ -0,0 +1,45 @@
+import { cache } from "../../common/decorators";
+
+export class AnalyticsBroker implements IAnalyticsBroker {
+
+	@cache()
+	private async getEqatecAnalyticsProvider(): Promise<IAnalyticsProvider> {
+		return this.$injector.resolve("eqatecAnalyticsProvider");
+	}
+
+	@cache()
+	private async getGoogleAnalyticsProvider(): Promise<IGoogleAnalyticsProvider> {
+		const clientId = await this.$analyticsSettingsService.getClientId();
+		return this.$injector.resolve("googleAnalyticsProvider", { clientId });
+	}
+
+	constructor(private $analyticsSettingsService: IAnalyticsSettingsService,
+		private $injector: IInjector) { }
+
+	public async sendDataForTracking(trackInfo: ITrackingInformation): Promise<void> {
+		const eqatecProvider = await this.getEqatecAnalyticsProvider();
+		const googleProvider = await this.getGoogleAnalyticsProvider();
+
+		switch (trackInfo.type) {
+			case TrackingTypes.Exception:
+				await eqatecProvider.trackError(<IExceptionsTrackingInformation>trackInfo);
+				break;
+			case TrackingTypes.Feature:
+				await eqatecProvider.trackInformation(<IFeatureTrackingInformation>trackInfo);
+				break;
+			case TrackingTypes.AcceptTrackFeatureUsage:
+				await eqatecProvider.acceptFeatureUsageTracking(<IAcceptUsageReportingInformation>trackInfo);
+				break;
+			case TrackingTypes.GoogleAnalyticsData:
+				await googleProvider.trackHit(<IGoogleAnalyticsTrackingInformation>trackInfo);
+				break;
+			case TrackingTypes.Finish:
+				await eqatecProvider.finishTracking();
+				break;
+			default:
+				throw new Error(`Invalid tracking type: ${trackInfo.type}`);
+		}
+
+	}
+
+}

lib/services/analytics/analytics-broker-process.ts

@@ -0,0 +1,14 @@
+/**
+ * Defines messages used in communication between CLI's process and analytics subprocesses.
+ */
+const enum AnalyticsMessages {
+	/**
+	 * Analytics Broker is initialized and is ready to receive information for tracking.
+	 */
+	BrokerReadyToReceive = "BrokerReadyToReceive",
+
+	/**
+	 * Eqatec Analytics process is initialized and is ready to receive information for tracking.
+	 */
+	EqatecAnalyticsReadyToReceive = "EqatecAnalyticsReadyToReceive"
+}