/**
 * 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 { Context, Tracer } from '@opentelemetry/api';
import { APICallback, GaxCallResult } from '../apitypes';
import { AttemptTraceContext, DynamicTraceContext, StaticTraceContext } from './contextUtil';
/**
 * Updates the `http.request.method` attribute, optional `url.template` attribute,
 * and span name on the currently active low level network attempt span, and
 * propagates `url.template` to the active client request span if this is the first
 * attempt span to resolve a URL template.
 *
 * @param {string} httpMethod - The HTTP request method (e.g. 'GET', 'POST').
 * @param {string} [urlTemplate] - Optional URL path template (e.g. '/v1/{name}:access').
 */
export declare function setAttemptHttpMethod(httpMethod: string, urlTemplate?: string): void;
/**
 * 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, ending the span on
 * resolution or recording the error and ending the span on rejection.
 *
 * @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.
 * For client-streaming calls without a callback, `'finish'` is used as the completion
 * signal because readable events (`'end'`) never fire on write-only streams.
 *
 * @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 client request span
 * (`"{clientName}.{methodName}"`), populating standard GCP client telemetry attributes
 * (`gcp.client.*`, `rpc.system.name`, `url.domain`, `server.address`, `server.port`,
 * `rpc.response.status_code` / `http.response.status_code`) and recording error
 * attributes (`error.type`, `status.message`, and `exception.type` event attribute)
 * if the operation fails. Child low level network attempt spans also propagate `rpc.method` and
 * `url.template` onto this span.
 *
 * 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`.
 * @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) => GaxCallResult, isStreamCall?: boolean, callback?: APICallback): GaxCallResult;
export declare function traceCall<T extends EventEmitter>(dynamicArgs: DynamicTraceContext, staticArgs: StaticTraceContext, fn: (tracedCallback?: APICallback) => T, isStreamCall: true, callback?: APICallback): T;
export declare function traceCall<T>(dynamicArgs: DynamicTraceContext, staticArgs: StaticTraceContext, fn: (tracedCallback?: APICallback) => T, isStreamCall?: false, callback?: APICallback): T;
/**
 * Executes an individual RPC transport attempt within an active OpenTelemetry
 * CLIENT span (low level network span), parenting it to the active client request span
 * and recording per-attempt client (`gcp.client.*`), network (`rpc.system.name`, `rpc.method`,
 * `http.request.method`, `url.template`, `url.domain`, `server.address`, `server.port`),
 * resend (`gcp.grpc.resend_count` / `http.request.resend_count`), status
 * (`rpc.response.status_code` / `http.response.status_code`), and error (`error.type`,
 * `status.message`, and `exception.type` / `exception.message` event attributes) attributes
 * without injecting span context into outgoing headers.
 *
 * HTTP attempt spans are named `"{http.request.method} {url.template}"` when a URL
 * template is available or `"{http.request.method}"` otherwise; gRPC attempt spans
 * are named `"{apiName}/{methodName}"` or `"{methodName}"`. Also updates `rpc.method`
 * on the parent client request span to `"{apiName}/{methodName}"` for both transports,
 * and propagates `url.template` to the parent client request span from its first HTTP
 * attempt that resolves a URL template.
 *
 * @template T
 * @param {AttemptTraceContext} dynamicArgs - Dynamic trace context for the RPC attempt.
 * @param {StaticTraceContext} staticArgs - Static trace context for the client library.
 * @param {function} fn - The transport attempt operation to trace.
 * @param {boolean} [isStreamCall=false] - Whether the operation is a stream call.
 * @param {APICallback} [callback] - The attempt callback.
 * @param {Context} [parentContext] - Optional parent OpenTelemetry context (e.g. client request span context).
 * @returns {T} The result of the traced attempt.
 */
export declare function traceAttempt<T = GaxCallResult>(dynamicArgs: AttemptTraceContext, staticArgs: StaticTraceContext, fn: (tracedCallback?: APICallback) => T, isStreamCall?: boolean, callback?: APICallback, parentContext?: Context): T;