Telemetry API

Architecture

Diagrams

Communication with other components

Diagram

File [Star UML]

8KB

TelemetryComponents.zip

archive

Application Insights

The Telemetry API creates instances of Microsoft.ApplicationInsights.TelemetryClient to communicate with the Application Insights Resource in Azure.

Hubspot

The Hubspot API can be accessed by using an Http Client. It has already been done in the Assessment API.

Assessment DB

The communication with this database will be done by using the Sql.Data namespace and the namespaces contained there. It will be a straightforward communication similar to the one that is implemented in the Assessment API.

API Methods

Post Events

POST https://telemetry-api.mobilize.net/Events

Post a batch of events that must be reported by the Telemetry API

Path Parameters

Name	Type	Description
batchOfEvents	object	A EventBatch object containing a list of events, the instrumentation key, the product name, the session guid.

200 A boolean value indicating if the batch of events was correctly processed.

true // Could also be false

Post Exception Events

POST https://telemetry-api.mobilize.net/ExceptionEvents

Post a batch of exceptions that must be reported by the Telemetry API

Path Parameters

Name	Type	Description
batchOfExceptions	object	A ExceptionEventBatch object containing a list of events, the instrumentation key, the product name, the session guid.

200

Functional Equivalence

This API should provide enough functionality to report all the events that are normally reported from the IControllerMonitor (in the Controller) and from the VBUC Telemetry.

IControllerMonitor

These are the methods included in the IControllerMonitor

/// <summary>
/// Sends the information that the execution has been requested.
/// </summary>
void ReportRequestExecutionEvent(string codeProcessorExecutionId, CodeProcessorDescriptor codeProcessorProductDescriptor);

/// <summary>
/// Sends the information needed to track the start of the execution.
/// </summary>
void ReportExecutionStartedEvent(string codeProcessorExecutionId, CodeProcessorDescriptor codeProcessorWorkerDescriptor);

/// <summary>
/// Sends the information needed to track the end of the execution.
/// </summary>
void ReportExecutionFinishedEvent(string codeProcessorExecutionId, CodeProcessorDescriptor codeProcessorWorkerDescriptor, float totalExecutionTime, ExecutionStatus executionStatus);

/// <summary>
/// Sends the license validation state.
/// </summary>
void ReportLicenseValidationEvent(string codeProcessorExecutionId, string licenseKey, bool wasSuccessful, string errorMessage = null);

/// <summary>
/// Sends the current license model.
/// </summary>
void ReportLicenseDataEvent(string codeProcessorExecutionId, ILicenseModel data);

/// <summary>
/// Sends the state of a license activation/installation.
/// </summary>
void ReportLicenseActivationEvent(string codeProcessorExecutionId, string licenseKey, bool wasSuccessful, string errorMessage = null);

/// <summary>
/// Sends the code processor validation state, also the execution parameters.
/// </summary>
void ReportParametersValidationEvent(string codeProcessorExecutionId, bool wasSuccessful, string requestedExecutionMode, Dictionary<string, string> additionalParameters, string errorMessage = null);

/// <summary>
/// Track important metrics from the code to be processed.
/// </summary>
void ReportCodeMetricsEvent(string codeProcessorExecutionId, CodeDescriptor codeDescriptor);

/// <summary>
/// Sends the exception details.
/// </summary>
void ReportErrorEvent(string codeProcessorExecutionId, Exception exception, string details = null);

/// <summary>
/// Sends the fingerprint of the input
/// </summary>
/// <param name="codeProcessorExecutionId"></param>
/// <param name="fingerprint"></param>
void ReportFingerprintEvent(string codeProcessorExecutionId, string fingerprint);

VBUC Telemetry

The Telemetry in the VBUC requires a Telemetry Client with the ability to Track Events.

Future Work

• In the future we can implement more methods for the API, maybe PageView tracking, and similar methods.

• In the future we could implement versioning.

Challenges

Windows XP Compatibility

A POC has been generated in order to validate that it.

Versioning

Versioning will not be implement for the first version of the API. In the future we can evaluate this option.

Security

We could, in the future, implement Authentication and Authorization flows. Also, this API must accept connections with TLS 1.0, which could be insecure. This only affects Windows XP because Windows XP does not support TLS 1.1 or better. The data sent from the Telemetry Monitor in Windows XP could technically be intercepted (with a Man-in-the-Middle attack, specifically a POODLE attack, see https://en.wikipedia.org/wiki/POODLE).

Performance

• It is necessary to send events in a batch (every 30 seconds or something like that)

• An option to flush the events should also be given

• We must think about the way in which the batch will work if there is an error/the application is closed

• The events might be grouped

Instrumentation Key

We will be sending both the product name (in order to have a template method) and an instrumentation key (to be more flexible).

Will this Telemetry API be called from the front-end (Angular)?

Not at the moment.

What are the requirements that we have to address?

Mainly the functional equivalence with VBUC and the IControllerMonitor.

Assessment DB Insertion

We will insert data into the Assessment DB. We need to map the Sessions, Events & Attributes from the Telemetry API into some tables in the Assessment DB. We will not generate an Assessment Model in the VBUC Client, it will be generated in the Telemetry API.

Tables

• TelemetrySession

  • Id

  • SessionID (GUID)

  • ProductSessionId

• TelemetryEvent

  • Id

  • TelemetrySessionId

  • Name

  • Sequence

  • ClientTimestamp

  • ServerTimestamp

• TelemetryEventAttribute

  • Id

  • TelemetryEventId

  • Name

  • Value

How to relate the assessment info with the telemetry info?

Whenever an upload introduces a new TelemetrySession (in the Telemetry API), it is necessary to look for a ProductSession with the same SessionID (GUID) as the new TelemetrySession. If a ProductSession fulfills that requirement, then it must be associated to the TelemetrySession (with the ProductSessionId column).

Whenever an upload introduces a new ProductSession (in the Assessment API), it is necessary to look for a TelemetrySession with the same SessionID (GUID) as the new ProductSession. If TelemetrySession fulfill that requirement, then it must be associated to the ProductSession (with the TelemetrySession.ProductSessionId column).

Whenever a JOIN is performed over TelemetrySession and ProductSession, it is preferred to use the SessionId columns in both tables (the creation of an Index in both tables is recommended for better performance, since these columns are not Primary Keys nor Foreign Keys). This JOIN could also be performed by using the TelemetrySession.ProductSessionId and the ProductSession.Id columns, as one would normally do. However, there is a very small chance that there will be false positives in this case (if the the ProductSession was not associated to the TelemetrySession, for any kind of reason, such as dirty reads, for instance).

How high level will this API be?

• The methods will be as generic as possible

  • They will receive the product name and instrumentation key

  • We can also use a Template Method design pattern, similar to the one we have in the Assessment API, and change the behavior depending on the product name/version