Refactor track* API

Before we ship stable SDK I would like to refactor track API:

1. To make track* functions more consistent between themselves.
2. To allow specifying timestamp
3. To address some reported bugs such as inability to specify result code for dependencies #286 and not being able to track requests without request object #148
4. To make names consistent with property names in Portal and Analytics
5. To make API consistent with .NET API
6. To reduce the number of positional argument to the ones required, while keeping the others in TrackOptions bag.

This is the proposal:

interface TrackOptions
{
    timestamp?: Date;
    properties?: { [key: string]: string; }
    measurements?:{ [key: string]: number; }
    contextObjects?: {[name: string]: any;}
    tagOverrides?: { [key: string]: string; }
}

void trackDependency(
     dependencyTypeName: string,
     target: string,
     dependencyName: string,
     data: string,
     duration: number,
     resultCode: string
     success: bool
     trackOptions: TrackOptions);

void trackEvent(
     eventName: string,
     trackOptions: TrackOptions);

void trackTrace(
     message: string,
     severityLevel: SeverityLevel
     trackOptions: TrackOptions);

void trackMetric(
     metricName: string,
     metricValue: number
     trackOptions: TrackOptions);

void trackException(
     exception: Error,
     trackOptions: TrackOptions);

void trackRequest(
     name: string,
     duration: number,
     resultCode: string
     success: bool
     trackOptions: TrackOptions);

@OsvaldoRosado @SergeyKanzhelev @KamilSzostak

[AlexBulankou]

Discussed with Sergey and decided to do 2 changes:

1. Rename *TrackOptions-> *Telemetry for consistency with .NET and also not to introduce additional concept:

• RequestTelemetry
• DependencyTelemetry
• MetricTelemetry
• ExceptionTelemetry
• EventTelemetry
• TraceTelemetry

1. Don’t expose domain specific objects, such as http, https, http.RequestOptions in the Client API. This way API remains clean and can be easier shared with JS later on. Instead create helpers to create RequestTelemetry from req/res and DependencyTelemetry from ClientRequest With this API becomes:

class Util
{
 public createDependencyTelemetryFromClientRequest(clientRequest:http.ClientRequest|https.ClientRequest, requestOptions: http.RequestOptions|https.RequestOptions): DependencyTelemetry;
 public createRequestTelemetryFromHttpRequestAsync(httpRequest: http.Request | https.Request, httpResponse: http.Response | https.Response, onRequestComplete:()=>RequestTelemetry): void;
 public createRequestTelemetryFromHttpRequest(httpRequest: http.Request | https.Request, httpResponse: http.Response | https.Response, duration: number): RequestTelemetry;
}

interface Telemetry
{
    timestamp?: Date;
    properties?: { [key: string]: string; };
    measurements?:{ [key: string]: number; };
    contextObjects?: {[name: string]: any;};
    tagOverrides?: { [key: string]: string; };
}

interface DependencyTelemetry extends Telemetry
{
     dependencyTypeName: string;
     target: string;
     dependencyName: string;
     data: string;
     duration: number;
     resultCode: string;
     success: bool;
}

interface EventTelemetry extends Telemetry
{
     eventName: string
}

interface TraceTelemetry extends Telemetry
{
     message: string;
     severityLevel: SeverityLevel;
}

interface ExceptionTelemetry extends Telemetry
{
     exception: Error;
}

interface MetricTelemetry extends Telemetry
{
     name: string;
     value: number;
     count: number;
     min: number;
     max: number;
     stdDev: number;
}

interface RequestTelemetry extends Telemetry
{
     name: string;
     duration: number;
     resultCode: string;
     success: bool;
}

public class Client
{
  public void trackDependency(telemetry: DependencyTelemetry);
  public void trackTrace(telemetry: TraceTelemetry); 
  public void trackMetric(telemetry: MetricTelemetry);
  public void trackException(telemetry: ExceptionTelemetry);
  public void trackRequest(telemetry: RequestTelemetry);
  public void trackEvent(telemetry: EventTelemetry);
}

[AlexBulankou]

thoughts on a NodeClient that inherits from Client to have domain-specific objects rather than hiding them in Utils .

@OsvaldoRosado, I agree with this approach, this is how I’m doing it: https://github.com/Microsoft/ApplicationInsights-node.js/blob/albulank/trapi/Library/NodeClient.ts