Skip to content

Commit 865c099

Browse files
westarlewestarle
committed
feat(gax): implement actionable errors logging in ApiTracer framework
1 parent a0df2ff commit 865c099

File tree

3 files changed

+271
-0
lines changed

3 files changed

+271
-0
lines changed

‎gax-java/gax/src/main/java/com/google/api/gax/rpc/ClientContext.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,9 @@ public static ClientContext create(StubSettings settings) throws IOException {
281281
if (apiTracerFactory instanceof SpanTracerFactory) {
282282
apiTracerFactory = apiTracerFactory.withContext(apiTracerContext);
283283
}
284+
if (com.google.api.gax.logging.LoggingUtils.isLoggingEnabled()) {
285+
apiTracerFactory = new com.google.api.gax.tracing.LoggingTracerFactory(apiTracerFactory);
286+
}
284287

285288
return newBuilder()
286289
.setBackgroundResources(backgroundResources.build())

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

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
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+
31+
package com.google.api.gax.tracing;
32+
33+
import com.google.api.core.BetaApi;
34+
import com.google.api.core.InternalApi;
35+
import com.google.api.gax.logging.LoggerProvider;
36+
import com.google.api.gax.logging.LoggingUtils;
37+
import com.google.api.gax.rpc.ApiException;
38+
import com.google.rpc.ErrorInfo;
39+
import java.util.HashMap;
40+
import java.util.Map;
41+
42+
/**
43+
* A decorator for {@link ApiTracer} that logs actionable errors using {@link LoggingUtils} when an
44+
* RPC attempt fails.
45+
*/
46+
@BetaApi
47+
@InternalApi
48+
public class LoggingTracer implements ApiTracer {
49+
private static final LoggerProvider LOGGER_PROVIDER =
50+
LoggerProvider.forClazz(LoggingTracer.class);
51+
52+
private final ApiTracer delegate;
53+
private final ApiTracerContext apiTracerContext;
54+
55+
public LoggingTracer(ApiTracer delegate, ApiTracerContext apiTracerContext) {
56+
this.delegate = delegate;
57+
this.apiTracerContext = apiTracerContext;
58+
}
59+
60+
@Override
61+
public Scope inScope() {
62+
return delegate.inScope();
63+
}
64+
65+
@Override
66+
public void operationSucceeded() {
67+
delegate.operationSucceeded();
68+
}
69+
70+
@Override
71+
public void operationCancelled() {
72+
delegate.operationCancelled();
73+
}
74+
75+
@Override
76+
public void operationFailed(Throwable error) {
77+
delegate.operationFailed(error);
78+
}
79+
80+
@Override
81+
public void connectionSelected(String id) {
82+
delegate.connectionSelected(id);
83+
}
84+
85+
@Override
86+
public void attemptStarted(int attemptNumber) {
87+
delegate.attemptStarted(attemptNumber);
88+
}
89+
90+
@Override
91+
public void attemptStarted(Object request, int attemptNumber) {
92+
delegate.attemptStarted(request, attemptNumber);
93+
}
94+
95+
@Override
96+
public void attemptSucceeded() {
97+
delegate.attemptSucceeded();
98+
}
99+
100+
@Override
101+
public void attemptCancelled() {
102+
delegate.attemptCancelled();
103+
}
104+
105+
@Override
106+
public void attemptFailed(Throwable error, org.threeten.bp.Duration delay) {
107+
recordActionableError(error);
108+
delegate.attemptFailed(error, delay);
109+
}
110+
111+
@Override
112+
public void attemptFailedDuration(Throwable error, java.time.Duration delay) {
113+
recordActionableError(error);
114+
delegate.attemptFailedDuration(error, delay);
115+
}
116+
117+
@Override
118+
public void attemptFailedRetriesExhausted(Throwable error) {
119+
recordActionableError(error);
120+
delegate.attemptFailedRetriesExhausted(error);
121+
}
122+
123+
@Override
124+
public void attemptPermanentFailure(Throwable error) {
125+
recordActionableError(error);
126+
delegate.attemptPermanentFailure(error);
127+
}
128+
129+
@Override
130+
public void lroStartFailed(Throwable error) {
131+
delegate.lroStartFailed(error);
132+
}
133+
134+
@Override
135+
public void lroStartSucceeded() {
136+
delegate.lroStartSucceeded();
137+
}
138+
139+
@Override
140+
public void responseReceived() {
141+
delegate.responseReceived();
142+
}
143+
144+
@Override
145+
public void requestSent() {
146+
delegate.requestSent();
147+
}
148+
149+
@Override
150+
public void batchRequestSent(long elementCount, long requestSize) {
151+
delegate.batchRequestSent(elementCount, requestSize);
152+
}
153+
154+
private void recordActionableError(Throwable error) {
155+
Map<String, Object> logContext = new HashMap<>();
156+
157+
if (apiTracerContext.rpcSystemName() != null) {
158+
logContext.put(
159+
ObservabilityAttributes.RPC_SYSTEM_NAME_ATTRIBUTE, apiTracerContext.rpcSystemName());
160+
}
161+
if (apiTracerContext.fullMethodName() != null) {
162+
logContext.put(
163+
ObservabilityAttributes.GRPC_RPC_METHOD_ATTRIBUTE, apiTracerContext.fullMethodName());
164+
}
165+
if (apiTracerContext.serverPort() != null) {
166+
logContext.put(ObservabilityAttributes.SERVER_PORT_ATTRIBUTE, apiTracerContext.serverPort());
167+
}
168+
if (apiTracerContext.libraryMetadata() != null
169+
&& !apiTracerContext.libraryMetadata().isEmpty()) {
170+
if (apiTracerContext.libraryMetadata().repository() != null) {
171+
logContext.put(
172+
ObservabilityAttributes.REPO_ATTRIBUTE,
173+
apiTracerContext.libraryMetadata().repository());
174+
}
175+
}
176+
177+
if (error instanceof ApiException) {
178+
ApiException apiException = (ApiException) error;
179+
logContext.put(
180+
ObservabilityAttributes.RPC_RESPONSE_STATUS_ATTRIBUTE,
181+
apiException.getStatusCode().getCode().toString());
182+
183+
if (apiException.getErrorDetails() != null) {
184+
ErrorInfo errorInfo = apiException.getErrorDetails().getErrorInfo();
185+
if (errorInfo != null) {
186+
logContext.put("error.type", errorInfo.getReason());
187+
logContext.put("gcp.errors.domain", errorInfo.getDomain());
188+
for (Map.Entry<String, String> entry : errorInfo.getMetadataMap().entrySet()) {
189+
logContext.put("gcp.errors.metadata." + entry.getKey(), entry.getValue());
190+
}
191+
}
192+
}
193+
}
194+
195+
String message = error.getMessage() != null ? error.getMessage() : error.getClass().getName();
196+
LoggingUtils.logActionableError(
197+
logContext, LOGGER_PROVIDER, org.slf4j.event.Level.INFO, message);
198+
}
199+
}

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

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
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+
31+
package com.google.api.gax.tracing;
32+
33+
import com.google.api.core.BetaApi;
34+
import com.google.api.core.InternalApi;
35+
36+
/**
37+
* A decorator for {@link ApiTracerFactory} that wraps the created tracers in a {@link
38+
* LoggingTracer}.
39+
*/
40+
@BetaApi
41+
@InternalApi
42+
public class LoggingTracerFactory implements ApiTracerFactory {
43+
private final ApiTracerFactory delegate;
44+
45+
public LoggingTracerFactory(ApiTracerFactory delegate) {
46+
this.delegate = delegate;
47+
}
48+
49+
@Override
50+
public ApiTracer newTracer(ApiTracer parent, SpanName spanName, OperationType operationType) {
51+
return new LoggingTracer(
52+
delegate.newTracer(parent, spanName, operationType), delegate.getApiTracerContext());
53+
}
54+
55+
@Override
56+
public ApiTracer newTracer(ApiTracer parent, ApiTracerContext context) {
57+
return new LoggingTracer(delegate.newTracer(parent, context), context);
58+
}
59+
60+
@Override
61+
public ApiTracerContext getApiTracerContext() {
62+
return delegate.getApiTracerContext();
63+
}
64+
65+
@Override
66+
public ApiTracerFactory withContext(ApiTracerContext context) {
67+
return new LoggingTracerFactory(delegate.withContext(context));
68+
}
69+
}

0 commit comments

Comments
 (0)