#19217

Committed 09 May 2024 02:28AM UTC coverage: 88.358% (-0.01%) from 88.369%

Build # #19217

Build Type

push

github

Committed by

ejona86

Commit Message

Add gauge metric API and Otel implementation

This is needed by gRFC A78 for xds metrics, and for RLS metrics. Since
gauges need to acquire a lock (or other synchronization) in the
callback, the callback allows batching multiple gauges together to avoid
acquiring-and-requiring such locks.

Unlike other metrics, gauges are reported on-demand to the MetricSink.
This means not all sinks will receive the same data, as the sinks will
ask for the gauges at different times.

Run Details

31566 of 35725 relevant lines covered (88.36%)

0.88 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/../api/src/main/java/io/grpc/MetricSink.java

/*
 * Copyright 2024 The gRPC Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.grpc;

import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * An internal interface representing a receiver or aggregator of gRPC metrics data.
 */
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11110")
public interface MetricSink {

  /**
   * Returns a set of names for the metrics that are currently enabled or disabled.
   *
   * @return A set of enabled metric names.
   */
  Map<String, Boolean> getEnabledMetrics();

  /**
   * Returns a set of optional label names for metrics that the sink actually wants.
   *
   * @return A set of optional label names.
   */
  Set<String> getOptionalLabels();

  /**
   * Returns size of metric measures used to record metric values. These measures are created
   * based on registered metrics (via MetricInstrumentRegistry) and are ordered according to their
   * registration sequence.
   *
   * @return Size of metric measures.
   */
  int getMeasuresSize();

  /**
   * Adds a value for a double-precision counter associated with specified metric instrument.
   *
   * @param metricInstrument The counter metric instrument identifies metric measure to add.
   * @param value The value to record.
   * @param requiredLabelValues A list of required label values for the metric.
   * @param optionalLabelValues A list of additional, optional label values for the metric.
   */
  default void addDoubleCounter(DoubleCounterMetricInstrument metricInstrument, double value,
      List<String> requiredLabelValues, List<String> optionalLabelValues) {
  }

  /**
   * Adds a value for a long valued counter metric associated with specified metric instrument.
   *
   * @param metricInstrument The counter metric instrument identifies metric measure to add.
   * @param value The value to record.
   * @param requiredLabelValues A list of required label values for the metric.
   * @param optionalLabelValues A list of additional, optional label values for the metric.
   */
  default void addLongCounter(LongCounterMetricInstrument metricInstrument, long value,
      List<String> requiredLabelValues, List<String> optionalLabelValues) {
  }

  /**
   * Records a value for a double-precision histogram metric associated with specified metric
   * instrument.
   *
   * @param metricInstrument The histogram metric instrument identifies metric measure to record.
   * @param value The value to record.
   * @param requiredLabelValues A list of required label values for the metric.
   * @param optionalLabelValues A list of additional, optional label values for the metric.
   */
  default void recordDoubleHistogram(DoubleHistogramMetricInstrument metricInstrument, double value,
      List<String> requiredLabelValues, List<String> optionalLabelValues) {
  }

  /**
   * Records a value for a long valued histogram metric associated with specified metric
   * instrument.
   *
   * @param metricInstrument The histogram metric instrument identifies metric measure to record.
   * @param value The value to record.
   * @param requiredLabelValues A list of required label values for the metric.
   * @param optionalLabelValues A list of additional, optional label values for the metric.
   */
  default void recordLongHistogram(LongHistogramMetricInstrument metricInstrument, long value,
      List<String> requiredLabelValues, List<String> optionalLabelValues) {
  }

  /**
   * Record a long gauge value.
   *
   * @param value The value to record.
   * @param requiredLabelValues A list of required label values for the metric.
   * @param optionalLabelValues A list of additional, optional label values for the metric.
   */
  default void recordLongGauge(LongGaugeMetricInstrument metricInstrument, long value,
      List<String> requiredLabelValues, List<String> optionalLabelValues){
  }

  /**
   * Registers a callback to produce metric values for only the listed instruments. The returned
   * registration must be closed when no longer needed, which will remove the callback.
   *
   * @param callback The callback to call to record.
   * @param metricInstruments The metric instruments the callback will record against.
   */
  default Registration registerBatchCallback(Runnable callback,
      CallbackMetricInstrument... metricInstruments) {
    return () -> { };
  }

  interface Registration extends MetricRecorder.Registration {}

  void updateMeasures(List<MetricInstrument> instruments);
}

1	/*
2	* Copyright 2024 The gRPC Authors
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* http://www.apache.org/licenses/LICENSE-2.0
9	*
10	* Unless required by applicable law or agreed to in writing, software
11	* distributed under the License is distributed on an "AS IS" BASIS,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16
17	package io.grpc;
18
19	import java.util.List;
20	import java.util.Map;
21	import java.util.Set;
22
23	/**
24	* An internal interface representing a receiver or aggregator of gRPC metrics data.
25	*/
26	@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11110")
27	public interface MetricSink {
28
29	/**
30	* Returns a set of names for the metrics that are currently enabled or disabled.
31	*
32	* @return A set of enabled metric names.
33	*/
34	Map<String, Boolean> getEnabledMetrics();
35
36	/**
37	* Returns a set of optional label names for metrics that the sink actually wants.
38	*
39	* @return A set of optional label names.
40	*/
41	Set<String> getOptionalLabels();
42
43	/**
44	* Returns size of metric measures used to record metric values. These measures are created
45	* based on registered metrics (via MetricInstrumentRegistry) and are ordered according to their
46	* registration sequence.
47	*
48	* @return Size of metric measures.
49	*/
50	int getMeasuresSize();
51
52	/**
53	* Adds a value for a double-precision counter associated with specified metric instrument.
54	*
55	* @param metricInstrument The counter metric instrument identifies metric measure to add.
56	* @param value The value to record.
57	* @param requiredLabelValues A list of required label values for the metric.
58	* @param optionalLabelValues A list of additional, optional label values for the metric.
59	*/
60	default void addDoubleCounter(DoubleCounterMetricInstrument metricInstrument, double value,
61	List<String> requiredLabelValues, List<String> optionalLabelValues) {
62	}	×
63
64	/**
65	* Adds a value for a long valued counter metric associated with specified metric instrument.
66	*
67	* @param metricInstrument The counter metric instrument identifies metric measure to add.
68	* @param value The value to record.
69	* @param requiredLabelValues A list of required label values for the metric.
70	* @param optionalLabelValues A list of additional, optional label values for the metric.
71	*/
72	default void addLongCounter(LongCounterMetricInstrument metricInstrument, long value,
73	List<String> requiredLabelValues, List<String> optionalLabelValues) {
74	}	×
75
76	/**
77	* Records a value for a double-precision histogram metric associated with specified metric
78	* instrument.
79	*
80	* @param metricInstrument The histogram metric instrument identifies metric measure to record.
81	* @param value The value to record.
82	* @param requiredLabelValues A list of required label values for the metric.
83	* @param optionalLabelValues A list of additional, optional label values for the metric.
84	*/
85	default void recordDoubleHistogram(DoubleHistogramMetricInstrument metricInstrument, double value,
86	List<String> requiredLabelValues, List<String> optionalLabelValues) {
87	}	×
88
89	/**
90	* Records a value for a long valued histogram metric associated with specified metric
91	* instrument.
92	*
93	* @param metricInstrument The histogram metric instrument identifies metric measure to record.
94	* @param value The value to record.
95	* @param requiredLabelValues A list of required label values for the metric.
96	* @param optionalLabelValues A list of additional, optional label values for the metric.
97	*/
98	default void recordLongHistogram(LongHistogramMetricInstrument metricInstrument, long value,
99	List<String> requiredLabelValues, List<String> optionalLabelValues) {
100	}	×
101
102	/**
103	* Record a long gauge value.
104	*
105	* @param value The value to record.
106	* @param requiredLabelValues A list of required label values for the metric.
107	* @param optionalLabelValues A list of additional, optional label values for the metric.
108	*/
109	default void recordLongGauge(LongGaugeMetricInstrument metricInstrument, long value,
110	List<String> requiredLabelValues, List<String> optionalLabelValues){
111	}	×
112
113	/**
114	* Registers a callback to produce metric values for only the listed instruments. The returned
115	* registration must be closed when no longer needed, which will remove the callback.
116	*
117	* @param callback The callback to call to record.
118	* @param metricInstruments The metric instruments the callback will record against.
119	*/
120	default Registration registerBatchCallback(Runnable callback,
121	CallbackMetricInstrument... metricInstruments) {
122	return () -> { };	×
123	}
124
125	interface Registration extends MetricRecorder.Registration {}
126
127	void updateMeasures(List<MetricInstrument> instruments);
128	}

grpc / grpc-java / #19217

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous