Meter Interface

  • Reference
Package:
com.azure.core.util.metrics
Maven Artifact:
com.azure:azure-core:1.49.0

Implements

AutoCloseable

public interface Meter
extends AutoCloseable

Meter is generally associated with Azure Service Client instance and allows creating instruments that represent individual metrics such as number of active connections or HTTP call latency. Choose instrument kind based on OpenTelemetry guidelines: https://opentelemetry.io/docs/reference/specification/metrics/api/\#counter-creation This class is intended to be used by Azure client libraries and provides abstraction over different metrics implementations. Application developers should use metrics implementations such as OpenTelemetry or Micrometer directly.

// Meter and instruments should be created along with service client instance and retained for the client
 // lifetime for optimal performance
 Meter meter = meterProvider
     .createMeter("azure-core", "1.0.0", new MetricsOptions());

 DoubleHistogram amqpLinkDuration = meter
     .createDoubleHistogram("az.core.amqp.link.duration", "AMQP link response time.", "ms");

 TelemetryAttributes attributes = defaultMeter.createAttributes(
     Collections.singletonMap("endpoint", "http://service-endpoint.azure.com"));

 // when measured operation starts, record the measurement
 Instant start = Instant.now();

 doThings();

 // optionally check if meter is operational for the best performance
 if (amqpLinkDuration.isEnabled()) {
     amqpLinkDuration.record(Instant.now().toEpochMilli() - start.toEpochMilli(), attributes, currentContext);
 }

Method Summary

Modifier and Type Method and Description
abstract void close()
abstract TelemetryAttributes createAttributes(Map<String,Object> attributeMap)

Creates and returns attribute collection implementation specific to the meter implementation.
abstract DoubleHistogram createDoubleHistogram(String name, String description, String unit)

Creates histogram instrument allowing to record long values.
abstract LongCounter createLongCounter(String name, String description, String unit)

Creates Counter instrument that is used to record incrementing values, such as number of sent messages or created connections.
default LongGauge createLongGauge(String name, String description, String unit)

Creates LongGauge instrument that is used to asynchronously record current value of metric.
abstract LongCounter createLongUpDownCounter(String name, String description, String unit)

Creates UpDownCounter instrument that is used to record values that can go up or down, such as number of active connections or queue size.
abstract boolean isEnabled()

Checks if Meter implementation was found, and it's enabled.

Method Details

close

public abstract void close()

createAttributes

public abstract TelemetryAttributes createAttributes(Map attributeMap)

Creates and returns attribute collection implementation specific to the meter implementation. Attribute collections differ in how they support different types of attributes and internal data structures they use. For the best performance, client libraries should create and cache attribute collections for the client lifetime and pass cached instance when recoding new measurements.

// Create attributes for possible error codes. Can be done lazily once specific error code is received.
 TelemetryAttributes successAttributes = defaultMeter.createAttributes(new HashMap<String, Object>() {{
         put("endpoint", "http://service-endpoint.azure.com");
         put("error", true);
     }});

 TelemetryAttributes errorAttributes =  defaultMeter.createAttributes(new HashMap<String, Object>() {{
         put("endpoint", "http://service-endpoint.azure.com");
         put("error", false);
     }});

 LongCounter httpConnections = defaultMeter.createLongCounter("az.core.http.connections",
     "Number of created HTTP connections", null);

 boolean success = false;
 try {
     success = doThings();
 } finally {
     httpConnections.add(1, success ? successAttributes : errorAttributes, currentContext);
 }

Parameters:

attributeMap - map of key value pairs to cache.

Returns:

an instance of AttributesBuilder

createDoubleHistogram

public abstract DoubleHistogram createDoubleHistogram(String name, String description, String unit)

Creates histogram instrument allowing to record long values. Histograms should be used for latency or other measurements where distribution of values is important and values are statistically bounded. See https://opentelemetry.io/docs/reference/specification/metrics/api/\#histogram for more details.

// Meter and instruments should be created along with service client instance and retained for the client
 // lifetime for optimal performance
 Meter meter = meterProvider
     .createMeter("azure-core", "1.0.0", new MetricsOptions());

 DoubleHistogram amqpLinkDuration = meter
     .createDoubleHistogram("az.core.amqp.link.duration", "AMQP link response time.", "ms");

 TelemetryAttributes attributes = defaultMeter.createAttributes(
     Collections.singletonMap("endpoint", "http://service-endpoint.azure.com"));

 // when measured operation starts, record the measurement
 Instant start = Instant.now();

 doThings();

 // optionally check if meter is operational for the best performance
 if (amqpLinkDuration.isEnabled()) {
     amqpLinkDuration.record(Instant.now().toEpochMilli() - start.toEpochMilli(), attributes, currentContext);
 }

Parameters:

description - free-form text describing the instrument
unit - optional unit of measurement.

Returns:

new instance of DoubleHistogram

createLongCounter

public abstract LongCounter createLongCounter(String name, String description, String unit)

Creates Counter instrument that is used to record incrementing values, such as number of sent messages or created connections. Use createLongUpDownCounter(String name, String description, String unit) for counters that can go down, such as number of active connections or queue size. See https://opentelemetry.io/docs/reference/specification/metrics/api/\#counter for more details.

TelemetryAttributes attributes = defaultMeter.createAttributes(new HashMap<String, Object>() {{
         put("endpoint", "http://service-endpoint.azure.com");
         put("status", "ok");
     }});

 LongCounter createdHttpConnections = defaultMeter.createLongCounter("az.core.http.connections",
     "Number of created HTTP connections", null);

 createdHttpConnections.add(1, attributes, currentContext);

Parameters:

description - free-form text describing the counter
unit - optional unit of measurement.

Returns:

new instance of LongCounter

createLongGauge

public default LongGauge createLongGauge(String name, String description, String unit)

Creates LongGauge instrument that is used to asynchronously record current value of metric. See https://opentelemetry.io/docs/reference/specification/metrics/api/\#asynchronous-gauge for more details.

TelemetryAttributes attributes = defaultMeter.createAttributes(new HashMap<String, Object>() {{
         put("endpoint", "http://service-endpoint.azure.com");
         put("container", "my-container");
     }});

 LongGauge latestSequenceNumber = defaultMeter.createLongGauge("az.eventhubs.consumer.sequence_number",
     "Sequence number of the latest event received from the broker.", null);

 AutoCloseable subscription = latestSequenceNumber.registerCallback(sequenceNumber::get, attributes);

 // update value when event is received
 sequenceNumber.set(getSequenceNumber());

 try {
     subscription.close();
 } catch (Exception e) {
     e.printStackTrace();
 }

Parameters:

description - free-form text describing the counter
unit - optional unit of measurement.

Returns:

new instance of LongGauge

createLongUpDownCounter

public abstract LongCounter createLongUpDownCounter(String name, String description, String unit)

Creates UpDownCounter instrument that is used to record values that can go up or down, such as number of active connections or queue size. See https://opentelemetry.io/docs/reference/specification/metrics/api/\#updowncounter for more details.

TelemetryAttributes attributes = defaultMeter.createAttributes(new HashMap<String, Object>() {{
         put("endpoint", "http://service-endpoint.azure.com");
         put("status", "ok");
     }});

 LongCounter activeHttpConnections = defaultMeter.createLongUpDownCounter("az.core.http.active.connections",
     "Number of active HTTP connections", null);

 // on connection initialized:
 activeHttpConnections.add(1, attributes, currentContext);

 // on connection closed:
 activeHttpConnections.add(-1, attributes, currentContext);

Parameters:

description - free-form text describing the counter
unit - optional unit of measurement.

Returns:

new instance of LongCounter

isEnabled

public abstract boolean isEnabled()

Checks if Meter implementation was found, and it's enabled.

Returns:

true if Meter is enabled, false otherwise.

Applies to