/**
 * 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 { EventEmitter } from 'events';
import { Tracer } from '@opentelemetry/api';
import { APICallback, GaxCallResult } from '../apitypes';
/**
 * Static metadata about the Google Cloud client library used to populate
 * telemetry span attributes.
 */
export interface StaticTraceContext {
    /**
     * The target GCP service endpoint or domain (e.g. 'storage.googleapis.com').
     */
    gcpClientService?: string;
    /**
     * The version of the client library (e.g. '1.2.3').
     */
    gcpVersion?: string;
    /**
     * The GitHub repository name hosting the client library (e.g. 'googleapis/google-cloud-node').
     */
    gcpRepo?: string;
    /**
     * The NPM package name of the client library (e.g. '@google-cloud/storage').
     */
    gcpArtifact?: string;
    /**
     * Server domain name or IP address for the RPC call.
     */
    serverAddress?: string;
    /**
     * Server port number for the RPC call.
     */
    serverPort?: number;
}
/**
 * Dynamic metadata specific to the individual RPC invocation used to populate
 * telemetry span attributes.
 */
export interface DynamicTraceContext {
    /**
     * The name of the client class making the call (e.g. 'StorageClient').
     */
    clientName: string;
    /**
     * The name of the API method or RPC being invoked (e.g. 'GetObject').
     */
    methodName: string;
    /**
     * The transport protocol used for the RPC ('grpc' or 'http').
     */
    rpcType: 'grpc' | 'http';
    /**
     * Server domain name or IP address for the RPC call.
     */
    serverAddress?: string;
    /**
     * Server port number for the RPC call.
     */
    serverPort?: number;
}
/**
 * Reports that the request was sent again after a retryable failure.
 *
 * Handed to the traced operation, which calls it once per resend. gax retries
 * in more than one place — the unary retry loop and the server-streaming one —
 * and counting the calls rather than reading a counter keeps the tracer
 * independent of how each of them tracks its own attempts.
 */
export type ResendRecorder = () => void;
/**
 * Returns the OpenTelemetry Tracer instance for google-gax.
 *
 * @returns {Tracer} The OpenTelemetry Tracer.
 */
export declare function getGaxTracer(): Tracer;
/**
 * Resolves google.rpc.ErrorInfo reason if present on the error or its cause chain.
 * Corresponds to Tier 1 in the error.type hierarchy.
 */
export declare function resolveErrorInfoReason(e: unknown): string | undefined;
/**
 * Resolves a server error code received from the backend service:
 * - For HTTP: The HTTP status code string (e.g. '400', '403', '503').
 * - For gRPC: The canonical gRPC status code name in uppercase (e.g. 'PERMISSION_DENIED', 'UNAVAILABLE').
 * Corresponds to Tier 2 in the error.type hierarchy.
 */
export declare function resolveServerErrorCode(e: unknown, rpcType: 'grpc' | 'http'): string | undefined;
/**
 * Resolves client-side network and operational errors to standard CLIENT_* identifiers.
 * Corresponds to Tier 3 in the error.type hierarchy.
 */
export declare function resolveClientNetworkOrOperationalError(e: unknown): string | undefined;
/**
 * Resolves a language-specific error type name (e.g. AbortError, TypeError, RangeError, CustomRpcError).
 * Generic wrapper types (Error, GoogleError, Object, DOMException) are excluded and unwrap e.cause.
 * Corresponds to Tier 4 in the error.type hierarchy.
 */
export declare function resolveLanguageSpecificErrorType(e: unknown): string | undefined;
/**
 * Resolves the OpenTelemetry `error.type` attribute according to the 5-tier hierarchy:
 * 1. google.rpc.ErrorInfo.reason
 * 2. Specific Server Error Code (HTTP status code or gRPC status name)
 * 3. Client-Side Network/Operational Errors (CLIENT_* standardized strings)
 * 4. Language-specific error type (e.g. AbortError, RangeError, TypeError, CustomRpcError)
 * 5. Internal Fallback ("INTERNAL")
 */
export declare function resolveErrorType(e: unknown, rpcType: 'grpc' | 'http'): string;
/**
 * Determines if a failure occurred on the client side before DNS resolution
 * or connection establishment.
 */
export declare function isPreConnectionFailure(e: unknown): boolean;
/**
 * Determines whether a failure is a server-side error (i.e. a server response arrived).
 */
export declare function isServerSideError(e: unknown, rpcType: 'grpc' | 'http'): boolean;
/**
 * Safely converts a value to a JSON string without throwing exceptions on
 * circular references, BigInt values, or non-serializable properties.
 */
export declare function safeJsonStringify(value: unknown): string | undefined;
/**
 * Extracts and formats status details and metadata attached by GFE/backend on server-side errors,
 * returning the server error message and a formatted stacktrace string.
 */
export declare function resolveServerExceptionDetails(e: Error): {
    message: string;
    stacktrace?: string;
};
/**
 * Manages span lifecycle for Promise-based operations.
 *
 * @template T
 * @param {T} promise - The promise returned from the traced operation.
 * @param {function} recordError - Callback to record errors on the span.
 * @param {function} endSpan - Callback to end the span idempotently.
 */
export declare function handlePromise<T>(promise: T, recordError: (err: unknown) => void, endSpan: () => void): void;
/**
 * Manages span lifecycle for Stream-based operations and cleans up event listeners.
 *
 * @param {EventEmitter} stream - The stream returned from the traced operation.
 * @param {function} recordError - Callback to record errors on the span.
 * @param {function} endSpan - Callback to end the span idempotently.
 * @param {boolean} [hasCallback=false] - Whether the caller supplied a callback
 *   for this call. When true, 'finish' is not treated as a completion signal.
 */
export declare function handleStream(stream: EventEmitter, recordError: (err: unknown) => void, endSpan: () => void, hasCallback?: boolean): void;
/**
 * Executes a function within an active OpenTelemetry span, populating standard
 * GCP telemetry attributes and recording errors/exceptions if thrown.
 *
 * For callback-style invocations, pass the user's `callback` as the fifth
 * argument so the span stays open until the callback or stream events finish.
 *
 * @template T
 * @param {DynamicTraceContext} dynamicArgs - Dynamic trace context for the RPC call.
 * @param {StaticTraceContext} staticArgs - Static trace context for the client library.
 * @param {function} fn - The operation to trace. Receives the traced callback
 *   when `callback` is supplied, otherwise `undefined`, and a
 *   {@link ResendRecorder} to call once for every retryable resend it makes.
 * @param {boolean} [isStreamCall=false] - Whether the operation is a stream call (true) or promise call (false).
 * @param {APICallback} [callback] - The user callback for callback-style invocations.
 * @returns {T} The result of the traced operation.
 */
export declare function traceCall(dynamicArgs: DynamicTraceContext, staticArgs: StaticTraceContext, fn: (tracedCallback?: APICallback, recordResend?: ResendRecorder) => GaxCallResult, isStreamCall?: boolean, callback?: APICallback): GaxCallResult;
export declare function traceCall<T extends EventEmitter>(dynamicArgs: DynamicTraceContext, staticArgs: StaticTraceContext, fn: (tracedCallback?: APICallback, recordResend?: ResendRecorder) => T, isStreamCall: true, callback?: APICallback): T;
export declare function traceCall<T>(dynamicArgs: DynamicTraceContext, staticArgs: StaticTraceContext, fn: (tracedCallback?: APICallback, recordResend?: ResendRecorder) => T, isStreamCall?: false, callback?: APICallback): T;