Azure Metrics SDK, version Alpha 0.1: request for feedback.

[macrogreg]

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!

[macrogreg]

@SergeyKanzhelev @Dmitry-Matveev @vitalyf007 @anurse @vancem @tokaplan @zakimaksyutov

[zakimaksyutov]

I think we'll go in deep details a bit later. Here is one very small tactical question. I noticed that we're introducing a class which allows tracking objects, including tracking strings (by doing Double.TryParse). Do we need to do it? Can we limit API surface to double (int?) and reduce the code we will have to maintain?

I'm not sure I'm sold that we should provide API which will allow usage like this:

metric.Track("135.45")

[macrogreg]

@zakimaksyutov , good question.
The reason this overload exists is that we will need to support distinct count aggregations going forward. D-counts are usually an aggregate of data points represented by strings, not numbers. That is why the generic interface has the two overloads. And the measurement merely does the "sensible" thing by trying to parse the strings to numbers.

The trouble is that interfaces are not version-able and we would not be able to have only the numeric Track method now and add the object overload later.

There is, however, another way to do distinct counts - by counting dimension values rather than metric values. Let me see if processing folks can provide some information of whether they have definite plans on what option they will pick. Maybe we can simplify.

[cijothomas]

@macrogreg https://github.com/Microsoft/ApplicationInsights-SDK-Labs/blob/metrics/master/Metrics/Tests/Microsoft.ApplicationInsights.Metrics.Convenience.Test/Examples.cs This links to examples seem to be dead? Can you post updated one?

[cijothomas]

https://github.com/Microsoft/ApplicationInsights-dotnet/pull/735/files#diff-e461f8c0e583f7733b3c5cf55863af0d got it.

[macrogreg]

@cijothomas , correct. :)
I will move the tests into another directory soon, to adjust with the folder structure in the Core SDK repo. I'll post an updated link.

[macrogreg]

Latest examples:
https://github.com/Microsoft/ApplicationInsights-dotnet/blob/feature/PreAggMetrics.Master/Test/Microsoft.ApplicationInsights.Test/Shared/Metrics/MetricsExamples.cs

[TimothyMothra]

@macrogreg can this be closed because it's already shipped with 2.6.0-Beta3

[macrogreg]

Yes.