Skip to content

Latest commit

 

History

History
86 lines (62 loc) · 5.12 KB

concepts.md

File metadata and controls

86 lines (62 loc) · 5.12 KB
Raw

Application Insights DotNet SDK Concepts

This lists the high level concepts of the AI DotNet SDK and links to detailed guides to help you get started.

To use the Application Insights SDK you must configure an Instrumentation Key which can be obtained from an Application Insights resource. Or you can use a Connection string to simplify the configuration of our endpoints. Both an Instrumentation Key and Connection String are provided for you on the Overivew Dashboard of your Application Insights resource.

TelemetryClient

The TelemetryClient object is the primary root object for the library. Almost all functionality around telemetry sending is located on this object.

Initialization

You must initialize an instance of this object and populate it with your Instrumentation Key to identify your data.

using Microsoft.ApplicationInsights;
using Microsoft.ApplicationInsights.Extensibility;

var configuration = new TelemetryConfiguration
{
    ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000",
};
var tc = new TelemetryClient(configuration);

Using the TelemetryClient to send telemetry

You can populate common context on the TelemetryClient.context property which will be automatically attached to each telemetry item sent. You can also attach additional property data to each telemetry item sent. The TelemetryClient also exposes several Track methods that can be used to send all telemetry types understood by the Application Insights service. Some example use cases are shown below.

Please review the full API summary for custom events and metrics for more examples.

tc.Context.Device.OperatingSystem = Environment.OSVersion.ToString();

tc.TrackTrace(message: "Custom message.");

tc.TrackEvent(
    eventName: "PurchaseOrderSubmitted", 
    properties: new Dictionary<string, string>() { { "CouponCode", "JULY2015" } }, 
    metrics: new Dictionary<string, double>() { { "OrderTotal", 68.99 }, { "ItemsOrdered", 5 } }
    );
	
try
{
    // do something
}
catch(Exception ex)
{
    tc.TrackException(ex);
}

Flushing

When your application is shutting down, we recommend Flushing the TelemetryClient to clear the buffer and prevent telemetry from being lost.

Please review our examples here: Flushing data.

Telemetry Channels

Telemetry channels are responsible for sending the telemetry data to the designated place. Optional features can be provided by the telemetry channels, for example, buffering the data and sending in them in batches, persisting the data to a local storage in case of transmission failure (e.g. network outage), traffic shaping and retry mechanisms

The .NET and .NET Core versions of the SDKs provide two built-in telemetry channels:

  • InMemoryChannel: A lightweight channel that buffers items in memory until they're sent. Items are buffered in memory and flushed once every 30 seconds, or whenever 500 items are buffered.
  • ServerTelemetryChannel: A more advanced channel that has retry policies and the capability to store data on a local disk.

Please review our full guide on Telemetry Channels in Application Insights.

TelemetryProcessors and TelemetryInitializers

You can write and configure plug-ins for the Application Insights SDK to customize how telemetry can be enriched and processed before it's sent to the Application Insights service.

Please review our full guide on Filtering and preprocessing telemetry.

Telemetry correlation

Application Insights supports distributed telemetry correlation, which you use to detect which component is responsible for failures or performance degradation.

Please review our full guide on Telemetry correlation in Application Insights.

Custom metric collection

The Azure Monitor Application Insights .NET and .NET Core SDKs have two different methods of collecting custom metrics, TrackMetric(), and GetMetric(). The key difference between these two methods is local aggregation.

Please review our full guide on Custom metric collection in .NET and .NET Core.

Sampling

Sampling is the recommended way to reduce telemetry traffic, data costs, and storage costs, while preserving a statistically correct analysis of application data.

Please review our full guide on Sampling in Application Insights.