Filtering Metrics

App Metrics supports filtering metrics on various properties such as Metric Type, Tags, Context and Name. Filtering can be applied either globally, when retrieving a snapshot of metrics or for a specific reporter.

Global Filter

A metrics filter can be applied on the IMetricsBuilder which will be applied by default when retrieving metric snapshots.

Metrics Field Filter

Metric types supported by App Metrics typically record several fields e.g. a Meter will record for example a 1-min, 5-min and 15-min rate. Such values can also be calculated using the chosen TSDB where metrics are flushed. In cases where metrics are frequently flushed and it is necessary to save on storage, metrics which aren’t be used can be excluded:

var metrics = new MetricsBuilder()
    .MetricFields.Configure(
        fields =>
        {
            fields.Counter.Exclude(CounterFields.Total, CounterFields.SetItem, CounterFields.SetItemPercent);
            fields.Meter.OnlyInclude(MeterFields.Rate1M);
            fields.Histogram.OnlyInclude(HistogramFields.P95, HistogramFields.P99);
        })
    .Build();

The MetricsFields extension also allows renaming the default metric names, for example to customise the default gauge and counter value fields:

var metrics = new MetricsBuilder()
    .MetricFields.Configure(
        fields =>
        {
            fields.Counter.Set(CounterFields.Value, "custom_val");
            fields.Gauge.Set(GaugeFields.Value, "custom_val");
        })
    .Build();

The following is an example of how to apply a global filter:

var filter = new MetricsFilter()
    .WhereType(MetricType.Counter, MetricType.Gauge)
    .WhereContext("Application")
    .WhereNameStartsWith("test_");

var metrics = new MetricsBuilder()
    .Filter.With(filter)
    .Build();

When retrieving a metric snapshot, the global filter can be overriden by passing in a new filter: metrics.Snapshot.Get(filter)

Report Filtering

App Metrics supports filtering metrics for specific reporters which could be useful to report a subset metrics to different sources.

The following example reports all metrics in the Console context to System.Console and metrics in the TextFile context to a text file.

var metrics = new MetricsBuilder()
    .Report.ToConsole(options => options.Filter = new MetricsFilter().WhereContext("Console"))
    .Report.ToTextFile(options => options.Filter = new MetricsFilter().WhereContext("TextFile"))
    .Build();

Snapshot Filter

Metrics can be filtered when retriving a snapshot via an IMetrics as follows:

var filter = new MetricsFilter()
    .WhereName(name => name == "test_gauge");
var snapshot = metrics.Snapshot.Get(filter);

Filtering Specifics

A default implementation of IFilterMetrics is provided to filter metrics, create an instance of MetricsFilter.

var filter = new MetricsFilter();

Metric Context

Metrics can be grouped into Contexts which can be useful in organizing metrics.

To filter by a specific context:

filter.WhereContext("MyContext");

Metric Name

All metrics are required to be labelled with a Name.

To filter a metric by it’s name:

filter.WhereName(metric => metric == "my_metric_name");
filter.WhereNameStartsWith("my_");

Metric Type

Several metric types are supported by App Metrics.

To filter by one or more types:

filter.WhereType(MetricType.Timer);
filter.WhereType(MetricType.Counter, MetricType.Gauge);

Metric Tags

Metric tagging is very useful when reporting to a time series database allowing querying and aggregating by various dimensions straightforward. App Metrics supports filtering metrics on tags by matching tag key(s) and tag key/value pairs.

To filter metrics by tags:

filter.WhereTaggedWithKey("myTagKey1", "myTagKey2");
filter.WhereTaggedWithKeyValue(new TagKeyValueFilter { { "tag1", "value1" } });