Metrics

Basics

The types are hosted within the Purview.Telemetry.Metrics namespace, with the exception of the TagAttribute which is defined within Purview.Telemetry.

To signal an interface for meter target generation, decorate the interface with the MeterAttribute. If the MeterAttribute.Name is not specified, the name of the interface, without the first 'I', will be used. For example ICacheServiceTelemetry would become CacheServiceTelemetry.

When creating the meter types, the IMeterFactory is used by default.

Initialisation

During the initialisation of the class you can implement a partial method used to provide additional tags to any meters created by the IMeterFactory.

The signature is: partial void PopulateMeterTags(System.Collections.Generic.Dictionary<string, object?> meterTags). You can add you custom tags to the meterTags to enable all meters created to include these tags.

Instrument Types

There are several supported instrument types: counter, histogram, up-down counter, observable counter, observable gauge and observable up-down counters. Each are determined by the corresponding attribute:

AutoCounterAttribute and CounterAttribute generates the Counter<T> instrument.
HistogramAttribute generates the Histogram<T> instrument.
UpDownCounterAttribute generates the UpDownCounter<T> instrument.
ObservableCounterAttribute generates the ObservableCounter<T> instrument.
ObservableGaugeAttribute generates the ObservableGauge<T> instrument.
ObservableUpDownCounterAttribute generates the ObservableUpDownCounter<T> instrument.

The measurement type used by the meter must be one of the following: byte, short, int, long, float, double, or decimal.

This is determined by decorating the desired parameter with the InstrumentMeasurementAttribute. When generating an auto-increment counter, the instrument measurement value is automatically created. Therefore an error diagnostic will be raised if one is included.

Inferring The Measuring Value

Inferring the instrument measurement value is supported in the following cases:

For CounterAttribute (when AutoIncrement is false), HistogramAttribute and UpDownCounterAttribute where the first parameter is used matching the requirement measurement types and not defined as a tag or baggage.

Additionally, ObservableCounterAttribute, ObservableGaugeAttribute and ObservableUpDownCounterAttribute measurement parameter inferring is supported when a corresponding Func<T>, Func<Measurement<T>> or Func<IEnumerable<Measurement<T>>> is found.

AutoCounter, Counter, Histogram and Up/Down Counter

All of these counter types require a measurement parameter, except for the counter when AutoCounterAttribute is present, or CounterAttribute.AutoIncrement is set to true.

If a measurement parameter is not defined, the first parameter with a matching type is used.

When using AutoCounterAttribute or CounterAttribute.AutoIncrement, the meter increments by one each time the method is called.

ObservableCounter, ObservableGauge and ObservableUpDownCounter

Observable meter types must always have a System.Func<T> with one of the supported instrument types.

However, you may also use Measurement<T> where T is one of the support instrument types.

You can provide multiple values at once using IEnumerable<Measurement<T>>, again T must be one of valid measurement types.

Examples:

[ObservableCounter]
void Counter(Func<int> func);

[ObservableGauge]
void Gauge(Func<Measurement<int>> func);

[ObservableUpDownCounter]
void UpDownCounter(Func<IEnumerable<Measurement<int>>> func);

Types

MeterAttribute

Defines and controls the generation of meters and instruments on an interface, overriding any assembly level defaults.

Name	Type	Description
`Name`	`string?`	Optionally defines the name of the meter, used to group instruments. If no name is specified, defaults to the name of the interface within the starting `I`. Defaults to `null`.
`InstrumentPrefix`	`string?`	Determines the prefix to use when generating the name of the instrument. Defaults to `null`.
`IncludeAssemblyInstrumentPrefix`	`bool`	Determines if the `MeterGenerationAttribute.InstrumentPrefix` prefix is included as part of the instrument name generation. Defaults to `true`.
`LowercaseInstrumentName`	`bool`	Determines if the name of the instrument, including any prefix information, is lower-cased. Defaults to `true`.
`LowercaseTagKeys`	`bool`	Determines if any tags have their name's lowercased. Defaults to `true`.

MeterGenerationAttribute

Controls defaults of meter and instrument generation at the assembly level.

Name	Type	Description
`InstrumentPrefix`	`string?`	Determines the prefix to use when generating the name of the instrument. Defaults to `null`.
`InstrumentSeparator`	`string?`	Determines the separator to use when generating prefixes. Defaults to `.`.
`LowercaseInstrumentName`	`bool`	Determines if the name of the instrument, including any prefix information, is lower-cased. Defaults to `true`.
`LowercaseTagKeys`	`bool`	Determines if any tags have their name's lowercased. Defaults to `true`.

InstrumentMeasurementAttribute

Defines the parameter used as the instrument measurement value. Not supported when using AutoCounterAttribute or when CounterAttribute.AutoIncrement is true.

Instrument Definition Attributes

The following attributes are used on methods to define the type of instruments to generate.

AutoCounterAttribute

Used to create a Counter<T> meter, where T is an int.

Name	Type	Description
Name	`string?`	Determines the name of the meter. If this is not provided, the name of the method is used. Also available on construction. Defaults to `null`.
Unit	`string?`	Specifies the Unit used during meter generation. Also available on construction. Defaults to `null`.
Description	`string?`	Specifies the Description used during meter generation. Also available on construction. Defaults to `null`.

This is the equivalent of using the CounterAttribute and setting AutoIncrement to true.

When specifying an [InstrumentMeasurementAttribute] on a parameter, the TSG4002 diagnostic is raised.

CounterAttribute

Used to create a Counter<T> meter.

Name	Type	Description
AutoIncrement	`bool`	Determines if the meter should generate an auto-incrementing counter, rather than accepting a measurement value from one of the parameters Also available on construction. Defaults to `false`.
Name	`string?`	Determines the name of the meter. If this is not provided, the name of the method is used. Also available on construction. Defaults to `null`.
Unit	`string?`	Specifies the Unit used during meter generation. Also available on construction. Defaults to `null`.
Description	`string?`	Specifies the Description used during meter generation. Also available on construction. Defaults to `null`.

When AutoIncrement is true and an [InstrumentMeasurementAttribute] is used on a parameter, the TSG4002 diagnostic is raised.

HistogramAttribute

Used to create a Histogram<T> meter.

Name	Type	Description
Name	`string?`	Determines the name of the meter. If this is not provided, the name of the method is used. Also available on construction. Defaults to `null`.
Unit	`string?`	Specifies the Unit used during meter generation. Also available on construction. Defaults to `null`.
Description	`string?`	Specifies the Description used during meter generation. Also available on construction. Defaults to `null`.

UpDownAttribute

Used to create a UpDownCounter<T> meter.

Name	Type	Description
Name	`string?`	Determines the name of the meter. If this is not provided, the name of the method is used. Also available on construction. Defaults to `null`.
Unit	`string?`	Specifies the Unit used during meter generation. Also available on construction. Defaults to `null`.
Description	`string?`	Specifies the Description used during meter generation. Also available on construction. Defaults to `null`.

ObservableCounterAttribute

Used to create a ObservableUpDownCounter<T> meter.

Name	Type	Description
Name	`string?`	Determines the name of the meter. If this is not provided, the name of the method is used. Also available on construction. Defaults to `null`.
Unit	`string?`	Specifies the Unit used during meter generation. Also available on construction. Defaults to `null`.
Description	`string?`	Specifies the Description used during meter generation. Also available on construction. Defaults to `null`.
ThrowOnAlreadyInitialized	`bool`	Determines if the method throws an exception or not if it is called more than once. Also available on construction. Defaults to `false`.

ObservableGaugeAttribute

Used to create a ObservableGauge<T> meter.

Name	Type	Description
Name	`string?`	Determines the name of the meter. If this is not provided, the name of the method is used. Also available on construction. Defaults to `null`.
Unit	`string?`	Specifies the Unit used during meter generation. Also available on construction. Defaults to `null`.
Description	`string?`	Specifies the Description used during meter generation. Also available on construction. Defaults to `null`.
ThrowOnAlreadyInitialized	`bool`	Determines if the method throws an exception or not if it is called more than once. Also available on construction. Defaults to `false`.

ObservableUpDownCounterAttribute