#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/MetricRecorder.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;

/**
 * An interface used for recording gRPC metrics. Implementations of this interface are responsible
 * for collecting and potentially reporting metrics from various gRPC components.
 */
@Internal
public interface MetricRecorder {
  /**
   * Adds a value for a double-precision counter metric instrument.
   *
   * @param metricInstrument The counter metric instrument to add the value against.
   * @param value The value to add.
   * @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 instrument.
   *
   * @param metricInstrument The counter metric instrument to add the value against.
   * @param value The value to add.
   * @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 instrument.
   *
   * @param metricInstrument The histogram metric instrument to record the value against.
   * @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 instrument.
   *
   * @param metricInstrument The histogram metric instrument to record the value against.
   * @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) {}

  /**
   * 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(BatchCallback callback,
      CallbackMetricInstrument... metricInstruments) {
    return () -> { };
  }

  /** Callback to record gauge values. */
  interface BatchCallback {
    /** Records instrument values into {@code recorder}. */
    void accept(BatchRecorder recorder);
  }

  /** Recorder for instrument values produced by a batch callback. */
  interface BatchRecorder {
    /**
     * 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.
     */
    void recordLongGauge(LongGaugeMetricInstrument metricInstrument, long value,
        List<String> requiredLabelValues, List<String> optionalLabelValues);
  }

  /** A handle to a registration, that allows unregistration. */
  interface Registration extends AutoCloseable {
    // Redefined to not throw an exception.
    /** Unregister. */
    @Override
    void close();
  }
}

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
21	/**
22	* An interface used for recording gRPC metrics. Implementations of this interface are responsible
23	* for collecting and potentially reporting metrics from various gRPC components.
24	*/
25	@Internal
26	public interface MetricRecorder {
27	/**
28	* Adds a value for a double-precision counter metric instrument.
29	*
30	* @param metricInstrument The counter metric instrument to add the value against.
31	* @param value The value to add.
32	* @param requiredLabelValues A list of required label values for the metric.
33	* @param optionalLabelValues A list of additional, optional label values for the metric.
34	*/
35	default void addDoubleCounter(DoubleCounterMetricInstrument metricInstrument, double value,
36	List<String> requiredLabelValues, List<String> optionalLabelValues) {}	×
37
38	/**
39	* Adds a value for a long valued counter metric instrument.
40	*
41	* @param metricInstrument The counter metric instrument to add the value against.
42	* @param value The value to add.
43	* @param requiredLabelValues A list of required label values for the metric.
44	* @param optionalLabelValues A list of additional, optional label values for the metric.
45	*/
46	default void addLongCounter(LongCounterMetricInstrument metricInstrument, long value,
47	List<String> requiredLabelValues, List<String> optionalLabelValues) {}	×
48
49	/**
50	* Records a value for a double-precision histogram metric instrument.
51	*
52	* @param metricInstrument The histogram metric instrument to record the value against.
53	* @param value The value to record.
54	* @param requiredLabelValues A list of required label values for the metric.
55	* @param optionalLabelValues A list of additional, optional label values for the metric.
56	*/
57	default void recordDoubleHistogram(DoubleHistogramMetricInstrument metricInstrument, double value,
58	List<String> requiredLabelValues, List<String> optionalLabelValues) {}	×
59
60	/**
61	* Records a value for a long valued histogram metric instrument.
62	*
63	* @param metricInstrument The histogram metric instrument to record the value against.
64	* @param value The value to record.
65	* @param requiredLabelValues A list of required label values for the metric.
66	* @param optionalLabelValues A list of additional, optional label values for the metric.
67	*/
68	default void recordLongHistogram(LongHistogramMetricInstrument metricInstrument, long value,
69	List<String> requiredLabelValues, List<String> optionalLabelValues) {}	×
70
71	/**
72	* Registers a callback to produce metric values for only the listed instruments. The returned
73	* registration must be closed when no longer needed, which will remove the callback.
74	*
75	* @param callback The callback to call to record.
76	* @param metricInstruments The metric instruments the callback will record against.
77	*/
78	default Registration registerBatchCallback(BatchCallback callback,
79	CallbackMetricInstrument... metricInstruments) {
80	return () -> { };	×
81	}
82
83	/** Callback to record gauge values. */
84	interface BatchCallback {
85	/** Records instrument values into {@code recorder}. */
86	void accept(BatchRecorder recorder);
87	}
88
89	/** Recorder for instrument values produced by a batch callback. */
90	interface BatchRecorder {
91	/**
92	* Record a long gauge value.
93	*
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	void recordLongGauge(LongGaugeMetricInstrument metricInstrument, long value,
99	List<String> requiredLabelValues, List<String> optionalLabelValues);
100	}
101
102	/** A handle to a registration, that allows unregistration. */
103	interface Registration extends AutoCloseable {
104	// Redefined to not throw an exception.
105	/** Unregister. */
106	@Override
107	void close();
108	}
109	}

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