Below will outline the process of monitoring custom metrics from your .NET apps in Stackify.
Getting the Metrics API Using NuGet
Using NuGet from Visual Studio, it’s easy to add the Stackify API for Custom Metrics. If you just want Metrics, you can download the Stackify API. If you are integrating Stackify’s Error or Logging Appender into your project as well, you will find that Custom Metrics is already included, so no need to add the Stackify API library separately.
Configuring with NuGet
In order for the NuGet installation to complete, copy your Stackify Activation Key (license key) from your Retrace account page and paste it here. Once this is complete, you are done with the installation and configuration of the Stackify API and can begin using it.
A Note Before Starting…
At present, Retrace can only display custom metrics for apps that appear in the Web Apps list – this list is populated via auto-discovery of apps by the agent on your servers. If you log custom metrics from an app running on unmonitored servers, you won’t see that app or its metrics.
A Basic Example
To begin, add a reference to the StackifyLib namespace.
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");
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.
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.
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.
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.
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.
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.
Here’s a quick sample to make this a little clearer:
DateTime startTime = DateTime.UtcNow; // Do a bunch of stuff... Metrics.Time("Category", "Metric", startTime);
The API provides a MetricSettings class that can be used on all the metrics to control how the metrics will be reported in Stackify.
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.
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).
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.