TypeCobol Telemetry

Introduction

TypeCobol solution includes an Analytics class library project which acts like a wrapper for sending Analytics to a desired Analytics receiver (Application Insights, Google Analytics, Kibana...). For now, we only support the use of Microsoft Azure Application Insights. In this documentation, you will find some information about the Analytics Wrapper architecture and usage. Please note that all the datas are sent anonymously.

Hint

It's important to notice that Telemetry is off by default.
In order to enable Telemetry use option --Telemetry or simply -t when calling CLI/Deamon.

---

Summary

• Config file
• Singleton pattern
• Wrapper
  • Data Anonymization
  • Methods
    • TrackEvent
    • TrackException
    • TrackTrace
    • EndSession
    • SendMail

---

Config File

Analytics project use an App.Config file containing Keys and Values to send emails, to set TypeCobol project version and Analytics token. This file has been set with default value that needs to be replaced with your own configuration.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
      <add key="SmtpServer" value="your.smtp.server" />
      <add key="SmtpPort" value="25" />
      <add key="SmtpUseDefaultCredential" value="true" />
      <add key="MailReceiver" value="[email protected]" />
      <add key="MailSubject" value="TypeCobol Error" />
      <add key="TypeCobolVersion" value="1.0.0" />
      <add key="AppInsightKey" value="API Key for Azure Application Insights"/>
   </appSettings>
</configuration>

---

Singleton Pattern

In order to have an unique instance to send data to an Analytics provider, we used a Singleton Pattern based on .NET 4.0 Lazy<T>. Its provide a simple way to initialize AnalyticsWrapper.

public sealed class AnalyticsWrapper {
	private static readonly Lazy<AnalyticsWrapper> _LazyAccess = new Lazy<AnalyticsWrapper>(() => new AnalyticsWrapper()); //Singleton pattern
	public static AnalyticsWrapper Telemetry { get { return _LazyAccess.Value; } 
	
        private AnalyticsWrapper() {
	        //Init Telemetry here
        }
}

All the public methods are accessible only by using the static instance named Telemetry

AnalyticsWrapper.Telemetry.AnyMethod();

Analytics Wrapper

Analytics Wrapper is composed of different methods to send data : TrackEvent(), TrackException(), TrackTrace(), SendMail() and EndSession(). All these methods will accessile by using AnalytisWrapper.Telemetry instance. All the data transmited by the current Analytics Wrapper are anonymous. We don't want to push any sensitive data onto external cloud services.

Data Anonymization

In order to secure the data sended to external services like Azure, or Google Cloud, we force Application Insights SDK properties to be set to fake data. We also hide our user id by using an SHA-256 Hash algorithm. You could simply find this specifications in AnalyticsWrapper constructor.

// ----- Initiliaze AppInsights Telemetry Client -------//
     _TelemetryClient = new TelemetryClient(new TelemetryConfiguration(appKey));
     _TelemetryClient.Context.User.Id = CreateSHA256(Environment.UserName);
     _TelemetryClient.Context.Session.Id = Guid.NewGuid().ToString();
     _TelemetryClient.Context.Component.Version = typeCobolVersion;
     _TelemetryClient.Context.Device.OperatingSystem = "N/A";
     _TelemetryClient.Context.Location.Ip = "N/A";
     _TelemetryClient.Context.Cloud.RoleInstance = "N/A";
     _TelemetryClient.Context.Cloud.RoleName = "N/A";
     _TelemetryClient.Context.Device.Type = "N/A";
// --------------------------------------- //

Available Methods

TrackEvent

In order to track an event by giving a name to this event you can use the following syntax :

AnalyticsWrapper.Telemetry.TrackEvent("Event name");

TrackException

You can also track an exception by using TrackException(Exception ex) method :

try {
    //Something that is going to crash...
 }
catch(Exception ex) {
    AnalyticsWrapper.Telemetry.TrackException(ex);
 }

TrackTrace

A trace is really similar to an event execpt tha fact it could include a severity level. For now, we only create trace that are in Error severity level. For our own use with Application Insights its allows us to track specific diagnostics generated during parsing.

AnalyticsWrapper.Telemetry.TrackTrace(dignostic.data);

EndSession

This method is only usefull for Application Insights, it's called by the end of Deamon.cs in order to flush the in-memory and force datas to be sent. It could delay the application closure if lots of data need to be send.

AnalyticsWrapper.Telemetry.EndSession();

SendMail

The send mail function allows TypeCobol parser to send an email with exception's details attached to a TypeCobol source file. All the smtp configuration, as mentionned before, resides in App.config file. The email's body is based on a HTML content, that could be found in Templated folder of Analytics project.

AnalyticsWrapper.Telemetry.SendMail(typeCobolException, config.InputFiles, config.CopyFolders, config.CommandLine);