Package com.azure.core.util.metrics
Interface Meter
- All Superinterfaces:
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 TypeMethodDescriptionvoid
close()
createAttributes
(Map<String, Object> attributeMap) Creates and returns attribute collection implementation specific to the meter implementation.createDoubleHistogram
(String name, String description, String unit) Creates histogram instrument allowing to record long values.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) CreatesLongGauge
instrument that is used to asynchronously record current value of metric.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.boolean
Checks if Meter implementation was found, and it's enabled.
-
Method Details
-
createDoubleHistogram
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-ruledescription
- free-form text describing the instrumentunit
- optional unit of measurement.- Returns:
- new instance of
DoubleHistogram
- Throws:
NullPointerException
- if name or description is null.
-
createLongCounter
Creates Counter instrument that is used to record incrementing values, such as number of sent messages or created connections. UsecreateLongUpDownCounter(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-ruledescription
- free-form text describing the counterunit
- optional unit of measurement.- Returns:
- new instance of
LongCounter
- Throws:
NullPointerException
- if name or description is null.
-
createLongUpDownCounter
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-ruledescription
- free-form text describing the counterunit
- optional unit of measurement.- Returns:
- new instance of
LongCounter
- Throws:
NullPointerException
- if name or description is null.
-
createLongGauge
CreatesLongGauge
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:
name
- short counter name following https://opentelemetry.io/docs/reference/specification/metrics/api/#instrument-naming-ruledescription
- free-form text describing the counterunit
- optional unit of measurement.- Returns:
- new instance of
LongGauge
- Throws:
NullPointerException
- if name or description is null.
-
createAttributes
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 interfaceAutoCloseable
-