/// <summary>
/// Gets or creates a metric container that you can use to track, aggregate and send metric values.<br />
/// Optionally specify a metric configuration to control how the tracked values are aggregated.
/// </summary>
/// <param name="telemetryClient">The aggregated values will be sent using the specified client.</param>
/// <param name="metricIdentifier">A grouping containing the Namespace, the ID (name) and the dimension names of the metric.</param>
/// <param name="metricConfiguration">Determines how tracked values will be aggregated. <br />
/// Use presets in <see cref="MetricConfigurations.Common"/> or specify your own settings. </param>
/// <returns>A <c>Metric</c> with the specified ID and dimensions. If you call this method several times
/// with the same metric ID and dimensions for a given aggregation scope, you will receive the same
/// instance of <c>Metric</c>.</returns>
/// <exception cref="ArgumentException">If you previously created a metric with the same namespace, ID, dimensions
/// and aggregation scope, but with a different configuration. When calling this method to get a previously
/// created metric, you can simply avoid specifying any configuration (or specify null) to imply the
/// configuration used earlier.</exception>
/// <param name="aggregationScope">The scope across which the values for the metric are to be aggregated in memory.
/// See <see cref="MetricAggregationScope" /> for more info.</param>
public static Metric GetMetric(
this TelemetryClient telemetryClient,
MetricIdentifier metricIdentifier,
MetricConfiguration metricConfiguration,
MetricAggregationScope aggregationScope)
{
return(GetOrCreateMetric(
telemetryClient,
aggregationScope,
metricIdentifier,
metricConfiguration));
}
/// <summary>
/// Gets or creates a metric container that you can use to track, aggregate and send metric values.<br />
/// Optionally specify a metric configuration to control how the tracked values are aggregated.
/// </summary>
/// <param name="telemetryClient">The aggregated values will be sent using the specified client.</param>
/// <param name="metricId">The ID (name) of the metric.
/// (The namespace specified in <see cref="MetricIdentifier.DefaultMetricNamespace"/> will be used.
/// To specify another namespace, user an overload that takes a <c>MetricIdentifier</c> paramater instead.)</param>
/// <param name="metricConfiguration">Determines how tracked values will be aggregated. <br />
/// Use presets in <see cref="MetricConfigurations.Common"/> or specify your own settings. </param>
/// <returns>A <c>Metric</c> with the specified ID and dimensions. If you call this method several times
/// with the same metric ID and dimensions for a given aggregation scope, you will receive the same
/// instance of <c>Metric</c>.</returns>
/// <exception cref="ArgumentException">If you previously created a metric with the same namespace, ID, dimensions
/// and aggregation scope, but with a different configuration. When calling this method to get a previously
/// created metric, you can simply avoid specifying any configuration (or specify null) to imply the
/// configuration used earlier.</exception>
/// <param name="aggregationScope">The scope across which the values for the metric are to be aggregated in memory.
/// See <see cref="MetricAggregationScope" /> for more info.</param>
/// <returns></returns>
public static Metric GetMetric(
this TelemetryClient telemetryClient,
string metricId,
MetricConfiguration metricConfiguration,
MetricAggregationScope aggregationScope)
{
return(GetOrCreateMetric(
telemetryClient,
aggregationScope,
new MetricIdentifier(metricId),
metricConfiguration: metricConfiguration));
}
private static Metric GetOrCreateMetric(
TelemetryClient telemetryClient,
MetricAggregationScope aggregationScope,
MetricIdentifier metricIdentifier,
MetricConfiguration metricConfiguration)
{
Util.ValidateNotNull(telemetryClient, nameof(telemetryClient));
MetricManager metricManager = telemetryClient.GetMetricManager(aggregationScope);
Metric metric = metricManager.Metrics.GetOrCreate(metricIdentifier, metricConfiguration);
return(metric);
}
/// <summary>
/// Gets or creates a metric container that you can use to track, aggregate and send metric values.<br />
/// Optionally specify a metric configuration to control how the tracked values are aggregated.
/// </summary>
/// <param name="telemetryClient">The aggregated values will be sent using the specified client.</param>
/// <param name="metricId">The ID (name) of the metric.
/// (The namespace specified in <see cref="MetricIdentifier.DefaultMetricNamespace"/> will be used.
/// To specify another namespace, user an overload that takes a <c>MetricIdentifier</c> paramater instead.)</param>
/// <param name="dimension1Name">The name of the first dimension.</param>
/// <param name="metricConfiguration">Determines how tracked values will be aggregated. <br />
/// Use presets in <see cref="MetricConfigurations.Common"/> or specify your own settings. </param>
/// <returns>A <c>Metric</c> with the specified ID and dimensions. If you call this method several times
/// with the same metric ID and dimensions for a given aggregation scope, you will receive the same
/// instance of <c>Metric</c>.</returns>
/// <exception cref="ArgumentException">If you previously created a metric with the same namespace, ID, dimensions
/// and aggregation scope, but with a different configuration. When calling this method to get a previously
/// created metric, you can simply avoid specifying any configuration (or specify null) to imply the
/// configuration used earlier.</exception>
/// <param name="aggregationScope">The scope across which the values for the metric are to be aggregated in memory.
/// See <see cref="MetricAggregationScope" /> for more info.</param>
public static Metric GetMetric(
this TelemetryClient telemetryClient,
string metricId,
string dimension1Name,
MetricConfiguration metricConfiguration,
MetricAggregationScope aggregationScope)
{
return(GetOrCreateMetric(
telemetryClient,
aggregationScope,
new MetricIdentifier(MetricIdentifier.DefaultMetricNamespace, metricId, dimension1Name),
metricConfiguration: metricConfiguration));
}
/// <summary>
/// Gets or creates a metric container that you can use to track, aggregate and send metric values.<br />
/// Optionally specify a metric configuration to control how the tracked values are aggregated.
/// </summary>
/// <param name="telemetryClient">The aggregated values will be sent using the specified client.</param>
/// <param name="metricId">The ID (name) of the metric.</param>
/// <param name="metricConfiguration">Determines how tracked values will be aggregated. <br />
/// Use presets in <see cref="MetricConfigurations.Common"/> or specify your own settings. </param>
/// <returns>A <c>Metric</c> with the specified ID and dimensions. If you call this method several times
/// with the same metric ID and dimensions for a given aggregation scope, you will receive the same
/// instance of <c>Metric</c>.</returns>
/// <exception cref="ArgumentException">If you previously created a metric with the same ID, dimensions
/// and aggregation scope, but with a different configuration. When calling this method to get a previously
/// created metric, you can simply avoid specifying any configuration (or specify null) to imply the
/// configuration used earlier.</exception>
/// <param name="aggregationScope">The scope across which the values for the metric are to be aggregated in memory.
/// See <see cref="MetricAggregationScope" /> for more info.</param>
/// <returns></returns>
public static Metric GetMetric(
this TelemetryClient telemetryClient,
string metricId,
IMetricConfiguration metricConfiguration,
MetricAggregationScope aggregationScope)
{
return(GetOrCreateMetric(
telemetryClient,
aggregationScope,
metricId,
dimension1Name: null,
dimension2Name: null,
metricConfiguration: metricConfiguration));
}
/// <summary>
/// Gets or creates a metric container that you can use to track, aggregate and send metric values.<br />
/// Optionally specify a metric configuration to control how the tracked values are aggregated.
/// </summary>
/// <param name="telemetryClient">The aggregated values will be sent using the specified client.</param>
/// <param name="metricId">The ID (name) of the metric.</param>
/// <param name="dimension1Name">The name of the first dimension.</param>
/// <param name="metricConfiguration">Determines how tracked values will be aggregated. <br />
/// Use presets in <see cref="MetricConfigurations.Common"/> or specify your own settings. </param>
/// <returns>A <c>Metric</c> with the specified ID and dimensions. If you call this method several times
/// with the same metric ID and dimensions for a given aggregation scope, you will receive the same
/// instance of <c>Metric</c>.</returns>
/// <exception cref="ArgumentException">If you previously created a metric with the same ID, dimensions
/// and aggregation scope, but with a different configuration. When calling this method to get a previously
/// created metric, you can simply avoid specifying any configuration (or specify null) to imply the
/// configuration used earlier.</exception>
/// <param name="aggregationScope">The scope across which the values for the metric are to be aggregated in memory.
/// See <see cref="MetricAggregationScope" /> for more info.</param>
public static Metric GetMetric(
this TelemetryClient telemetryClient,
string metricId,
string dimension1Name,
IMetricConfiguration metricConfiguration,
MetricAggregationScope aggregationScope)
{
Util.ValidateNotNullOrWhitespace(dimension1Name, nameof(dimension1Name));
return(GetOrCreateMetric(
telemetryClient,
aggregationScope,
metricId,
dimension1Name,
dimension2Name: null,
metricConfiguration: metricConfiguration));
}
/// <summary>
/// </summary>
/// <param name="telemetryClient"></param>
/// <param name="aggregationScope"></param>
/// <returns></returns>
public static MetricManager Metrics(this TelemetryClient telemetryClient, MetricAggregationScope aggregationScope)
{
Util.ValidateNotNull(telemetryClient, nameof(telemetryClient));
switch (aggregationScope)
{
case MetricAggregationScope.TelemetryConfiguration:
TelemetryConfiguration pipeline = Util.GetTelemetryConfiguration(telemetryClient);
return(pipeline.Metrics());
case MetricAggregationScope.TelemetryClient:
MetricManager manager = GetOrCreateMetricManager(telemetryClient);
return(manager);
default:
throw new ArgumentException($"Invalid value of {nameof(aggregationScope)} ({aggregationScope}). Only the following values are supported:"
+ $" ['{nameof(MetricAggregationScope)}.{MetricAggregationScope.TelemetryClient.ToString()}',"
+ $" '{nameof(MetricAggregationScope)}.{MetricAggregationScope.TelemetryConfiguration.ToString()}'].");
}
}
private static Metric GetOrCreateMetric(
TelemetryClient telemetryClient,
MetricAggregationScope aggregationScope,
string metricId,
string dimension1Name,
string dimension2Name,
IMetricConfiguration metricConfiguration)
{
Util.ValidateNotNull(telemetryClient, nameof(telemetryClient));
MetricManager metricManager = telemetryClient.GetMetricManager(aggregationScope);
MetricsCache cache = metricManager.GetOrCreateExtensionState(MetricsCache.CreateNewInstance);
if (cache == null)
{
throw new InvalidOperationException($"telemetryConfiguration.GetMetricManager().GetOrCreateExtensionState(..) unexpectedly returned null."
+ $" This indicates that multiple extensions attempt to use"
+ $" the \"Cache\" extension point of the {nameof(MetricManager)} in a conflicting manner.");
}
Metric metric = cache.GetOrCreateMetric(metricId, dimension1Name, dimension2Name, metricConfiguration);
return(metric);
}