Timers

A Timer is a combination of a Histogram and a Meter allowing us to measure the duration of a type of event, the rate of its occurrence and provide duration statistics. For example, the AspNet Middleware Extension provides the ability to record a timer per endpoint as show shown in the JSON example below.

Using Timers

Timers can be recorded by either passing an action into the Time method or by using a using statement as show below. When a using statement is used the Timer will end recording upon disposing.

var requestTimer = new TimerOptions
{
    Name = "Request Timer",
    MeasurementUnit = Unit.Requests,
    DurationUnit = TimeUnit.Milliseconds,
    RateUnit = TimeUnit.Milliseconds
};

_metrics.Measure.Timer.Time(requestTimer, () => PerformRequest());

// OR

using(_metrics.Measure.Timer.Time(requestTimer))
{
    PerformRequest();
}

Timers, like Histogram also allow us to track the min, max and last value that has been recorded in cases when a "user value" is provided when recording the timer. For example, when timing requests where the endpoint has couple of features flags implemented, we could track which feature flag as producing the min and max response times. 

using(_metrics.Measure.Timer.Time(requestTimer, "feature-1"))
{
    PerformRequest();
}

Which for example when using the JSON formatter would result in something similar to:

{
    "context": "Application",
    "timers": [
        {
            "activeSessions": 0,
            "count": 20,
            "durationUnit": "ms",
            "histogram": {
                "lastUserValue": "feature-1",
                "lastValue": 308.5304,
                "max": 637.3094,
                "maxUserValue": "feature-1",
                "mean": 269.0895,
                "median": 246.0747,
                "min": 135.0442,
                "minUserValue": "feature-2",
                "percentile75": 331.6821,
                "percentile95": 424.2902,
                "percentile98": 424.2902,
                "percentile99": 637.3094,
                "percentile999": 637.3095,
                "sampleSize": 20,
                "stdDev": 108.9519,
                "sum": 5595
            },
            "rate": {
                "fifteenMinuteRate": 0.0018,
                "fiveMinuteRate": 0.0001,
                "meanRate": 0.0001,
                "oneMinuteRate": 5.1076
            },
            "rateUnit": "ms",            
            "name": "GET api/values",
            "unit": "Requests"
        }
    ]
}
Note

When reporting metrics with counts we should keep in mind that they are a cumulative count, see notes in the Counters documentation. A Timers values can also be reset like a Counter as shown below.

_metrics.Provider.Timer.Instance(httpStatusMeter).Reset();