Metrics

Metrics

Caution

All attributes are now in the unified Purview.Telemetry namespace. See Breaking Changes for migration details.

All metric-related attributes live in the Purview.Telemetry namespace. To signal an interface for meter generation, decorate it with the [Meter] attribute.

When creating the meter types, the IMeterFactory is used when available (it is not available on .NET Framework 4.8, where a new Meter(...) is created instead).

Meter naming

The meter name is resolved in this order:

1. MeterAttribute.Name (interface)
2. MeterGenerationAttribute.MeterName (assembly)
3. The assembly name

[Meter("InventoryService")]
interface IInventoryMetrics { }

Instrument naming

An instrument name is built from up to four dot-separated parts, outermost first:

1. The meter name - only with [assembly: MeterGeneration(MeterNameGenerationType = MeterNameGenerationType.OpenTelemetry)]. The default, MeterNameGenerationType.DotNet, leaves it out: the meter already identifies its instruments.
2. MeterGenerationAttribute.InstrumentPrefix (assembly), unless MeterAttribute.IncludeAssemblyInstrumentPrefix is false.
3. The interface prefix: MeterAttribute.InstrumentPrefix when set, otherwise derived from the interface name by removing the leading I and a trailing Telemetry or Logs (IProductTelemetry becomes product).
4. The instrument’s Name, or the method name.

With the default NamingConvention.OpenTelemetry, word boundaries in every part become underscores (RecordCount becomes record_count, MyApp.Products becomes my_app.products); NamingConvention.Legacy only lowercases them. LowercaseInstrumentName = false keeps every part as written.

[Meter("MyApp.Products")]
interface IProductTelemetry
{
    [Counter]
    void RecordCount([InstrumentMeasurement] int count);
}

Configuration	Instrument name
Defaults	product.record_count
MeterNameGenerationType.OpenTelemetry	my_app.products.product.record_count
NamingConvention.Legacy	product.recordcount

These three names are pinned by the Generate_GivenTheDocumentedExample* tests in TelemetrySourceGeneratorMetricsTests.MeterNaming.cs.

MeterNameGenerationType.OpenTelemetry also lowercases a meter name that falls back to the assembly name.

Initialisation

During initialisation you can implement a partial method to provide additional tags to any meters created by the IMeterFactory:

partial void PopulateMeterTags(System.Collections.Generic.Dictionary<string, object?> meterTags)
{
    meterTags["environment"] = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT");
}

Any tags added to meterTags are included on every meter created.

Instrument types

Each instrument is determined by its corresponding attribute:

• [AutoCounter] and [Counter] generate the Counter<T> instrument.
• [Histogram] generates the Histogram<T> instrument.
• [UpDownCounter] generates the UpDownCounter<T> instrument.
• [ObservableCounter] generates the ObservableCounter<T> instrument.
• [ObservableGauge] generates the ObservableGauge<T> instrument.
• [ObservableUpDownCounter] generates the ObservableUpDownCounter<T> instrument.

The measurement type must be one of byte, short, int, long, float, double, or decimal.

The measurement value

The measurement parameter is the parameter decorated with [InstrumentMeasurement]. For non-auto-increment instruments, if no parameter is decorated the first parameter with a valid measurement type that is not a [Tag]/[Baggage] is used.

• [AutoCounter] and [Counter(AutoIncrement = true)] increment by 1 each time the method is called and must not declare a measurement parameter (TSG4002).
• [Counter], [Histogram], and [UpDownCounter] require a measurement value (TSG4004).
• Observable instruments must declare a Func<T> parameter (TSG4005).

[Meter]
interface IMeterTelemetry
{
    [AutoCounter]
    void AutoIncrementMeter([Tag]string someValue);

    [Counter(AutoIncrement = true)]
    void AutoIncrementCounterMeter([Tag]string someValue);

    [Counter]
    void CounterMeter([InstrumentMeasurement]int measurement, [Tag]float someValue);

    [Histogram]
    void HistogramMeter([InstrumentMeasurement]int measurement, [Tag]int someValue, [Tag]bool anotherValue);

    [UpDownCounter]
    void UpDownCounterMeter([InstrumentMeasurement]decimal measurement, [Tag]byte someValue);
}

Observable instruments

Observable instruments always take a System.Func<> parameter with one of the following shapes:

• Any supported measurement type: byte, short, int, long, float, double, or decimal
• Measurement<T> where T is a supported measurement type
• IEnumerable<Measurement<T>> where T is a supported measurement type

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

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

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

Tags

Other parameters on the method are used as tags. This is implicit for non-measurement parameters, but can also be made explicit with [Tag]. When there are four or more tags, the generated code uses a stack-allocated TagList.

Attribute reference

[Meter]

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

Property	Type	Description
Name	string?	The name of the meter, used to group instruments. If not specified, MeterGenerationAttribute.MeterName is used, then the assembly name. Default null.
InstrumentPrefix	string?	The prefix used when generating instrument names. Default null.
IncludeAssemblyInstrumentPrefix	bool	Whether the MeterGenerationAttribute.InstrumentPrefix prefix is included in instrument names. Default true.
LowercaseInstrumentName	bool	Whether instrument names (including prefix) are lower-cased. Default true.
LowercaseTagKeys	bool	Whether tag names are lower-cased. Default true.

[MeterGeneration]

Controls meter and instrument defaults at the assembly level.

Property	Type	Description
MeterName	string?	The default meter name when none is defined on an interface. Available on construction.
MeterNameGenerationType	MeterNameGenerationType	Whether the meter name is used as a dot-separated prefix for instrument names. OpenTelemetry (0) adds the prefix; DotNet (1, default) does not. Available on construction.
InstrumentPrefix	string?	The prefix used when generating instrument names. Default null.
InstrumentSeparator	string	The separator used when generating prefixes. Default ..
LowercaseInstrumentName	bool	Whether instrument names (including prefix) are lower-cased. Default true.
LowercaseTagKeys	bool	Whether tag names are lower-cased. Default true.

[InstrumentMeasurement]

Marks the parameter used as the instrument measurement value. Not supported with [AutoCounter] or [Counter(AutoIncrement = true)].

Instrument attributes

[AutoCounter]

Creates a Counter<int> that increments by 1 per call.

Property	Type	Description
Name	string?	Instrument name; defaults to the method name. Available on construction. Default null.
Unit	string?	The unit used during meter generation. Available on construction. Default null.
Description	string?	The description used during meter generation. Available on construction. Default null.

[Counter]

Creates a Counter<T>.

Property	Type	Description
AutoIncrement	bool	When true, generates an auto-incrementing counter instead of accepting a measurement value from a parameter. Available on construction. Default false.
Name	string?	Instrument name; defaults to the method name. Available on construction. Default null.
Unit	string?	The unit used during meter generation. Available on construction. Default null.
Description	string?	The description used during meter generation. Available on construction. Default null.

When AutoIncrement is true and [InstrumentMeasurement] is used, the TSG4002 diagnostic is raised.

[Histogram] and [UpDownCounter]

Create a Histogram<T> or UpDownCounter<T>. Both share the Name, Unit, and Description properties described above.

Observable attributes

[ObservableCounter], [ObservableGauge], and [ObservableUpDownCounter] share the Name, Unit, and Description properties, plus:

Property	Type	Description
ThrowOnAlreadyInitialized	bool	Whether the method throws when called more than once. Available on construction. Default false.

Next steps

• Tags, Baggage, and Parameter Attributes — tagging parameters
• Multi-Targeting — combining Metrics with Activities and Logging
• Diagnostics — the TSG4xxx Metrics rules