Package com.azure.core.util.metrics

Interface Meter

All Superinterfaces:
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 Details

    • createDoubleHistogram

      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:
      name - short histogram name following https://opentelemetry.io/docs/reference/specification/metrics/api/#instrument-naming-rule
      description - free-form text describing the instrument
      unit - optional unit of measurement.
      Returns:
      new instance of DoubleHistogram
      Throws:
      NullPointerException - if name or description is null.

    • createLongCounter

      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, String, String) 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:
      name - short counter name following https://opentelemetry.io/docs/reference/specification/metrics/api/#instrument-naming-rule
      description - free-form text describing the counter
      unit - optional unit of measurement.
      Returns:
      new instance of LongCounter
      Throws:
      NullPointerException - if name or description is null.

    • createLongUpDownCounter

      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:
      name - short counter name following https://opentelemetry.io/docs/reference/specification/metrics/api/#instrument-naming-rule
      description - free-form text describing the counter
      unit - optional unit of measurement.
      Returns:
      new instance of LongCounter
      Throws:
      NullPointerException - if name or description is null.

    • createAttributes

      TelemetryAttributes createAttributes(Map<String,Object> 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

    • isEnabled

      boolean isEnabled()
      Checks if Meter implementation was found, and it's enabled.
      Returns:
      true if Meter is enabled, false otherwise.

    • close

      void close()
      Specified by:
      close in interface AutoCloseable