|
// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
using System;
using System.Diagnostics.Metrics;
namespace Microsoft.Extensions.Diagnostics.Metrics
{
/// <summary>
/// Contains a set of parameters used to determine which instruments are enabled for which listeners. Unspecified
/// parameters match anything.
/// </summary>
/// <remarks>
/// <para>The most specific rule that matches a given instrument will be used. The priority of parameters is as follows:</para>
/// <para>- MeterName, either an exact match, or the longest prefix match. See <see cref="Meter.Name">Meter.Name</see>.</para>
/// <para>- InstrumentName, an exact match. <see cref="Instrument.Name">Instrument.Name</see>.</para>
/// <para>- ListenerName, an exact match. <see cref="IMetricsListener.Name">IMetricsListener.Name</see>.</para>
/// <para>- Scopes</para>
/// </remarks>
/// <param name="meterName">The <see cref="Meter.Name">Meter.Name</see> or prefix.</param>
/// <param name="instrumentName">The <see cref="Instrument.Name">Instrument.Name</see>.</param>
/// <param name="listenerName">The <see cref="IMetricsListener.Name">IMetricsListener.Name</see>.</param>
/// <param name="scopes">A bitwise combination of the enumeration values that specifies the scopes to consider.</param>
/// <param name="enable"><see langword="true" /> to enable the matched instrument for this listener; otherwise, <see langword="false" />.</param>
public class InstrumentRule(string? meterName, string? instrumentName, string? listenerName, MeterScope scopes, bool enable)
{
/// <summary>
/// Gets the <see cref="Meter.Name">Meter.Name</see>, either an exact match or the longest prefix match. Only full segment matches are considered.
/// </summary>
/// <value>
/// The meter name. If <see langword="null" />, all meters are matched.
/// </value>
public string? MeterName { get; } = meterName;
/// <summary>
/// Gets the <see cref="Instrument.Name">Instrument.Name</see>, an exact match.
/// </summary>
/// <value>
/// The instrument name. If <see langword="null" />, all instruments for the meter are matched.
/// </value>
public string? InstrumentName { get; } = instrumentName;
/// <summary>
/// Gets the <see cref="IMetricsListener.Name">IMetricsListener.Name</see>, an exact match.
/// </summary>
/// <value>
/// The listener name. If <see langword="null" />, all listeners are matched.
/// </value>
public string? ListenerName { get; } = listenerName;
/// <summary>
/// Gets the <see cref="MeterScope"/>.
/// </summary>
/// <remarks>
/// This property is used to distinguish between meters created via <see cref="Meter"/> constructors (<see cref="MeterScope.Global"/>)
/// and those created via Dependency Injection with <see cref="IMeterFactory.Create(MeterOptions)"/> (<see cref="MeterScope.Local"/>).
/// </remarks>
public MeterScope Scopes { get; } = scopes == MeterScope.None
? throw new ArgumentOutOfRangeException(nameof(scopes), scopes, "The MeterScope must be Global, Local, or both.")
: scopes;
/// <summary>
/// Gets a value that indicates whether the instrument should be enabled for the listener.
/// </summary>
public bool Enable { get; } = enable;
}
}
|