/**
 * 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 { Attributes, Context, Span } from '@opentelemetry/api';
import { CallSettings } from '../gax';
export declare const DEFAULT_GCP_REPO = "googleapis/google-cloud-node";
export declare const CLIENT_REQUEST_SPAN_KEY: symbol;
export declare const ATTEMPT_SPAN_KEY: symbol;
/**
 * Active OpenTelemetry trace/span identifiers and span references for the current context.
 */
export interface ActiveTraceContext {
    traceId: string;
    spanId: string;
    span: Span;
    attemptSpan?: Span;
    clientRequestSpan?: Span;
}
/**
 * Static metadata about the Google Cloud client library used to populate
 * telemetry span attributes (`gcp.client.*`, `server.*`, `url.domain`).
 */
export interface StaticTraceContext {
    /**
     * The target GCP service endpoint or domain (e.g. 'storage.googleapis.com').
     * Populates `gcp.client.service`.
     */
    gcpClientService?: string;
    /**
     * The version of the client library (e.g. '1.2.3').
     * Populates `gcp.client.version`.
     */
    gcpVersion?: string;
    /**
     * The GitHub repository name hosting the client library (e.g. 'googleapis/google-cloud-node').
     * Populates `gcp.client.repo`.
     */
    gcpRepo?: string;
    /**
     * The NPM package name of the client library (e.g. '@google-cloud/storage').
     * Populates `gcp.client.artifact`.
     */
    gcpArtifact?: string;
    /**
     * Server domain name or IP address for the RPC call.
     * Populates `server.address`.
     */
    serverAddress?: string;
    /**
     * Server port number for the RPC call.
     * Populates `server.port`.
     */
    serverPort?: number;
    /**
     * Target service domain (e.g. 'cloudkms.googleapis.com').
     * Populates `url.domain`.
     */
    urlDomain?: string;
}
/**
 * Dynamic metadata specific to the individual RPC invocation used to populate
 * telemetry span names and 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').
     * Populates `rpc.system.name`.
     */
    rpcType: 'grpc' | 'http';
    /**
     * Server domain name or IP address for the RPC call.
     * Populates `server.address`.
     */
    serverAddress?: string;
    /**
     * Server port number for the RPC call.
     * Populates `server.port`.
     */
    serverPort?: number;
    /**
     * Target service domain (e.g. 'cloudkms.googleapis.com').
     * Populates `url.domain`.
     */
    urlDomain?: string;
}
/**
 * Dynamic metadata specific to an individual RPC transport attempt (low level network span).
 */
export interface AttemptTraceContext extends DynamicTraceContext {
    /**
     * The fully-qualified protobuf service name (e.g. 'google.cloud.kms.v1.KeyManagementService').
     * Combined with `methodName` to populate `rpc.method`.
     */
    apiName?: string;
    /**
     * The ordinal resend count for this attempt (0 for the initial attempt, 1 for the first retry, etc.).
     * Populates `gcp.grpc.resend_count` (gRPC) or `http.request.resend_count` (HTTP) when > 0;
     * omitted from span attributes when 0 or undefined.
     */
    resendCount?: number;
    /**
     * The HTTP request method for REST fallback attempts (e.g. 'GET', 'POST', 'PUT', 'PATCH', 'DELETE').
     * Populates `http.request.method`.
     */
    httpMethod?: string;
    /**
     * The URL path template for REST fallback attempts (e.g. '/v1/{name}:access').
     * Populates `url.template`.
     */
    urlTemplate?: string;
}
/**
 * Derives the GCP client service name from an NPM package name.
 * @deprecated Retained for backwards compatibility.
 */
export declare function extractClientServiceFromPackageName(name: string): string;
/**
 * Derives the GCP service name from a protobuf apiName (e.g. google.cloud.redis.v1.CloudRedis).
 */
export declare function extractServiceFromApiName(apiName: string): string | undefined;
/**
 * Extracts static metadata from CallSettings headers or apiName.
 */
export declare function extractFromSettings(settings?: CallSettings): StaticTraceContext;
/**
 * Extracts static metadata from process environment variables.
 */
export declare function extractFromEnvironment(): StaticTraceContext;
/**
 * Clears the cached static metadata.
 * @deprecated Static metadata is no longer cached across calls; retained as a no-op for backwards compatibility.
 */
export declare function clearMetadataCache(): void;
/**
 * Resolves static trace context dynamically at runtime by inspecting CallSettings,
 * environment variables, and standard defaults.
 *
 * Precedence: environment variables > dynamic resolution from settings.
 *
 * @param {CallSettings} [settings] - Call settings for the RPC invocation.
 * @param {string} [_callerFilePath] - Optional explicit path to the caller source file (deprecated).
 * @returns {StaticTraceContext} The resolved static trace context.
 */
export declare function resolveStaticTraceContext(settings?: CallSettings, _callerFilePath?: string): StaticTraceContext;
/**
 * Builds the common initial client, transport, and domain attributes shared by
 * client request spans and low level network attempt spans.
 *
 * @param {DynamicTraceContext} dynamicArgs - Dynamic trace context for the call or attempt.
 * @param {StaticTraceContext} staticArgs - Static trace context for the client library.
 * @param {string} [urlDomain] - Resolved `url.domain` attribute value, if available.
 * @returns {Attributes} The initial span attributes map.
 */
export declare function buildInitialAttributes(dynamicArgs: DynamicTraceContext, staticArgs: StaticTraceContext, urlDomain?: string): Attributes;
/**
 * Returns the active trace and span IDs (`traceId` and `spanId`) along with
 * the active span references (`span`, `attemptSpan`, `clientRequestSpan`) if a
 * GAX attempt span, GAX client request span, or outer OpenTelemetry span is
 * active and has a valid span context, or `undefined` otherwise.
 *
 * @param {Context} [activeContext=context.active()] - The OpenTelemetry context to inspect.
 * @returns {ActiveTraceContext | undefined} The active trace context, or undefined.
 */
export declare function getActiveTraceContext(activeContext?: Context): ActiveTraceContext | undefined;