Skip to content

Commit 65e645a

Browse files
westarlewestarle
authored
Merge branch 'main' into feat/actionable-errors-http-parser
2 parents f24b980 + 6a76397 commit 65e645a

16 files changed

Lines changed: 790 additions & 94 deletions

‎gax-java/dependencies.properties‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@ maven.com_google_api_grpc_proto_google_common_protos=com.google.api.grpc:proto-g
3939
maven.com_google_api_grpc_grpc_google_common_protos=com.google.api.grpc:grpc-google-common-protos:2.63.2
4040
maven.com_google_auth_google_auth_library_oauth2_http=com.google.auth:google-auth-library-oauth2-http:1.42.1
4141
maven.com_google_auth_google_auth_library_credentials=com.google.auth:google-auth-library-credentials:1.42.1
42-
maven.io_opentelemetry_opentelemetry_api=io.opentelemetry:opentelemetry-api:1.47.0
43-
maven.io_opentelemetry_opentelemetry_context=io.opentelemetry:opentelemetry-context:1.47.0
42+
maven.io_opentelemetry_opentelemetry_api=io.opentelemetry:opentelemetry-api:1.51.0
43+
maven.io_opentelemetry_opentelemetry_context=io.opentelemetry:opentelemetry-context:1.51.0
4444
maven.io_opencensus_opencensus_api=io.opencensus:opencensus-api:0.31.1
4545
maven.io_opencensus_opencensus_contrib_grpc_metrics=io.opencensus:opencensus-contrib-grpc-metrics:0.31.1
4646
maven.io_opencensus_opencensus_contrib_http_util=io.opencensus:opencensus-contrib-http-util:0.31.1
@@ -91,3 +91,8 @@ maven.net_bytebuddy_byte_buddy=net.bytebuddy:byte-buddy:1.17.0
9191
maven.org_objenesis_objenesis=org.objenesis:objenesis:2.6
9292
maven.org_junit_jupiter_junit_jupiter_api=org.junit.jupiter:junit-jupiter-api:5.11.4
9393
maven.org_junit_jupiter_junit_jupiter_params=org.junit.jupiter:junit-jupiter-params:5.11.4
94+
maven.io_opentelemetry_opentelemetry_sdk_testing=io.opentelemetry:opentelemetry-sdk-testing:1.51.0
95+
maven.io_opentelemetry_opentelemetry_sdk=io.opentelemetry:opentelemetry-sdk:1.51.0
96+
maven.io_opentelemetry_opentelemetry_sdk_common=io.opentelemetry:opentelemetry-sdk-common:1.51.0
97+
maven.io_opentelemetry_opentelemetry_sdk_metrics=io.opentelemetry:opentelemetry-sdk-metrics:1.51.0
98+
maven.com_google_guava_guava_testlib=com.google.guava:guava-testlib:32.1.3-jre

‎gax-java/gax/BUILD.bazel‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,11 @@ _TEST_COMPILE_DEPS = [
4444
"@net_bytebuddy_byte_buddy//jar",
4545
"@org_objenesis_objenesis//jar",
4646
"@com_googlecode_java_diff_utils_diffutils//jar",
47+
"@io_opentelemetry_opentelemetry_sdk_testing//jar",
48+
"@io_opentelemetry_opentelemetry_sdk//jar",
49+
"@io_opentelemetry_opentelemetry_sdk_metrics//jar",
50+
"@io_opentelemetry_opentelemetry_sdk_common//jar",
51+
"@com_google_guava_guava_testlib//jar",
4752
]
4853

4954
java_library(

‎gax-java/gax/pom.xml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,17 @@
7878
<artifactId>opentelemetry-context</artifactId>
7979
<optional>true</optional>
8080
</dependency>
81+
<dependency>
82+
<groupId>io.opentelemetry</groupId>
83+
<artifactId>opentelemetry-sdk-testing</artifactId>
84+
<scope>test</scope>
85+
</dependency>
86+
<dependency>
87+
<groupId>com.google.guava</groupId>
88+
<artifactId>guava-testlib</artifactId>
89+
<version>${guava.version}</version>
90+
<scope>test</scope>
91+
</dependency>
8192
<!-- Logging dependency -->
8293
<dependency>
8394
<groupId>org.slf4j</groupId>

‎gax-java/gax/src/main/java/com/google/api/gax/tracing/GoldenSignalsMetricsRecorder.java‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Redistribution and use in source and binary forms, with or without
5+
* modification, are permitted provided that the following conditions are
6+
* met:
7+
*
8+
* * Redistributions of source code must retain the above copyright
9+
* notice, this list of conditions and the following disclaimer.
10+
* * Redistributions in binary form must reproduce the above
11+
* copyright notice, this list of conditions and the following disclaimer
12+
* in the documentation and/or other materials provided with the
13+
* distribution.
14+
* * Neither the name of Google LLC nor the names of its
15+
* contributors may be used to endorse or promote products derived from
16+
* this software without specific prior written permission.
17+
*
18+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
*/
30+
package com.google.api.gax.tracing;
31+
32+
import io.opentelemetry.api.OpenTelemetry;
33+
import io.opentelemetry.api.metrics.DoubleHistogram;
34+
import io.opentelemetry.api.metrics.Meter;
35+
import java.util.Arrays;
36+
import java.util.List;
37+
import java.util.Map;
38+
39+
/**
40+
* This class takes an OpenTelemetry object, and creates instruments (meters, histograms etc.) from
41+
* it for recording golden signal metrics. There must be only one instance of
42+
* GoldenSignalsMetricsRecorder per client, all the methods in this class are expected to be called
43+
* from multiple threads, hence they need to be thread safe.
44+
*/
45+
class GoldenSignalsMetricsRecorder {
46+
static final String CLIENT_REQUEST_DURATION_METRIC_NAME = "gcp.client.request.duration";
47+
static final String CLIENT_REQUEST_DURATION_METRIC_DESCRIPTION =
48+
"Measures the total time taken for a logical client request, including any retries, backoff, and pre/post-processing";
49+
50+
static final List<Double> BOUNDARIES =
51+
Arrays.asList(
52+
0.0, 0.0001, 0.0005, 0.0010, 0.005, 0.010, 0.050, 0.100, 0.5, 1.0, 5.0, 10.0, 60.0, 300.0,
53+
900.0, 3600.0);
54+
final DoubleHistogram clientRequestDurationRecorder;
55+
56+
GoldenSignalsMetricsRecorder(OpenTelemetry openTelemetry, String libraryName) {
57+
Meter meter = openTelemetry.meterBuilder(libraryName).build();
58+
59+
this.clientRequestDurationRecorder =
60+
meter
61+
.histogramBuilder(CLIENT_REQUEST_DURATION_METRIC_NAME)
62+
.setDescription(CLIENT_REQUEST_DURATION_METRIC_DESCRIPTION)
63+
.setUnit("s")
64+
.setExplicitBucketBoundariesAdvice(BOUNDARIES)
65+
.build();
66+
}
67+
68+
void recordOperationLatency(double operationLatency, Map<String, String> attributes) {
69+
clientRequestDurationRecorder.record(
70+
operationLatency, ObservabilityUtils.toOtelAttributes(attributes));
71+
}
72+
}

‎gax-java/gax/src/main/java/com/google/api/gax/tracing/GoldenSignalsMetricsTracer.java‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Redistribution and use in source and binary forms, with or without
5+
* modification, are permitted provided that the following conditions are
6+
* met:
7+
*
8+
* * Redistributions of source code must retain the above copyright
9+
* notice, this list of conditions and the following disclaimer.
10+
* * Redistributions in binary form must reproduce the above
11+
* copyright notice, this list of conditions and the following disclaimer
12+
* in the documentation and/or other materials provided with the
13+
* distribution.
14+
* * Neither the name of Google LLC nor the names of its
15+
* contributors may be used to endorse or promote products derived from
16+
* this software without specific prior written permission.
17+
*
18+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
*/
30+
package com.google.api.gax.tracing;
31+
32+
import static com.google.api.gax.tracing.ObservabilityAttributes.RPC_RESPONSE_STATUS_ATTRIBUTE;
33+
34+
import com.google.api.gax.rpc.StatusCode;
35+
import com.google.common.annotations.VisibleForTesting;
36+
import com.google.common.base.Stopwatch;
37+
import com.google.common.base.Ticker;
38+
import java.util.HashMap;
39+
import java.util.Map;
40+
import java.util.concurrent.TimeUnit;
41+
42+
/**
43+
* This class computes golden signal metrics that can be observed in the lifecycle of an RPC
44+
* operation. The responsibility of recording metrics should delegate to {@link
45+
* GoldenSignalsMetricsRecorder}, hence this class should not have any knowledge about the
46+
* observability framework (e.g. OpenTelemetry).
47+
*/
48+
class GoldenSignalsMetricsTracer implements ApiTracer {
49+
private final Stopwatch clientRequestTimer;
50+
private final GoldenSignalsMetricsRecorder metricsRecorder;
51+
private final Map<String, String> attributes = new HashMap<>();
52+
53+
/**
54+
* Creates the following instruments for the following metrics:
55+
*
56+
* <ul>
57+
* <li>Client Request Duration: Histogram
58+
* </ul>
59+
*
60+
* @param metricsRecorder OpenTelemetry
61+
*/
62+
GoldenSignalsMetricsTracer(GoldenSignalsMetricsRecorder metricsRecorder) {
63+
this.clientRequestTimer = Stopwatch.createStarted();
64+
this.metricsRecorder = metricsRecorder;
65+
}
66+
67+
@VisibleForTesting
68+
GoldenSignalsMetricsTracer(GoldenSignalsMetricsRecorder metricsRecorder, Ticker ticker) {
69+
this.clientRequestTimer = Stopwatch.createStarted(ticker);
70+
this.metricsRecorder = metricsRecorder;
71+
}
72+
73+
/**
74+
* The concept of "operation" and "client request" are the same. They both represent the total
75+
* time taken for a logical client request, including any retries, backoff, and
76+
* pre/post-processing
77+
*/
78+
@Override
79+
public void operationSucceeded() {
80+
attributes.put(RPC_RESPONSE_STATUS_ATTRIBUTE, StatusCode.Code.OK.toString());
81+
metricsRecorder.recordOperationLatency(
82+
clientRequestTimer.elapsed(TimeUnit.NANOSECONDS) / 1_000_000_000.0, attributes);
83+
}
84+
85+
@Override
86+
public void operationCancelled() {
87+
attributes.put(RPC_RESPONSE_STATUS_ATTRIBUTE, StatusCode.Code.CANCELLED.toString());
88+
metricsRecorder.recordOperationLatency(
89+
clientRequestTimer.elapsed(TimeUnit.NANOSECONDS) / 1_000_000_000.0, attributes);
90+
}
91+
92+
@Override
93+
public void operationFailed(Throwable error) {
94+
attributes.put(RPC_RESPONSE_STATUS_ATTRIBUTE, ObservabilityUtils.extractStatus(error));
95+
metricsRecorder.recordOperationLatency(
96+
clientRequestTimer.elapsed(TimeUnit.NANOSECONDS) / 1_000_000_000.0, attributes);
97+
}
98+
}

‎gax-java/gax/src/main/java/com/google/api/gax/tracing/GoldenSignalsMetricsTracerFactory.java‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Redistribution and use in source and binary forms, with or without
5+
* modification, are permitted provided that the following conditions are
6+
* met:
7+
*
8+
* * Redistributions of source code must retain the above copyright
9+
* notice, this list of conditions and the following disclaimer.
10+
* * Redistributions in binary form must reproduce the above
11+
* copyright notice, this list of conditions and the following disclaimer
12+
* in the documentation and/or other materials provided with the
13+
* distribution.
14+
* * Neither the name of Google LLC nor the names of its
15+
* contributors may be used to endorse or promote products derived from
16+
* this software without specific prior written permission.
17+
*
18+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
*/
30+
package com.google.api.gax.tracing;
31+
32+
import com.google.api.core.BetaApi;
33+
import com.google.api.core.InternalApi;
34+
import io.opentelemetry.api.OpenTelemetry;
35+
36+
/**
37+
* A {@link ApiTracerFactory} to build instances of {@link GoldenSignalsMetricsTracer}.
38+
*
39+
* <p>This class is expected to be initialized once during client initialization.
40+
*/
41+
@BetaApi
42+
@InternalApi
43+
public class GoldenSignalsMetricsTracerFactory implements ApiTracerFactory {
44+
45+
private ApiTracerContext apiTracerContext;
46+
private final OpenTelemetry openTelemetry;
47+
private GoldenSignalsMetricsRecorder metricsRecorder;
48+
49+
public GoldenSignalsMetricsTracerFactory(OpenTelemetry openTelemetry) {
50+
this.openTelemetry = openTelemetry;
51+
}
52+
53+
@Override
54+
public ApiTracer newTracer(ApiTracer parent, SpanName spanName, OperationType operationType) {
55+
if (metricsRecorder == null) {
56+
// This should never happen, in case it happens, create a no-op api tracer to not block
57+
// regular requests.
58+
return new BaseApiTracer();
59+
}
60+
return new GoldenSignalsMetricsTracer(metricsRecorder);
61+
}
62+
63+
@Override
64+
public ApiTracerFactory withContext(ApiTracerContext context) {
65+
this.apiTracerContext = context;
66+
this.metricsRecorder =
67+
new GoldenSignalsMetricsRecorder(
68+
openTelemetry, apiTracerContext.libraryMetadata().artifactName());
69+
return this;
70+
}
71+
}

‎gax-java/gax/src/main/java/com/google/api/gax/tracing/MetricsTracer.java‎

Lines changed: 4 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -35,16 +35,13 @@
3535
import com.google.api.core.BetaApi;
3636
import com.google.api.core.InternalApi;
3737
import com.google.api.core.ObsoleteApi;
38-
import com.google.api.gax.rpc.ApiException;
3938
import com.google.api.gax.rpc.StatusCode;
4039
import com.google.common.annotations.VisibleForTesting;
4140
import com.google.common.base.Stopwatch;
4241
import java.util.HashMap;
4342
import java.util.Map;
44-
import java.util.concurrent.CancellationException;
4543
import java.util.concurrent.TimeUnit;
4644
import java.util.concurrent.atomic.AtomicBoolean;
47-
import javax.annotation.Nullable;
4845

4946
/**
5047
* This class computes generic metrics that can be observed in the lifecycle of an RPC operation.
@@ -123,7 +120,7 @@ public void operationFailed(Throwable error) {
123120
if (operationFinished.getAndSet(true)) {
124121
throw new IllegalStateException(OPERATION_FINISHED_STATUS_MESSAGE);
125122
}
126-
attributes.put(STATUS_ATTRIBUTE, extractStatus(error));
123+
attributes.put(STATUS_ATTRIBUTE, ObservabilityUtils.extractStatus(error));
127124
metricsRecorder.recordOperationLatency(
128125
operationTimer.elapsed(TimeUnit.MILLISECONDS), attributes);
129126
metricsRecorder.recordOperationCount(1, attributes);
@@ -175,7 +172,7 @@ public void attemptCancelled() {
175172
*/
176173
@Override
177174
public void attemptFailedDuration(Throwable error, java.time.Duration delay) {
178-
attributes.put(STATUS_ATTRIBUTE, extractStatus(error));
175+
attributes.put(STATUS_ATTRIBUTE, ObservabilityUtils.extractStatus(error));
179176
metricsRecorder.recordAttemptLatency(attemptTimer.elapsed(TimeUnit.MILLISECONDS), attributes);
180177
metricsRecorder.recordAttemptCount(1, attributes);
181178
}
@@ -199,7 +196,7 @@ public void attemptFailed(Throwable error, org.threeten.bp.Duration delay) {
199196
*/
200197
@Override
201198
public void attemptFailedRetriesExhausted(Throwable error) {
202-
attributes.put(STATUS_ATTRIBUTE, extractStatus(error));
199+
attributes.put(STATUS_ATTRIBUTE, ObservabilityUtils.extractStatus(error));
203200
metricsRecorder.recordAttemptLatency(attemptTimer.elapsed(TimeUnit.MILLISECONDS), attributes);
204201
metricsRecorder.recordAttemptCount(1, attributes);
205202
}
@@ -213,29 +210,11 @@ public void attemptFailedRetriesExhausted(Throwable error) {
213210
*/
214211
@Override
215212
public void attemptPermanentFailure(Throwable error) {
216-
attributes.put(STATUS_ATTRIBUTE, extractStatus(error));
213+
attributes.put(STATUS_ATTRIBUTE, ObservabilityUtils.extractStatus(error));
217214
metricsRecorder.recordAttemptLatency(attemptTimer.elapsed(TimeUnit.MILLISECONDS), attributes);
218215
metricsRecorder.recordAttemptCount(1, attributes);
219216
}
220217

221-
/** Function to extract the status of the error as a string */
222-
@VisibleForTesting
223-
static String extractStatus(@Nullable Throwable error) {
224-
final String statusString;
225-
226-
if (error == null) {
227-
return StatusCode.Code.OK.toString();
228-
} else if (error instanceof CancellationException) {
229-
statusString = StatusCode.Code.CANCELLED.toString();
230-
} else if (error instanceof ApiException) {
231-
statusString = ((ApiException) error).getStatusCode().getCode().toString();
232-
} else {
233-
statusString = StatusCode.Code.UNKNOWN.toString();
234-
}
235-
236-
return statusString;
237-
}
238-
239218
/**
240219
* Add attributes that will be attached to all metrics. This is expected to be called by
241220
* handwritten client teams to add additional attributes that are not supposed be collected by

‎gax-java/gax/src/main/java/com/google/api/gax/tracing/ObservabilityAttributes.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,4 +58,10 @@ public class ObservabilityAttributes {
5858

5959
/** The RPC system name, e.g. 'grpc' or 'http'. */
6060
public static final String RPC_SYSTEM_NAME_ATTRIBUTE = "rpc.system.name";
61+
62+
/**
63+
* The error codes of the request. The value will be the string representation of the canonical
64+
* gRPC status code (e.g., "OK", "INTERNAL").
65+
*/
66+
public static final String RPC_RESPONSE_STATUS_ATTRIBUTE = "rpc.response.status_code";
6167
}

0 commit comments

Comments
 (0)