Here I introduce the pre-release version of the Microsoft Azure Metrics SDK. I give a brief overview of the feature set and then provide a number of usage examples as a tutorial for the API surface. The goal of this publication is to collect feedback on the API surface and on the implementation strategy.

The goal of the Azure Metrics SDK is to provide an API for metric pre-aggregation and metric ingestion into Azure. In the current pre-release version we target the Application Insights ingestion endpoint. However, the SDK is designed with minimal dependencies on the Application Insights Core SDK. It is structured to be naturally used to submit preaggregated metrics to other endpoints. In the mid- to long-term, a subset of the features may be moved into more platform-level .Net APIs.

Metrics, once emitted by the source application, are always a conceptually aggregated quantity. Specific metric measurements should never be sent or stored in the original, non-aggregated form. Once the APIs discussed here reach a stable public release, the Application Insights TelemetryClient.TrackMetric(..) API should be deprecated. Advanced developers wishing to implement their own pre-aggregation logic should use TelemetryClient.Track(ITelemetry) API to send any telemetry that results from their custom aggregation. Developers who want to send specific single-point measurements should use Events.

Currently the SDK offers the following features:

• Different kinds of aggregators:
-- Measurements
-- Counters
-- Custom aggregators

• Zero-dimensional and multi-dimensional metrics:
-- Local metric series capping
-- Local dimension cardinality capping
-- Support for dynamic discovery of dimension values.

• Data introspection: applications can reason about their own telemetry.

• Support for centrally configured aggregation.

• APIs structure is layered:
-- Low level APIs are optimized for performance and memory consumption. Aggregation is lock-free and GC-friendly.
-- Convenience APIs are discoverable and provide a smooth learning curve.

• Support for QuickPulse/LiveMetrics.

• Support for custom aggregation cycles, data filters, value filters.

• Support for unit and integration of metrics-emitting code.

Currently the Azure Metrics SDK is available as source code in the ApplicationInsights-SDK-Labs repo on GitHub in the branch metrics/master. Direct link:
https://github.com/Microsoft/ApplicationInsights-SDK-Labs/tree/metrics/master

We will be starting work to move it into the ApplicationInsights-dotnet repo soon.

What follows is a series for code-samples and mini-totorials that explain the APIs, starting for the very basics, all the way to more advanced use cases. Instead of pasting it all here, please take a look at this file:
https://github.com/Microsoft/ApplicationInsights-SDK-Labs/blob/metrics/master/Metrics/Tests/Microsoft.ApplicationInsights.Metrics.Convenience.Test/Examples.cs

All examples are maintained there and updated when SDK APIs are updated. The examples can be built and run. Please pay attention to the comments in the examples. You can consider them as a continuation of this post.
Here is a list of the topics you will find there:

// *** SENDING METRICS ***
// *** MEASUREMENTS AND COUNTERS ***
// *** MULTI-DIMENSIONAL METRICS ***
// *** ACCESSING METRIC DATA SERIES ***
// *** WORKING WITH THE EMITTED METRIC DATA ***
// *** ADDITIONAL DATA CONTEXT ***
// *** SEPARATION OF CONCERNS: TRACKING METRICS AND CONFIGURING AGGREGATIONS ARE INDEPENDENT ***
// *** CUSTOM METRIC CONFIGURATIONS ***
// *** MANUALLY CREATING METRIC SERIES WITHOUT THE CONTEXT OF A METRIC ***
// *** FLUSHING ***
// *** AGGREGATION SCOPE ***
// *** UNIT TESTS: CAPTURING APPLICATION INSIGHTS TELEMETRY BY INJECTING A TELEMETRY CLIENT ***
// *** UNIT TESTS: CAPTURING APPLICATION INSIGHTS TELEMETRY BY SUBSTITUTING THE TELEMETRY CHANNEL ***
// *** UNIT TESTS: CAPTURING METRIC AGGREGATES ***
// *** Running it all ***

Thank you!