Trakerr - C# API client

Get your application events and errors to Trakerr via the Trakerr API.

You can send both errors and non-errors (plain log statements, for example) to Trakerr with this API.

Overview

The 3-minute guide is primarily oriented around sending errors or warnings and also do not allow sending additional parameters. Option-3 in the detailed integration guide describes how you could send a non-error (or any log statement) along with additional parameters.

The SDK takes performance impact seriously and all communication between the SDK <=> Trakerr avoids blocking the calling function. The SDK also applies asynchronous patterns where applicable.

A Trakerr Event is what is created by this SDK and is then sent to Trakerr for Trakerr to capture. A Trakerr Event can consist of various parameters as described here in Model.AppEvent. Some of these parameters are populated by default and others are optional and can be supplied by you.

Since some of these parameters are common across all event's, the API has the option of setting these on the TrakerrClient instance (described towards the bottom) and offers a factory API for creating AppEvent's.

Key AppEvent Properties

Log Level, Event Type and Classification

Log Level This enum specifies the logging level to be used for this event ('debug','info','warning','error' or 'fatal')
Event Type This defines the type of event or logger name. This is automatically set for errors.
Classification This is a user settable property that controls how the events are grouped. Defaults to 'Issue'. Set this to a different value to group this event in a different group.

Event User, Event Session and Correlation ID

Event User This is the user that is associated with this event. This can be any user data or could be encrypted if privacy is required.
Event Session This is any session specific information associated with this event.
Cross App Correlation ID This is an additional ID that can be used for cross-application correlation of the same event.

Operation Time

Operation Time This property in milliseconds measures the operation time for this specific event.

Custom properties and segments

In addition to the above, you can use custom properties and segments to send custom event, performance data. These can then be visualized in Trakerr's dashboards.

Frameworks supported

.NET 4.0 or later
Windows Phone 7.1 (Mango) and later.

Install SDK dependency using Nuget

IO.TrakerrClient - 1.0.0 or later

The DLLs included in the package may not be the latest version. We recommend using [NuGet] (https://docs.nuget.org/consume/installing-nuget) to obtain the latest version of the packages:

Install-Package IO.TrakerrClient

3-minute Integration Guide

Using App.config for configuration

First setup a sample application and setup App.config to include your API key (see TrakerrSampleApp project for an example).

<configuration>
...
    <appSettings>
      <add key="trakerr.apiKey" value="<api-key>" />
      <add key="trakerr.url" value="https://trakerr.io/api/v1/" />
      <add key="trakerr.contextAppVersion" value="1.0" />
      <add key="trakerr.deploymentStage" value="development"/>
    </appSettings>
</configuration>

To send an exception to Trakerr, it's as simple as calling .SendToTrakerr() on the exception (see example below).

    using IO.TrakerrClient;
    ...
    try
    {
        throw new Exception("This is a test exception.");
    }
    catch (Exception e)
    {
        // Send the event to Trakerr
        e.SendToTrakerr();
    }

Without App.config for configuration

    using IO.TrakerrClient;
    using IO.Trakerr.Model;
    ...

    // specify config (without App.config)
    var trakerrClient = TrakerrClient(
        "<api-key>",                // API KEY
        "1.0",                      // Your application version (any string)
        "production"                // Any custom deployment stage string ("production", "development", "staging" etc.)
    );

    try
    {
        throw new ArgumentException("Args are invalid.");
    }
    catch (Exception e)
    {
        // You can optionally specify the log level, along with the classifcation in the SendException parameters.
        // See C# documentation of SendException for more details.
        trakerrClient.SendException(e);
    }

Trakerr Client Shutdown

When cleaning up your application, or implementing a shutdown, be sure to call

TrakerrClient.Shutdown(false);

This will close the CPU monitoring thread gracefully. If an error has occurred; passing true will force thread abort. Do not pass true unless absolutely necessary.

Detailed Integration Guide

Option-1: Send an exception to Trakerr

Use the guide 3-minute integration guide above to send an exception to Trakerr.

Option-2: Send an exception with user, session, custom properties and more

Calling CreateAppEvent with an exception as shown below automatically populates the stacktrace information to send to Trakerr.

This call will create a new Model.AppEvent. You can then populate other member data to send to Trakerr using accessors (see Model.AppEvent for more details on properties that you can set).

    using IO.TrakerrClient;
    using IO.Trakerr.Model;
    ....

    // Instantiate the TrakerrClient globally somewhere and store. This is thread-safe.
    // Specify config without App.config (OR if using App.config you can use the parameterless constructor instead)

    var trakerrClient = TrakerrClient(
        "<api-key>",                // API KEY
        "1.0",                      // Your application version (any string)
        "production"                // Any custom deployment stage string ("production", "development", "staging" etc.)
    );

    ....

    try
    {
        throw new IndexOutOfRangeException("Buffer overflow.");
    }
    catch (Exception e)
    {

        var appevent = trakerrClient.CreateAppEvent(
            e,                                  // the exception to send to Trakerr
            AppEvent.LogLevelEnum.Fatal,        // the log level indicating FATAL
            "Issue"                             // the classification indicating an "Issue"
        );

        // You can set properties on AppEvent below like user, session, custom properties and more.
        appevent.EventUser = "john@trakerr.io";
        appevent.EventSession = "8";
        appevent.appevent.ContextOperationTimeMillis = 1000;

        // Set some custom data
        appevent.CustomProperties = new CustomData();
        appevent.CustomProperties.StringData = new CustomStringData("This is string data 1!");//Add up to 10 custom strings.
        appevent.CustomProperties.StringData.CustomData2 = "This is string data 2!";//You can also add strings later like this.

        // opulate any other data you want, customdata or overriding default values of the appevent.
        trakerrClient.SendEventAsync(appevent);
    }

Option-3: Send an event (including non-exceptions) with user, session, custom properties and more

You can send non-errors to Trakerr. This will send an event without a stacktrace.

This creates a new Model.AppEvent using CreateAppEvent. You can then populate other member data using accessors (see Model.AppEvent for more details on properties that you can set).

    using IO.TrakerrClient;
    using IO.Trakerr.Model;

    ...

    // Instantiate the TrakerrClient globally somewhere and store. This is thread-safe.
    // Specify config without App.config (OR if using App.config you can use the parameterless constructor instead)

    var trakerrClient = TrakerrClient(
        "<api-key>",                // API KEY
        "1.0",                      // Your application version (any string)
        "production"                // Any custom deployment stage string ("production", "development", "staging" etc.)
    );

    ....

    // Create an event and then send it to Trakerr
    var infoevent = trakerrClient.CreateAppEvent(
        AppEvent.LogLevelEnum.Info,     // log level (logLevel in API)
        "Database",                     // classification -- user defined (classification in API)
        "MySQL.INSERT",                 // type -- user defined (eventType in API)
        "Success inserting data"        // some message -- user defined (eventMessage in API)
    );

    // You can set properties on AppEvent below like user, session, custom properties and more.
    infoevent.EventUser = "jill@trakerr.io";
    infoevent.EventSession = "2";

    // Set some custom data like database instance connected to and database region
    infoevent.CustomProperties = new CustomData();
    infoevent.CustomProperties.StringData = new CustomStringData("east.mysql.trakerr.com");//Add up to 10 custom strings.
    infoevent.CustomProperties.StringData.CustomData2 = "region-1"; //You can also add strings later like this.

    // Populate any other data you want, customdata or overriding default values of the appevent.
    trakerrClient.SendEventAsync(infoevent);

About TrakerrClient's properties

The TrakerrClient class above can be constructed to take aditional data, rather than using the configured defaults. The constructor signature is:

public TrakerrClient(string apiKey = null, string contextAppVersion = null, string contextDeploymentStage = null, string contextEnvLanguage = "C#")

The TrakerrClient class also has a lot of exposed properties. The benefit to setting these immediately after after you create TrakerrClient is that AppEvent will default it's values against the TrakerClient that created it. This way if there is a value that all your AppEvents uses, and the constructor default value currently doesn't suit you; it may be easier to change it in TrakerrClient as it will become the default value for all AppEvents created after. A lot of these are populated by default value by the constructor, but you can populate them with whatever string data you want. The following table provides an in depth look at each of those.

If you're populating an app event directly, you'll want to take a look at the AppEvent properties as they contain properties unique to each AppEvent which do not have defaults you may set in the client.

Name	Type	Description	Notes
apiKey	string	API Key for your application.	Defaults to reading "trakerr.apiKey" property under appSettings from the App.config.
contextAppVersion	string	Provide the application version.	Defaults to reading "trakerr.contextAppVersion" property under appSettings from the App.config.
contextDevelopmentStage	string	One of development, staging, production; or a custom string.	Default Value: trakerr.deploymentStage or "development" if not provided.
contextEnvLanguage	string	Constant string representing the language the application is in.	Default value: "C#", can be set by the constructor if your using VB or managed C++.
contextEnvName	string	Name of the CLR the program is running on	Defaults to returning "Microsoft CLR" if using .Net framework or "Mono" if mono.
contextEnvVersion	string	Provide an environment version.	Defaults to reading to the CLR version of .net, or uses reflection to find the mono version.
contextEnvHostname	string	Provide the current hostname.	Defaults to the current DNS name if available or uses the Machine name as a fallback.
contextAppOS	string	Provide an operating system name.	Defaults to Environment.OSVersion.Platform along with the service pack (eg. Win32NT Service Pack 1).
contextAppOSVersion	string	Provide an operating system version.	Defaults to Environment.OSVersion.Version.ToString() (eg. 6.1.7601.65536).
contextAppOSBrowser	string	An optional string browser name the application is running on.	Defaults to `null`
contextAppOSBrowserVersion	string	An optional string browser version the application is running on.	Defaults to `null`
contextDataCenter	string	Data center the application is running on or connected to.	Defaults to `null`
contextDataCenterRegion	string	Data center region.	Defaults to `null`
contextAppSKU	string	Application SKU context.	Defaults to `null`
contextTags	List	Any tags that describe the the module that this handler is for.	Defaults to `null`

Documentation for Models

Model.AppEvent

trakerr-com / trakerr-csharp