/** * Copyright 2026 Google LLC * * 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. */ import * as loggingUtils from 'google-logging-utils'; import { APICallback, GaxCallResult } from '../apitypes'; import { AttemptTraceContext, StaticTraceContext } from './contextUtil'; export interface LogPayload { 'rpc.system.name'?: 'grpc' | 'http'; 'rpc.method'?: string; 'rpc.response.status_code'?: string; 'http.response.status_code'?: number; 'error.type'?: string; 'gcp.errors.domain'?: string; [key: `gcp.errors.metadata.${string}`]: string | undefined; 'gcp.client.repo'?: string; 'gcp.client.artifact'?: string; 'gcp.client.version'?: string; 'gcp.client.language'?: 'node'; 'gcp.client.service'?: string; 'url.domain'?: string; 'server.address'?: string; 'response.payload'?: string; 'exception.type'?: string; 'exception.message'?: string; 'exception.stacktrace'?: string; } /** * Returns the `google-logging-utils` logger for the given GCP client service, * defaulting to the `'google-gax'` namespace when no service name is provided. * * Ensures telemetry logs are still delivered to `NodeBackend` when logging was * enabled via `{enableTelemetryLogging: true}` without `GOOGLE_SDK_NODE_LOGGING` * matching the namespace, while preserving any custom backend installed via * `loggingUtils.setBackend()`. * * @param {string} [serviceName] - The GCP client service name (e.g. 'storage'). * @returns {loggingUtils.AdhocDebugLogFunction} The logger function. */ export declare function getGaxLogger(serviceName?: string): loggingUtils.AdhocDebugLogFunction; /** * Builds the structured `LogPayload` attributes for a failed RPC call or attempt. * * @param {unknown} err - The error thrown or reported for the call. * @param {AttemptTraceContext} dynamicArgs - Dynamic context for the RPC call or attempt. * @param {StaticTraceContext} [staticArgs={}] - Static context for the client library. * @param {boolean} [includeExceptionAttributes=true] - Whether to populate `exception.*` * attributes (set on L3 client call logs, omitted on L4 transport attempt logs). * @returns {LogPayload} The populated log payload attributes with undefined fields omitted. */ export declare function buildLogAttributes(err: unknown, dynamicArgs: AttemptTraceContext, staticArgs?: StaticTraceContext, includeExceptionAttributes?: boolean): LogPayload; /** * Executes an API call and emits a single `WARNING` log entry if the logical * request fails across promise, callback, stream, or synchronous execution boundaries. * * @template T * @param {AttemptTraceContext} dynamicArgs - Dynamic context for the RPC call. * @param {StaticTraceContext} staticArgs - Static context for the client library. * @param {function} fn - The operation to execute. Receives the wrapped callback * when `userCallback` is supplied, otherwise `undefined`. * @param {boolean} [isStreamCall=false] - Whether the operation returns a stream (`EventEmitter`). * @param {APICallback} [userCallback] - Optional user callback for callback-style invocations. * @returns {T} The return value of `fn`. */ export declare function logCall(dynamicArgs: AttemptTraceContext, staticArgs: StaticTraceContext, fn: (loggedCallback?: APICallback) => T, isStreamCall?: boolean, userCallback?: APICallback): T; /** * Executes an individual RPC transport attempt and emits a `DEBUG` log entry * if the attempt fails across promise, callback, stream, or synchronous execution boundaries. * * @template T * @param {AttemptTraceContext} attemptDynamicArgs - Dynamic context for the RPC attempt. * @param {StaticTraceContext} staticArgs - Static context for the client library. * @param {function} fn - The transport attempt operation to execute. Receives the wrapped * callback when `userCallback` is supplied, otherwise `undefined`. * @param {boolean} [isStreamCall=false] - Whether the operation returns a stream (`EventEmitter`). * @param {APICallback} [userCallback] - Optional attempt callback. * @returns {T} The return value of `fn`. */ export declare function logNetworkAttempt(attemptDynamicArgs: AttemptTraceContext, staticArgs: StaticTraceContext, fn: (loggedCallback?: APICallback) => T, isStreamCall?: boolean, userCallback?: APICallback): T;