@microsoft/applicationinsights-core-js 3.4.0-nightlybeta3.2505-36 → 3.4.0-nightlybeta3.2507-22

package/types/applicationinsights-core-js.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft Application Insights Core Javascript SDK, 3.4.0-nightlybeta3.2505-36
+ * Microsoft Application Insights Core Javascript SDK, 3.4.0-nightlybeta3.2507-22
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -263,12 +263,21 @@ export declare class AppInsightsCore<CfgType extends IConfiguration = IConfigura
      * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
      * If the caller doesn't return true the caller should assume that it may never be called.
      * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
-     * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
+     * @returns true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
      */
     flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): void;
     /**
-     * Gets the current distributed trace context for this instance if available
-     * @param createNew - Optional flag to create a new instance if one doesn't currently exist, defaults to true
+     * Gets the current distributed trace context for this instance if available, you can optional
+     * create a new instance if one does not currently exist or return null if one does not currently exist.
+     * When a server context is available it will be used as the parent context for the any new instance created
+     * (when createNew is true or no instance currently exists), calling this function will not
+     * change the current distributed trace context, it will only return the current context
+     * or create a new instance if one does not currently exist.
+     * @param createNew - Optional flag to create a new instance if one doesn't currently exist, defaults to
+     * undefined which will only create a new instance if one does not currently exist.
+     * If set to `false` then it will return null if no distributed trace context is available.
+     * If set to `true` then a new instance will be created even if one already exists.
+     * @param createNew - Optional flag to create a new instance if one doesn't currently exist, defaults to
      */
     getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
     /**
@@ -356,9 +365,12 @@ export declare abstract class BaseTelemetryPlugin implements ITelemetryPlugin {
      */
     processNext: (env: ITelemetryItem, itemCtx: IProcessTelemetryContext) => void;
     /**
-     * Set next extension for telemetry processing
+     * Set next extension for telemetry processing, this is now optional as plugins should use the
+     * processNext() function of the passed IProcessTelemetryContext instead. It is being kept for
+     * now for backward compatibility only.
+     * @deprecated - Use processNext() function of the passed IProcessTelemetryContext instead
      */
-    setNextPlugin: (next: ITelemetryPlugin | ITelemetryPluginChain) => void;
+    setNextPlugin?: (next: ITelemetryPlugin | ITelemetryPluginChain) => void;
     /**
      * Returns the current diagnostic logger that can be used to log issues, if no logger is currently
      * assigned a new default one will be created and returned.
@@ -537,7 +549,7 @@ export declare function cfgDfFunc<V, T, C = IConfiguration>(defaultValue?: V): I
  * @param defaultValue - The default value to apply it not provided or it's not valid
  * @returns a new IConfigDefaultCheck structure
  */
-export declare function cfgDfMerge<V, T = IConfiguration, C = IConfiguration>(defaultValue: V | IConfigDefaults<V, T>): IConfigDefaultCheck<T, V, C>;
+export declare function cfgDfMerge<V, T = IConfiguration, C = IConfiguration>(defaultValue: (V | undefined) | IConfigDefaults<V | undefined, T>): IConfigDefaultCheck<T, V | undefined, C>;
 
 /**
  * Helper which returns an IConfigDefaultCheck instance with the provided field set function
@@ -583,6 +595,37 @@ export declare function createCookieMgr(rootConfig?: IConfiguration, logger?: ID
 
 export declare function createCustomDomEvent(eventName: string, details?: any): CustomEvent;
 
+/**
+ * Creates an IDistributedTraceContext instance that ensures a valid traceId is always available.
+ * The traceId will be inherited from the parent context if valid, otherwise a new random W3C trace ID is generated.
+ *
+ * @param parent - An optional parent {@link IDistributedTraceContext} or {@link IOTelSpanContext} to inherit
+ * trace context values from. If provided, the traceId and spanId will be copied from the parent if they are valid.
+ * When the parent is an {@link IDistributedTraceContext}, it will be set as the parentCtx property to maintain
+ * hierarchical relationships and enable parent context updates.
+ * When the parent is an {@link IOTelSpanContext}, the parentCtx will be null because OpenTelemetry span contexts
+ * are read-only data sources that don't support the same hierarchical management methods as IDistributedTraceContext.
+ * The core instance will create a wrapped IDistributedTraceContext instance from the IOTelSpanContext data
+ * to enable Application Insights distributed tracing functionality while maintaining OpenTelemetry compatibility.
+ *
+ * @returns A new IDistributedTraceContext instance with the following behavior:
+ * - **traceId**: Always present - either inherited from parent (if valid) or newly generated W3C trace ID
+ * - **spanId**: Inherited from parent if valid, otherwise empty string
+ * - **traceFlags**: Inherited from parent if available, otherwise undefined
+ * - **pageName**: Inherited from parent context or derived from current location, defaults to "_unknown_"
+ * - **traceState**: Lazily created W3C trace state, inheriting from parent if available
+ *
+ * @remarks
+ * This function ensures consistent distributed tracing by guaranteeing that every context has a valid traceId,
+ * which is essential for the refactored W3C trace state implementation. The spanId may be empty until a
+ * specific span is created, which is normal behavior for trace contexts.
+ *
+ * The distinction between IDistributedTraceContext and IOTelSpanContext parents is important:
+ * - IDistributedTraceContext parents enable bidirectional updates and hierarchical management
+ * - IOTelSpanContext parents are used only for initial data extraction and OpenTelemetry compatibility
+ */
+export declare function createDistributedTraceContext(parent?: IDistributedTraceContext | IOTelSpanContext): IDistributedTraceContext;
+
 /**
  * Create or return a dynamic version of the passed config, if it is not already dynamic
  * @param config - The config to be converted into a dynamic config
@@ -644,6 +687,19 @@ export declare const createValueMap: <E, V = E>(values: {
     [key in keyof E]: [E[keyof E], V[keyof V]];
 }) => V;
 
+/**
+ * Creates a new mutable {@link IW3cTraceState} instance, optionally inheriting from the parent trace state
+ * and optionally using the provided encoded string value as the initial trace state.
+ * Calls to {@link IW3cTraceState.set} and {@link IW3cTraceState.del} will modify the current instance
+ * which means that any child instance that is using this instance as a parent will also be indirectly
+ * modified unless the child instance has overridden the value associated with the modified key.
+ * @since 3.4.0
+ * @param value - The string value for the trace state
+ * @param parent - The parent trace state to inherit any existing keys from.
+ * @returns - A new distributed trace state instance
+ */
+export declare function createW3cTraceState(value?: string | null, parent?: IW3cTraceState | null): IW3cTraceState;
+
 export { dateNow }
 
 export { deepFreeze }
@@ -929,6 +985,30 @@ export declare const enum eLoggingSeverity {
 
 export declare type EnumValue<E = any> = EnumCls<E>;
 
+/**
+ * Controls how the SDK should look for trace headers (traceparent/tracestate) from the initial page load
+ * The values are bitwise OR'd together to allow for multiple values to be set at once.
+ * @since 3.4.0
+ */
+declare const enum eTraceHeadersMode {
+    /**
+     * Don't look for any trace headers
+     */
+    None = 0,
+    /**
+     * Look for traceparent header/meta tag
+     */
+    TraceParent = 1,
+    /**
+     * Look for tracestate header/meta tag
+     */
+    TraceState = 2,
+    /**
+     * Look for both traceparent and tracestate headers/meta tags
+     */
+    All = 3
+}
+
 /**
  * Removes an event handler for the specified event
  * @param Object - to remove the event from
@@ -963,6 +1043,21 @@ export declare const EventsDiscardedReason: EnumValue<typeof eEventsDiscardedRea
 
 export declare type EventsDiscardedReason = number | eEventsDiscardedReason;
 
+/**
+ * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+ */
+export declare const enum eW3CTraceFlags {
+    /**
+     * No sampling decision has been made.
+     */
+    None = 0,
+    /**
+     * Represents that the trace has been sampled.
+     * @remarks This value is used to indicate that the trace has been sampled.
+     */
+    Sampled = 1
+}
+
 export declare const enum FeatureOptInMode {
     /**
      * not set, completely depends on cdn cfg
@@ -978,6 +1073,14 @@ export declare const enum FeatureOptInMode {
     enable = 3
 }
 
+/**
+ * Redacts sensitive information from a URL string, including credentials and specific query parameters.
+ * @param input - The URL string to be redacted.
+ * @param config - Configuration object that contain redactUrls setting.
+ * @returns The redacted URL string or the original string if no redaction was needed or possible.
+ */
+export declare function fieldRedaction(input: string, config: IConfiguration): string;
+
 /**
  * Find all script tags in the provided document and return the information about them.
  * @param doc - The document to search for script tags
@@ -1004,6 +1107,14 @@ export declare function findNamedServerTiming(name: string): any;
  */
 export declare function findW3cTraceParent(selectIdx?: number): ITraceParent;
 
+/**
+ * Helper function to fetch the passed traceparent from the page, looking for it as a meta-tag or a Server-Timing header.
+ * @since 3.4.0
+ * @param selectIdx - If the found value is comma separated which is the preferred entry to select, defaults to the first
+ * @returns
+ */
+export declare function findW3cTraceState(): IW3cTraceState;
+
 /**
  * This is the reverse case of {@link blockDynamicConversion} in that this will tag an
  * object to indicate that it should always be converted into a dynamic trackable object
@@ -1271,7 +1382,7 @@ export declare interface IAppInsightsCore<CfgType extends IConfiguration = IConf
      */
     flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason, cbTimeout?: number): boolean | void;
     /**
-     * Gets the current distributed trace context for this instance if available
+     * Gets the current distributed trace active context for this instance
      * @param createNew - Optional flag to create a new instance if one doesn't currently exist, defaults to true
      */
     getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
@@ -1339,9 +1450,12 @@ export declare interface IBaseProcessingContext {
      */
     getCfg: () => IConfiguration;
     /**
-     * Gets the named extension config
+     * Gets the named extension configuration
+     * @param identifier - The named extension identifier
+     * @param defaultValue - The default value(s) to return if no defined config exists
+     * @param rootOnly - If true, only the look for the configuration in the top level and not in the "extensionConfig"
      */
-    getExtCfg: <T>(identifier: string, defaultValue?: IConfigDefaults<T>) => T;
+    getExtCfg: <T>(identifier: string, defaultValue?: IConfigDefaults<T>, rootOnly?: boolean) => T;
     /**
      * Gets the named config from either the named identifier extension or core config if neither exist then the
      * default value is returned
@@ -1645,7 +1759,7 @@ export declare interface IConfiguration {
      * }
      * ```
      *
-     * For more details, see the [Page Unload Events documentation](https://microsoft.github.io/ApplicationInsights-JS/docs/PageUnloadEvents.html).
+     * For more details, see the [Page Unload Events documentation](https://microsoft.github.io/ApplicationInsights-JS/PageUnloadEvents.html).
      */
     disablePageUnloadEvents?: string[];
     /**
@@ -1660,7 +1774,7 @@ export declare interface IConfiguration {
      * }
      * ```
      *
-     * For more details, see the [Page Unload Events documentation](https://microsoft.github.io/ApplicationInsights-JS/docs/PageUnloadEvents.html).
+     * For more details, see the [Page Unload Events documentation](https://microsoft.github.io/ApplicationInsights-JS/PageUnloadEvents.html).
      */
     disablePageShowEvents?: string[];
     /**
@@ -1702,6 +1816,25 @@ export declare interface IConfiguration {
      * @since 3.3.2
      */
     expCfg?: IExceptionConfig;
+    /**
+     * [Optional] A flag to enable or disable the use of the field redaction for urls.
+     * @defaultValue true
+     */
+    redactUrls?: boolean;
+    /**
+     * [Optional] Additional query parameters to redact beyond the default set.
+     * Use this to specify custom parameters that contain sensitive information.
+     * These will be combined with the default parameters that are redacted.
+     * @defaultValue ["sig", "Signature", "AWSAccessKeyId", "X-Goog-Signature"]
+     * @example ["sig", "Signature", "AWSAccessKeyId", "X-Goog-Signature","auth_token", "api_key", "private_data"]
+     */
+    redactQueryParams?: string[];
+    /**
+     * [Optional] Controls if the SDK should look for the `traceparent` and/or `tracestate` values from
+     * the service timing headers or meta tags from the initial page load.
+     * @defaultValue eTraceHeadersMode.All
+     */
+    traceHdrMode?: eTraceHeadersMode;
 }
 
 export declare interface ICookieMgr {
@@ -1892,8 +2025,13 @@ export declare interface IDistributedTraceContext {
      */
     getName(): string;
     /**
-     * Sets the current name of the page
+     * Sets the current name of the page, also updates the name for any parent context.
+     * This is used to identify the page in the telemetry data.
+     * @remarks This function updates the current and ALL parent contexts with the new name,
+     * to just update the name of the current context, use the `pageName` property.
      * @param pageName - The name of the page
+     * @deprecated Use the `pageName` property to avoid the side effect of changing the page name of all
+     * parent contexts.
      */
     setName(pageName: string): void;
     /**
@@ -1906,6 +2044,12 @@ export declare interface IDistributedTraceContext {
      * Set the unique identifier for a trace. All requests / spans from the same trace share the same traceId.
      * Must be conform to the W3C TraceContext specification, in a hex representation of 16-byte array.
      * A.k.a. trace-id, TraceID or Distributed TraceID https://www.w3.org/TR/trace-context/#trace-id
+     *
+     * @remarks Sets the traceId for the current context AND all parent contexts, if you want to set the traceId
+     * for the current context only, use the `traceId` property.
+     * @param newValue - The traceId to set
+     * @deprecated Use the `traceId` property to avoid the side effect of changing the traceId of all
+     * parent contexts.
      */
     setTraceId(newValue: string): void;
     /**
@@ -1917,6 +2061,12 @@ export declare interface IDistributedTraceContext {
      * Self-generated 8-bytes identifier of the incoming request. Must be a hex representation of 8-byte array.
      * Also know as the parentId, used to link requests together
      * https://www.w3.org/TR/trace-context/#parent-id
+     *
+     * @remarks Sets the spanId for the current context AND all parent contexts, if you want to set the spanId for
+     * the current context only, use the `spanId` property.
+     * @param newValue - The spanId to set
+     * @deprecated Use the `spanId` property to avoid the side effect of changing the spanId of all
+     * parent contexts.
      */
     setSpanId(newValue: string): void;
     /**
@@ -1925,9 +2075,80 @@ export declare interface IDistributedTraceContext {
     getTraceFlags(): number | undefined;
     /**
      * https://www.w3.org/TR/trace-context/#trace-flags
+     * @remarks Sets the trace flags for the current context and ALL  parent contexts, if you want to set the trace
+     * flags for the current context only, use the `traceFlags` property.
      * @param newValue - An integer representation of the W3C TraceContext trace-flags.
+     * @deprecated Use the `traceFlags` property to avoid the side effect of changing the traceFlags of all
+     * parent contexts.
      */
     setTraceFlags(newValue?: number): void;
+    /**
+     * Returns the current name of the page
+     * @remarks This function updates the current context only, to update the name of the current and ALL parent contexts,
+     * use the `setName` method.
+     * @default undefined
+     * @since 3.4.0
+     */
+    pageName: string;
+    /**
+     * The current ID of the trace that this span belongs to. It is worldwide unique
+     * with practically sufficient probability by being made as 16 randomly
+     * generated bytes, encoded as a 32 lowercase hex characters corresponding to
+     * 128 bits.
+     * @remarks If you update this value, it will only update for the current context, not the parent context,
+     * if you need to update the current and ALL parent contexts, use the `setTraceId` method.
+     * @since 3.4.0
+     */
+    traceId: string;
+    /**
+     * The ID of the Span. It is globally unique with practically sufficient
+     * probability by being made as 8 randomly generated bytes, encoded as a 16
+     * lowercase hex characters corresponding to 64 bits.
+     * If you update this value, it will only update for the current context, not the parent context.
+     * @remarks If you update this value, it will only update for the current context, not the parent context,
+     * if you need to update the current and ALL parent contexts, use the `setSpanId` method.
+     * @since 3.4.0
+     */
+    spanId: string;
+    /**
+     * Returns true if the current context was initialized (propagated) from a remote parent.
+     * @since 3.4.0
+     * @default false
+     * @returns True if the context was propagated from a remote parent
+     */
+    readonly isRemote: boolean;
+    /**
+     * Trace flags to propagate.
+     *
+     * It is represented as 1 byte (bitmap). Bit to represent whether trace is
+     * sampled or not. When set, the least significant bit documents that the
+     * caller may have recorded trace data. A caller who does not record trace
+     * data out-of-band leaves this flag unset.
+     *
+     * see {@link eW3CTraceFlags} for valid flag values.
+     *
+     * @remarks If you update this value, it will only update for the current context, not the parent context,
+     * if you need to update the current and ALL parent contexts, use the `setTraceFlags` method.
+     * @since 3.4.0
+     */
+    traceFlags?: number;
+    /**
+     * Returns the current trace state which will be used to propgate context across different services.
+     * Updating (adding / removing keys) of the trace state will modify the current context.
+     * @remarks Unlike the OpenTelemetry {@link TraceState}, this value is a mutable object, so you can
+     * modify it directly you do not need to reassign the new value to this property.
+     * @since 3.4.0
+     */
+    readonly traceState: IW3cTraceState;
+    /**
+     * Provides access to the parent context of the current context.
+     * @remarks This is a read-only property, you cannot modify the parent context directly, you can only
+     * modify the current context. If you need to modify the parent context, you need to do it through the
+     * current context using the `setTraceId`, `setSpanId`, `setTraceFlags` and `setName` methods.
+     * @default null
+     * @since 3.4.0
+     */
+    readonly parentCtx?: IDistributedTraceContext | null;
 }
 
 /**
@@ -2466,6 +2687,115 @@ export declare class _InternalLogMessage {
 
 export declare type _InternalMessageId = number | _eInternalMessageId;
 
+/**
+ * A SpanContext represents the portion of a {@link IOTelSpan} which must be
+ * serialized and propagated along side of a {@link IOTelBaggage}.
+ */
+export declare interface IOTelSpanContext {
+    /**
+     * The ID of the trace that this span belongs to. It is worldwide unique
+     * with practically sufficient probability by being made as 16 randomly
+     * generated bytes, encoded as a 32 lowercase hex characters corresponding to
+     * 128 bits.
+     */
+    traceId: string;
+    /**
+     * The ID of the Span. It is globally unique with practically sufficient
+     * probability by being made as 8 randomly generated bytes, encoded as a 16
+     * lowercase hex characters corresponding to 64 bits.
+     */
+    spanId: string;
+    /**
+     * Only true if the SpanContext was propagated from a remote parent.
+     */
+    isRemote?: boolean;
+    /**
+     * Trace flags to propagate.
+     *
+     * It is represented as 1 byte (bitmap). Bit to represent whether trace is
+     * sampled or not. When set, the least significant bit documents that the
+     * caller may have recorded trace data. A caller who does not record trace
+     * data out-of-band leaves this flag unset.
+     *
+     * see {@link eW3CTraceFlags} for valid flag values.
+     */
+    traceFlags: number;
+    /**
+     * Tracing-system-specific info to propagate.
+     *
+     * The tracestate field value is a `list` as defined below. The `list` is a
+     * series of `list-members` separated by commas `,`, and a list-member is a
+     * key/value pair separated by an equals sign `=`. Spaces and horizontal tabs
+     * surrounding `list-members` are ignored. There can be a maximum of 32
+     * `list-members` in a `list`.
+     * More Info: https://www.w3.org/TR/trace-context/#tracestate-field
+     *
+     * Examples:
+     *     Single tracing system (generic format):
+     *         tracestate: rojo=00f067aa0ba902b7
+     *     Multiple tracing systems (with different formatting):
+     *         tracestate: rojo=00f067aa0ba902b7,congo=t61rcWkgMzE
+     */
+    traceState?: IOTelTraceState;
+}
+
+/**
+ * Provides an OpenTelemetry compatible Interface for the Open Telemetry Api (1.9.0) TraceState type.
+ *
+ * The TraceState is a list of key/value pairs that are used to propagate
+ * vendor-specific trace information across different distributed tracing systems.
+ * The TraceState is used to store the state of a trace across different
+ * distributed tracing systems, and it is used to ensure that the trace information
+ * is consistent across different systems.
+ *
+ * Instances of TraceState are immutable, and the methods on this interface
+ * return a new instance of TraceState with the updated values.
+ */
+export declare interface IOTelTraceState {
+    /**
+     * Create a new TraceState which inherits from this TraceState and has the
+     * given key set.
+     * The new entry will always be added in the front of the list of states.
+     *
+     * @param key - key of the TraceState entry.
+     * @param value - value of the TraceState entry.
+     */
+    set(key: string, value: string): IOTelTraceState;
+    /**
+     * Return a new TraceState which inherits from this TraceState but does not
+     * contain the given key.
+     *
+     * @param key - the key for the TraceState entry to be removed.
+     */
+    unset(key: string): IOTelTraceState;
+    /**
+     * Returns the value to which the specified key is mapped, or `undefined` if
+     * this map contains no mapping for the key.
+     *
+     * @param key - with which the specified value is to be associated.
+     * @returns the value to which the specified key is mapped, or `undefined` if
+     *     this map contains no mapping for the key.
+     */
+    get(key: string): string | undefined;
+    /**
+     * Serializes the TraceState to a `list` as defined below. The `list` is a series of `list-members`
+     * separated by commas `,`, and a list-member is a key/value pair separated by an equals sign `=`.
+     * Spaces and horizontal tabs surrounding `list-members` are ignored. There can be a maximum of 32
+     * `list-members` in a `list`.
+     *
+     * If the resulting serialization is limited to no longer than 512 bytes, if the combination of
+     * keys and values exceeds this limit, the serialization will be truncated to the last key/value pair
+     * that fits within the limit. The serialization will be returned as a string.
+     *
+     * This is different from the {@link IW3cTraceState} serialization which returns an array of strings where each
+     * string is limited to 512 bytes and the array is limited to 32 strings. Thus the OpenTelemetry serialization
+     * will only return the first single string that fits within the limie.
+     *
+     * @returns the serialized string.
+     */
+    serialize(): string;
+}
+
 /** IPayloadData describes interface of payload sent via POST channel */
 export declare interface IPayloadData {
     urlString: string;
@@ -2921,6 +3251,13 @@ export declare function isValidTraceId(value: string): boolean;
  */
 export declare function isValidTraceParent(value: ITraceParent): boolean;
 
+/**
+ * Identifies if the provided value looks like a distributed trace state instance
+ * @param value - The value to check
+ * @returns - True if the value looks like a distributed trace state instance
+ */
+export declare function isW3cTraceState(value: any): value is IW3cTraceState;
+
 /**
  * Checks if XMLHttpRequest is supported
  * @returns True if supported, otherwise false
@@ -2991,9 +3328,10 @@ export declare interface ITelemetryItem {
  */
 export declare interface ITelemetryPlugin extends ITelemetryProcessor, IPlugin {
     /**
-     * Set next extension for telemetry processing, this is not optional as plugins should use the
+     * Set next extension for telemetry processing, this is now optional as plugins should use the
      * processNext() function of the passed IProcessTelemetryContext instead. It is being kept for
      * now for backward compatibility only.
+     * @deprecated - Use processNext() function of the passed IProcessTelemetryContext instead
      */
     setNextPlugin?: (next: ITelemetryPlugin | ITelemetryPluginChain) => void;
     /**
@@ -3159,6 +3497,76 @@ export declare interface IUnloadHookContainer {
     run: (logger?: IDiagnosticLogger) => void;
 }
 
+/**
+ * Represents a mutable [W3C trace state list](https://www.w3.org/TR/trace-context/#tracestate-header), this is a
+ * list of key/value pairs that are used to pass trace state information between different tracing systems. The
+ * list is ordered and the order is important as it determines the processing order.
+ *
+ * Importantly instances of this type are mutable, change made to an instance via {@link IW3cTraceState.set} or
+ * {@link IW3cTraceState.del} will be reflected on the instance and any child instances that use it as a parent.
+ * However, any parent instance associated with an instance will not be modified by operations on that particular
+ * instance.
+ *
+ * @since 3.4.0
+ */
+export declare interface IW3cTraceState {
+    /**
+     * Returns a readonly array of the current keys associated with the trace state, keys are returned in the
+     * required processing order and if this instance has a parent the keys from the parent will be included
+     * unless they have been removed (deleted) from the child instance.
+     * Once created any modifications to the parent will also be reflected in the child, this is different from
+     * the OpenTelemetry implementation which creates a new instance for each call.
+     * @returns A readonly array of the current keys associated with the trace state
+     */
+    readonly keys: string[];
+    /**
+     * Check if the trace state list is empty, meaning it has no keys or values.
+     * This exists to allow for quick checks without needing to create a new array of keys.
+     * @since 3.4.0
+     * @returns true if the trace state list is empty, false otherwise
+     */
+    readonly isEmpty: boolean;
+    /**
+     * Get the value for the specified key that is associated with this instance, either directly or from the parent.
+     * @param key - The key to lookup
+     * @returns The value for the key, or undefined if not found
+     */
+    get(key: string): string | undefined;
+    /**
+     * Set the value for the specified key for this instance, returning its new location within the list.
+     * - 0 is the front of the list
+     * - -1 not set because the key/value pair is invalid
+     * If the key already exists it will be removed from its current location and added to the front of the list. And
+     * if the key was in the parent this will override the value inherited from the parent, more importantly it will
+     * not modify the parent value.
+     * @param key - The key to set
+     * @param value - The value to set
+     * @returns 0 if successful, -1 if not
+     */
+    set(key: string, value: string): number;
+    /**
+     * Delete the specified key from this instance, if the key was in the parent it will be removed (hidden) from
+     * this instance but will still be available directly from the parent.
+     * @param key - The key to delete
+     */
+    del(key: string): void;
+    /**
+     * Format the trace state list into a strings where each string can be used as a header value.
+     * This will return an empty array if the trace state list is empty.
+     * @param maxHeaders - The maximum number of entries to include in the output, once the limit is reached no more entries will be included
+     * @param maxKeys - The maximum number of keys to include in the output, once the limit is reached no more keys will be included
+     * @param maxLen - The maximum length of each header value, once the limit is reached a new header value will be created
+     * @returns An array of strings that can be used for the header values, if the trace state list is empty an empty array will be returned
+     */
+    hdrs(maxHeaders?: number, maxKeys?: number, maxLen?: number): string[];
+    /**
+     * Create a new instance of IW3cTraceState which is a child of this instance, meaning it will inherit the keys
+     * and values from this instance but any changes made to the child will not affect this instance.
+     * @returns A new instance of IW3cTraceState which is a child of this instance
+     */
+    child(): IW3cTraceState;
+}
+
 export declare interface IWatchDetails<T = IConfiguration> {
     /**
      * The current config object
@@ -3790,6 +4198,18 @@ export declare function setGblPerfMgr(perfManager: IPerfManager): void;
  */
 export declare function setValue<T, K extends keyof T>(target: T, field: K, value: T[K], valChk?: ((value: T[K]) => boolean) | null, srcChk?: ((value: T[K]) => boolean) | null): T[K];
 
+/**
+ * Create a new independent instance of IW3cTraceState that contains a snapshot of all current key/value pairs
+ * from the provided instance and any parent instances. The returned instance will have no parent and will be completely
+ * independent from any future changes to the original instance or its parent chain.
+ * This is useful when you need to capture the current state and ensure it remains unchanged regardless of
+ * future modifications to the parent instances.
+ * @since 3.4.0
+ * @param traceState - The trace state instance to snapshot
+ * @returns A new independent instance of IW3cTraceState with all current key/value pairs captured
+ */
+export declare function snapshotW3cTraceState(traceState: IW3cTraceState): IW3cTraceState;
+
 export declare function sortPlugins<T = IPlugin>(plugins: T[]): T[];
 
 /**