organizing-metrics.md

Organizing Metrics

App Metrics provides a two ways to organize your metrics:

1. Through the use of Tags when declaring your metrics or by configuring tags globally for all Metrics.
2. By specifing a Context label when declaring your metrics. By default any all custom Metrics will belong the the "Application" Context.

Metric Tagging

Metrics can be tagged when they are declared, these tags can then be shipped with your metric values to your database of choice which is useful for commonly-queried metadata.

An example use case for tagging is recording an APIs response time per endpoint where a timer is recorded per endpoint but then reported as the same metric name tagged with by the endpoint. This allows us to more easily have a dynamic list of endpoints and their response times when visualizing with Grafana for example.

Tagging at runtime

[!code-csharpMain]

Tagging globally

Tags can also be defined for all Metrics globally which is useful for tagging by things like machine name, environment, ip address, application name etc.

[!code-csharpMain]

Default tags

App Metrics adds a few default global tags which are commonly used. These are as follows:

Tag	Description
app	The name of the application, which is set to the entry assembly name of the application i.e. Assembly.GetEntryAssembly().GetName().Name.
server	The name of the machine the application is currently running on i.e. Environment.MachineName.
env	The environment the application is running in. When running in debug mode will be set to debug otherwise release. This can be adjusted to be staging, production etc via app settings, via the tagging helpers or disabled setting the AppMetricsOptions.AddDefaultGlobalTags to false.

Tagging helpers

App Metrics provides an extension method on the AppMetricsOptions delegate passing some environment information that can be used to set global tags such as the machine name, assembly version etc.

[!code-csharpMain]

Tagging statically

[!code-csharpMain]

Metric Contexts

Organizing your Metrics into separate meaningful contexts is helpful for visualization and reporting. Only one level of Context categorization is supported.

The default global context can be modified using the DefaultContextLabel in the configuration options when configuring your application to use App Metrics.

Defining a Context on a Metric

To add Metrics to a particular context, the context can be specified when declaring your metrics. For example:

[!code-csharpMain]

Filtering in process by Context

The DefaultMetricsFilter can be used to filter Metrics by a Context. This would be useful if we only wanted to report on a particular Metrics Context.

Note

See Metrics Filtering for more details on filtering Metrics.

Viewing from a Web Host

Below is a snippet from a /metrics response generated by a web host using the App.Metrics.Extensions.Middleware nuget package (Note: Metric values have been omitted for brevity).

[!code-jsonMain]

Note

You'll need to install the App.Metrics.Formatters.Json nuget package and AddJsonSerialization() in your Startup.cs for formatting /metrics results as json.

Filtering in process by Tag Keys

The DefaultMetricsFilter can be used to filter Metrics by a Tag Keys. This would be useful if we only wanted to report on a particular Metrics Tags.

Note

See Metrics Filtering for more details on filtering Metrics.