Application Insights SDK (0.11.0-prerelease)

Joshua Weber-MSFT

What is it?

Application Insights SDK lets you send telemetry to the Application Insights portal, where you can find out what users are doing with your application.

0.11.0 is the latest SDK release for Application Insights. This SDK includes new functionality and new concepts in addition to a change to the API. For information on the previous 0.10 release please read this blog post.

Data sent through this SDK will only be visible through the Microsoft Azure Preview Portal. (Previous versions sent data to an earlier edition of Application Insights, accessed through Visual Studio Online.) To find out more information about the different versions of Application Insights please see the documentation.

You can instrument these types of application:

1. ASP.NET web applications hosted either on premises or in Microsoft Azure.
2. Windows Phone 8.0 (Silverlight) and 8.1 (Silverlight and WinRT) – UI experience is coming soon.
3. Windows Store 8.1 applications – UI experience is coming soon.
4. Logging frameworks – Capture and search trace logging messages from multiple popular logging frameworks:
   • System.Diagnostics.Trace
   • Nlog
   • Log4Net
   • Application Insights tracing API
5. Web pages – Insert Javascript to instrument client side web code.

The easiest way to acquire the AppInsights SDK is to add it to your project using Visual Studio 2013 Update 3. Alternatively, you can manually add the NuGet packages from the public NuGet feed. For more information see Getting Started with Application Insights.

Preview NOTE

This SDK is currently in a NuGet pre-release state. It includes new concepts and a new coding experience. Its API is evolving and will probably change in the future based on early adopter feedback.

What is new?

The 0.11 SDK includes a new simpler Telemetry API, automatic JavaScript error collection, and enhancement to trace telemetry collection. It also includes a number of bugs fixes and additional improvements.

New Simpler Custom Telemetry API

As part of the 0.11 release we have introduced a simplified API. Our previous proposed API was not as quick and simple as we had hoped. To improve upon this we have modified the API to help simplify the coding experience and help new customers get up to speed quicker.

The primary change is the move to a single class in the root namespace, Microsoft.ApplicationInsights.TelemetryClient. This single class should meet the majority of your telemetry instrumentation needs. The TelemetryClient object exposes a set of Track methods. These Track methods represent all of the core telemetry item types Application Insights understands. After instantiation of a new TelemetryClient object, you should be able to send most telemetry through single method calls. In addition to the basic calls below, all track methods have more complex signatures allowing capture of additional custom properties for more advanced scenarios.

var tc = new TelemetryClient();

tc.TrackEvent("SampleEvent");
tc.TrackTrace("Simple Trace Log Message");
tc.TrackMetric("BasicMetric", 42);
catch (Exception e)
{
    tc.TrackException(e);
}

The TelemetryClient also exposes a context property member. The fields on this property represent the common set of properties that will be automatically attached to all telemetry sent through this instance of a TelemetryClient. This enables you to set common property values once, to be applied to all telemetry. Examples showing setting of both standard and custom properties are shown below.

tc.Context.User.AccountId = "My Customer AccountID";
tc.Context.Properties["CustomTrackingProperty"] = "OCT2014";

NOTE: Breaking Change – This API is a breaking change from previous versions. If using a previous version you will need to modify existing code to use the new 0.11 version.

JavaScript automatic error collection

The 0.11 SDK release includes enhancements to the JavaScript SDK. The JS SDK will now automatically collect all unhandled JavaScript exceptions. On a modern browser, the call stack will also be collected. In the screenshot below you can see a simple example of a call to a non-existent function in JavaScript and the details caught and reported to Application Insights. In addition you can see that this exception collected and reported in a common way with unhandled exceptions caught by the .Net Application Insights SDKs.

All you need to do to make use of this functionality is ensure that you have the latest update to the 0.11 JS SDK script tag. The easiest way to obtain the new snippet is from the Getting Started page in the portal.

Enhanced Trace Collection

Trace collection has been enhanced to match the schema and processing of the other telemetry types. All types are now consistently handled in the UI to enable a common experience across all your telemetry data.

NOTE: Breaking Change – The change of trace schema is a breaking change. If you were using trace collection before you will need to update to version 0.11 or later to continue to view your trace telemetry. The quickest way to upgrade is to utilize NuGet package management to upgrade your SDK NuGets and your trace adapters to the latest 0.11 release.

Joshua Weber-MSFT

Follow