Recording Custom .NET Metrics

Below will outline the process of monitoring custom metrics from your .NET apps in Stackify.

Add StackifyLib Using NuGet

Our open source project, StackifyLib, has support for reporting custom metrics to Retrace.

Add StackifyLib to your project via the package manager or via the Visual Studio user interface.

PM> Install-Package StackifyLib

Note: If you are also sending logs to Retrace for log4net, NLog, or Serilog, you would already have StackifyLib added to your project.

Configure Your Application

StackifyLib requires adding your Retrace activation key, application name, and environment name to the configuration of your application. This is used to register and identify your account and application.

<appSettings>
    <add key="Stackify.ApiKey" value="Your Activation Key" />
     <add key="Stackify.AppName" value="Your App Name"/>
    <add key="Stackify.Environment" value="Your Environment"/>
</appSettings>

A Basic Example

Now, let's say you want to track how many times users log in across your entire system. You can do that with one line of code on your login page. Every time this method is called, our library increments an internal counter and once a minute reports to us the total of how many times the event happened per minute.

StackifyLib.Metrics.Count("Users", "Login Success", autoReportZeroIfNothingReported:true);

This line of code specifies the metrics category ("Users"), the measure ("Login Success"), and by default increments the counter by 1 (you can provide a third parameter to specify how much to increment by instead as well).

Metrics API Methods

Metrics are reported to Stackify once a minute. They are only reported if you log a value within that minute time frame. See advanced settings below about overriding that default behavior. All metrics have a category and metric name. It is recommended to group similar metrics under a single category so they show together in the UI.

Average

The average of all values submitted are reported in a 1 minute time frame.

StackifyLib.Metrics.Average("Logs API", "Incoming App Log Count Avg", messages.Length);

Count

Count is used to track the rate of how many times an event occurs within a minute. For example, every time you read a message off a queue or a specific piece of code is called, Count will report the rate that an event occurs over a 1 minute time frame.

StackifyLib.Metrics.Count("Logs API", "Incoming App Log Count", messages.Length, autoReportZeroIfNothingReported:true);

CountAndTime

The CountAndTime metric performs both the count and time operations. Note: CountAndTime will report two different items in the dashboard: the count metric uses the metric name supplied, and the word “Time” is appended to the end of the metric name for the time metric.

StackifyLib.Metrics.CountAndTime("Logs API", "Save to Elasticsearch", timeSpan);

IncrementGauge

IncrementGauge is used to increment a gauge type metric up or down by a specified value. This could be useful in reporting the number of connections.  For example, every time a connection was opened or closed a value would be incremented or decremented to the gauge. IncrementGauge reports the last value in a minute time frame after being incremented.

StackifyLib.Metrics.IncrementGauge("Connections", "Current Count", 1);

SetGauge

SetGauge is used to set a gauge type mode where you want to report a specific value. For example, you could set a gauge for the current number of connections to a database or for the number of messages in a queue. This does not do any form of averaging of the values. SetGauge reports the last value in a minute time frame.

StackifyLib.Metrics.SetGauge("Connections", "Current Count", 11);

Sum

The sum of all values submitted are reported in a 1 minute time frame. Similar to Count().

StackifyLib.Metrics.Sum("Logs API", "Incoming App Log Count", messages.Length);

Time

Time is used to track how long something takes to occur. For example, it will track how long a specific method takes to execute. Time reports the average of the values submitted in a 1 minute time frame.

Stopwatch sw = new Stopwatch();
sw.Start();
//do some stuff
sw.Stop();

StackifyLib.Metrics.Time("Logs API", "Process Logs", sw.Elapsed);

Advanced Settings

The API provides a MetricSetting class that can be used on all the metrics to control how the metrics will be reported in Retrace. By default, the library only reports metrics if a value was submitted within a given minute time span.  If no metrics were reported to the library for that minute, however, no data will show in the App Dashboard.

To change the default behavior, you can make some alterations in the custom metrics code for each category depending on how you want your custom metrics to be reported in the App Dashboard.  There are two properties that can be set that will instruct the library to report a metric every minute even if you do not report any values. Applying these properties is done by changing the default settings in the API to AutoReportZero or AutoReportLastValue.  Below will describe what these settings mean and when they may be useful.

Example of using MetricSetting for advanced options.

MetricSetting ms = new MetricSetting();
ms.AllowNegativeGauge = false;
ms.AutoReportLastValueIfNothingReported = true;
ms.AutoReportZeroIfNothingReported = true;

StackifyLib.Metrics.Average("category", "metricName", 1, ms);

AutoReportZero

By changing the defaults to AutoReportZero, the way the metrics are reported are shown differently.  When no metric data is sent to Stackify, the data will be reflected as a zero.  This setting could be useful, for example, if using a Count custom metric category to measure the rate that something is being processed and you want a “0” to be reported when there is no activity for that metric. (With AutoReportZero settings you could also set up alerts to notify you when the result is 0 by configuring App monitoring).

AutoReportLast

This setting follows the same principle, except that when no metric data is sent to Retrace, the data will be reflected as the same value as the minute before.  An example where this might be useful would be when using a gauge type metric and you do not want the value to be reset when no metric data is recorded.

Keeping the Default Settings

Although these settings can alter how the “0’s” are reported, there may be times when the Default settings would be most appropriate.   For example, you might want to track some kind of maintenance job that happens only a few times a day.  In order to get more accurate trending results, you will not want data to be reported when the job is not running.