/**
 * 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;
}
/**
 * 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';
}
/**
 * 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;
/**
 * 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;