Skip to content

Commit 54c9684

Browse files
committed
feat(gax): add logNetworkAttempt to LoggerHelper
1 parent d9c6f13 commit 54c9684

2 files changed

Lines changed: 264 additions & 36 deletions

File tree

‎core/packages/gax/src/observability/LoggerHelper.ts‎

Lines changed: 119 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ import {
3535
resolveExceptionMessage,
3636
resolveExceptionStacktrace,
3737
resolveExceptionType,
38+
resolveResponsePayload,
3839
resolveResponseStatusCode,
3940
resolveRpcStatusName,
4041
} from './errorUtil';
@@ -61,6 +62,22 @@ export interface LogPayload {
6162
'exception.stacktrace'?: string;
6263
}
6364

65+
/**
66+
* Resolves a `LogSeverity` value across `google-logging-utils` versions where
67+
* `LogSeverity` may be exported as a type only.
68+
*/
69+
function resolveLogSeverity(
70+
level: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR',
71+
): loggingUtils.LogSeverity {
72+
return (
73+
(
74+
loggingUtils as {
75+
LogSeverity?: Record<string, loggingUtils.LogSeverity>;
76+
}
77+
).LogSeverity?.[level] ?? (level as loggingUtils.LogSeverity)
78+
);
79+
}
80+
6481
/**
6582
* Returns the `google-logging-utils` logger for the given GCP client service,
6683
* defaulting to the `'google-gax'` namespace when no service name is provided.
@@ -153,6 +170,48 @@ export function buildLogAttributes(
153170
return attributes;
154171
}
155172

173+
/**
174+
* Executes `fn` and attaches stream, promise, callback, or synchronous error
175+
* handlers to invoke `onError` when the operation fails.
176+
*/
177+
function executeLoggedOperation<T>(
178+
fn: (loggedCallback?: APICallback) => T,
179+
onError: (err: unknown) => void,
180+
isStreamCall: boolean,
181+
userCallback?: APICallback,
182+
): T {
183+
// Wrap user callback to log RPC errors before forwarding.
184+
let callbackInvoked = false;
185+
const loggedCallback: APICallback | undefined = userCallback
186+
? function (this: unknown, ...args: Parameters<APICallback>) {
187+
callbackInvoked = true;
188+
const err = args[0];
189+
if (err) {
190+
onError(err);
191+
}
192+
userCallback.apply(this, args);
193+
}
194+
: undefined;
195+
196+
// Execute call and attach error handlers for streams, promises, or sync throws.
197+
try {
198+
const result = fn(loggedCallback);
199+
const promiseTarget = !isStreamCall ? getPromiseTarget(result) : null;
200+
if (isStreamCall && result instanceof EventEmitter) {
201+
handleStream(result, onError, () => {}, Boolean(loggedCallback));
202+
} else if (promiseTarget) {
203+
handlePromise(promiseTarget, onError, () => {});
204+
}
205+
return result;
206+
} catch (syncErr) {
207+
// Avoid logging errors thrown inside userCallback after RPC completion.
208+
if (!callbackInvoked) {
209+
onError(syncErr);
210+
}
211+
throw syncErr;
212+
}
213+
}
214+
156215
/**
157216
* Executes an API call and emits a single `WARNING` log entry if the logical
158217
* request fails across promise, callback, stream, or synchronous execution boundaries.
@@ -201,17 +260,10 @@ export function logCall<T = GaxCallResult>(
201260
// Build structured log attributes with exception details.
202261
const attributes = buildLogAttributes(err, dynamicArgs, staticArgs);
203262

204-
const warningSeverity =
205-
(
206-
loggingUtils as {
207-
LogSeverity?: {WARNING: loggingUtils.LogSeverity};
208-
}
209-
).LogSeverity?.WARNING ?? ('WARNING' as loggingUtils.LogSeverity);
210-
211263
// Emit structured WARNING log.
212264
logger(
213265
{
214-
severity: warningSeverity,
266+
severity: resolveLogSeverity('WARNING'),
215267
...(traceId ? {telemetryTraceId: traceId} : {}),
216268
...(spanId ? {telemetrySpanId: spanId} : {}),
217269
other: attributes,
@@ -221,34 +273,65 @@ export function logCall<T = GaxCallResult>(
221273
);
222274
};
223275

224-
// Wrap user callback to log RPC errors before forwarding.
225-
let callbackInvoked = false;
226-
const loggedCallback: APICallback | undefined = userCallback
227-
? function (this: unknown, ...args: Parameters<APICallback>) {
228-
callbackInvoked = true;
229-
const err = args[0];
230-
if (err) {
231-
emitL3WarnLog(err);
232-
}
233-
userCallback.apply(this, args);
234-
}
235-
: undefined;
276+
return executeLoggedOperation(fn, emitL3WarnLog, isStreamCall, userCallback);
277+
}
236278

237-
// Execute call and attach error handlers for streams, promises, or sync throws.
238-
try {
239-
const result = fn(loggedCallback);
240-
const promiseTarget = !isStreamCall ? getPromiseTarget(result) : null;
241-
if (isStreamCall && result instanceof EventEmitter) {
242-
handleStream(result, emitL3WarnLog, () => {}, Boolean(loggedCallback));
243-
} else if (promiseTarget) {
244-
handlePromise(promiseTarget, emitL3WarnLog, () => {});
245-
}
246-
return result;
247-
} catch (syncErr) {
248-
// Avoid logging errors thrown inside userCallback after RPC completion.
249-
if (!callbackInvoked) {
250-
emitL3WarnLog(syncErr);
279+
/**
280+
* Executes an individual RPC transport attempt and emits a `DEBUG` log entry
281+
* if the attempt fails across promise, callback, stream, or synchronous execution boundaries.
282+
*
283+
* @template T
284+
* @param {AttemptTraceContext} attemptDynamicArgs - Dynamic context for the RPC attempt.
285+
* @param {StaticTraceContext} staticArgs - Static context for the client library.
286+
* @param {function} fn - The transport attempt operation to execute. Receives the wrapped
287+
* callback when `userCallback` is supplied, otherwise `undefined`.
288+
* @param {boolean} [isStreamCall=false] - Whether the operation returns a stream (`EventEmitter`).
289+
* @param {APICallback} [userCallback] - Optional attempt callback.
290+
* @returns {T} The return value of `fn`.
291+
*/
292+
export function logNetworkAttempt<T = GaxCallResult>(
293+
attemptDynamicArgs: AttemptTraceContext,
294+
staticArgs: StaticTraceContext,
295+
fn: (loggedCallback?: APICallback) => T,
296+
isStreamCall = false,
297+
userCallback?: APICallback,
298+
): T {
299+
// Snapshot attempt context in case async rejection loses active context.
300+
const initialContext = context.active();
301+
302+
const emitL4DebugLog = (err: unknown) => {
303+
// Resolve logger and active T4 attempt span context for this attempt.
304+
const logger = getGaxLogger(staticArgs?.gcpClientService);
305+
const attemptSpan =
306+
getActiveTraceContext()?.attemptSpan ??
307+
getActiveTraceContext(initialContext)?.attemptSpan;
308+
const spanContext = attemptSpan?.spanContext();
309+
const traceId = spanContext?.traceId;
310+
const spanId = spanContext?.spanId;
311+
312+
// Build structured log attributes and attach attempt metadata payload.
313+
const attributes = buildLogAttributes(err, attemptDynamicArgs, staticArgs);
314+
const responsePayload = resolveResponsePayload(
315+
(err as {metadata?: unknown} | null | undefined)?.metadata,
316+
);
317+
if (responsePayload !== undefined) {
318+
attributes['response.payload'] = responsePayload;
251319
}
252-
throw syncErr;
253-
}
320+
321+
// Emit structured DEBUG log for the failed attempt.
322+
const message = resolveExceptionMessage(err, attemptDynamicArgs.rpcType);
323+
logger(
324+
{
325+
severity: resolveLogSeverity('DEBUG'),
326+
...(traceId ? {telemetryTraceId: traceId} : {}),
327+
...(spanId ? {telemetrySpanId: spanId} : {}),
328+
other: attributes,
329+
},
330+
'RPC attempt failed: %s',
331+
message || err,
332+
);
333+
};
334+
335+
// Intercept and dispatch execution boundaries for the attempt.
336+
return executeLoggedOperation(fn, emitL4DebugLog, isStreamCall, userCallback);
254337
}

‎core/packages/gax/test/unit/loggerHelper.ts‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ import {
2424
buildLogAttributes,
2525
getGaxLogger,
2626
logCall,
27+
logNetworkAttempt,
2728
LogPayload,
2829
} from '../../src/observability/LoggerHelper';
2930
import {traceAttempt, traceCall} from '../../src/observability/TracerHelper';
@@ -671,4 +672,148 @@ describe('LoggerHelper', () => {
671672
);
672673
});
673674
});
675+
676+
describe('logNetworkAttempt', () => {
677+
it('does not log when an attempt succeeds across promise, callback, stream, or sync boundaries', async () => {
678+
const asyncResult = await logNetworkAttempt(
679+
dynamicArgs,
680+
staticArgs,
681+
async () => ({ok: true}),
682+
);
683+
assert.deepStrictEqual(asyncResult, {ok: true});
684+
685+
const syncResult = logNetworkAttempt(dynamicArgs, staticArgs, () => 42);
686+
assert.strictEqual(syncResult, 42);
687+
688+
let callbackResult: unknown;
689+
logNetworkAttempt(
690+
dynamicArgs,
691+
staticArgs,
692+
loggedCallback => {
693+
loggedCallback!(null, {cb: true});
694+
return undefined as unknown as ResultTuple;
695+
},
696+
false,
697+
(_err, res) => {
698+
callbackResult = res;
699+
},
700+
);
701+
assert.deepStrictEqual(callbackResult, {cb: true});
702+
703+
const stream = new EventEmitter();
704+
logNetworkAttempt(dynamicArgs, staticArgs, () => stream, true);
705+
stream.emit('end');
706+
707+
assert.strictEqual(sink.logs.length, 0);
708+
});
709+
710+
it('emits a DEBUG log with response.payload when err.metadata is present and omits it when absent', async () => {
711+
const errWithMeta = Object.assign(new GoogleError('Unavailable'), {
712+
code: Status.UNAVAILABLE,
713+
metadata: {'x-goog-request-id': 'req-123'},
714+
});
715+
716+
await assert.rejects(
717+
async () => {
718+
await logNetworkAttempt(dynamicArgs, staticArgs, async () => {
719+
throw errWithMeta;
720+
});
721+
},
722+
(caught: unknown) => caught === errWithMeta,
723+
);
724+
725+
assert.strictEqual(sink.logs.length, 1);
726+
const entry = sink.logs[0];
727+
assert.strictEqual(entry.namespace, 'storage');
728+
assert.strictEqual(entry.fields.severity, 'DEBUG');
729+
assert.deepStrictEqual(entry.args, [
730+
'RPC attempt failed: %s',
731+
'Unavailable',
732+
]);
733+
const other = entry.fields.other as LogPayload;
734+
assert.deepStrictEqual(other, {
735+
'gcp.client.service': 'storage',
736+
'gcp.client.version': '1.2.3',
737+
'gcp.client.repo': DEFAULT_GCP_REPO,
738+
'gcp.client.artifact': '@google-cloud/storage',
739+
'gcp.client.language': 'node',
740+
'rpc.system.name': 'grpc',
741+
'rpc.method': 'google.storage.v2.Storage/GetObject',
742+
'url.domain': 'storage.googleapis.com',
743+
'rpc.response.status_code': 'UNAVAILABLE',
744+
'error.type': 'UNAVAILABLE',
745+
'response.payload': '{"x-goog-request-id":"req-123"}',
746+
});
747+
assert.strictEqual('exception.type' in other, false);
748+
assert.strictEqual('exception.message' in other, false);
749+
assert.strictEqual('exception.stacktrace' in other, false);
750+
751+
sink.reset();
752+
const errWithoutMeta = new TypeError('client error');
753+
assert.throws(
754+
() =>
755+
logNetworkAttempt(dynamicArgs, staticArgs, () => {
756+
throw errWithoutMeta;
757+
}),
758+
errWithoutMeta,
759+
);
760+
761+
assert.strictEqual(sink.logs.length, 1);
762+
assert.strictEqual(sink.logs[0].fields.severity, 'DEBUG');
763+
assert.deepStrictEqual(sink.logs[0].args, [
764+
'RPC attempt failed: %s',
765+
'client error',
766+
]);
767+
const otherWithoutMeta = sink.logs[0].fields.other as LogPayload;
768+
assert.strictEqual('response.payload' in otherWithoutMeta, false);
769+
assert.strictEqual('exception.type' in otherWithoutMeta, false);
770+
assert.strictEqual('exception.message' in otherWithoutMeta, false);
771+
assert.strictEqual('exception.stacktrace' in otherWithoutMeta, false);
772+
});
773+
774+
it('captures the attempt span context and logs on callback and stream failures', () => {
775+
const stream = new EventEmitter();
776+
let receivedCallback: APICallback | undefined;
777+
778+
traceCall(dynamicArgs, staticArgs, () =>
779+
traceAttempt(dynamicArgs, staticArgs, () =>
780+
logNetworkAttempt(
781+
dynamicArgs,
782+
staticArgs,
783+
loggedCallback => {
784+
receivedCallback = loggedCallback;
785+
return stream;
786+
},
787+
true,
788+
() => {},
789+
),
790+
),
791+
);
792+
793+
const attemptErr = new GoogleError('attempt failed');
794+
receivedCallback!(attemptErr);
795+
stream.emit('error', attemptErr);
796+
797+
const spans = harness.getSpans('google-gax');
798+
assert.strictEqual(spans.length, 2);
799+
const attemptSpan = spans[0];
800+
801+
assert.strictEqual(sink.logs.length, 2);
802+
for (const logEntry of sink.logs) {
803+
assert.strictEqual(logEntry.fields.severity, 'DEBUG');
804+
assert.strictEqual(
805+
logEntry.fields.telemetryTraceId,
806+
attemptSpan.spanContext().traceId,
807+
);
808+
assert.strictEqual(
809+
logEntry.fields.telemetrySpanId,
810+
attemptSpan.spanContext().spanId,
811+
);
812+
assert.deepStrictEqual(logEntry.args, [
813+
'RPC attempt failed: %s',
814+
'attempt failed',
815+
]);
816+
}
817+
});
818+
});
674819
});

0 commit comments

Comments
 (0)