@microsoft/applicationinsights-core-js 3.4.0-nightlybeta3.2505-35 → 3.4.0-nightlybeta3.2507-23

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

@@ -1,5 +1,5 @@
 /*
- * Microsoft Application Insights Core Javascript SDK, 3.4.0-nightlybeta3.2505-35
+ * Microsoft Application Insights Core Javascript SDK, 3.4.0-nightlybeta3.2507-23
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -205,12 +205,21 @@ declare namespace ApplicationInsights {
          * @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;
         /**
@@ -555,9 +564,12 @@ declare namespace ApplicationInsights {
          */
         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.
@@ -736,7 +748,7 @@ declare namespace ApplicationInsights {
      * @param defaultValue - The default value to apply it not provided or it's not valid
      * @returns a new IConfigDefaultCheck structure
      */
-    function cfgDfMerge<V, T = IConfiguration, C = IConfiguration>(defaultValue: V | IConfigDefaults<V, T>): IConfigDefaultCheck<T, V, C>;
+    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
@@ -782,6 +794,37 @@ declare namespace ApplicationInsights {
 
     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
+     */
+    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
@@ -843,6 +886,19 @@ declare namespace ApplicationInsights {
         [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
+     */
+    function createW3cTraceState(value?: string | null, parent?: IW3cTraceState | null): IW3cTraceState;
+
     /**
      * Return the number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC.
      *
@@ -1219,6 +1275,30 @@ declare namespace ApplicationInsights {
 
     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
+     */
+    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
@@ -1253,6 +1333,21 @@ declare namespace ApplicationInsights {
 
     type EventsDiscardedReason = number | eEventsDiscardedReason;
 
+    /**
+     * The TelemetryUpdateReason enumeration contains a set of bit-wise values that specify the reason for update request.
+     */
+    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
+    }
+
     const enum FeatureOptInMode {
         /**
          * not set, completely depends on cdn cfg
@@ -1268,6 +1363,14 @@ declare namespace ApplicationInsights {
         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.
+     */
+    function fieldRedaction(input: string, config: IConfiguration): string;
+
     /**
      * This defines the handler function that is called via the finally when the promise is resolved or rejected
      */
@@ -1299,6 +1402,14 @@ declare namespace ApplicationInsights {
      */
     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
+     */
+    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
@@ -1689,7 +1800,7 @@ declare namespace ApplicationInsights {
          */
         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;
@@ -1757,9 +1868,12 @@ declare namespace ApplicationInsights {
          */
         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
@@ -2063,7 +2177,7 @@ declare namespace ApplicationInsights {
          * }
          * ```
          *
-         * 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[];
         /**
@@ -2078,7 +2192,7 @@ declare namespace ApplicationInsights {
          * }
          * ```
          *
-         * 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[];
         /**
@@ -2120,6 +2234,25 @@ declare namespace ApplicationInsights {
          * @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;
     }
 
     interface ICookieMgr {
@@ -2310,8 +2443,13 @@ declare namespace ApplicationInsights {
          */
         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;
         /**
@@ -2324,6 +2462,12 @@ declare namespace ApplicationInsights {
          * 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;
         /**
@@ -2335,6 +2479,12 @@ declare namespace ApplicationInsights {
          * 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;
         /**
@@ -2343,9 +2493,80 @@ declare namespace ApplicationInsights {
         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;
     }
 
     /**
@@ -2884,6 +3105,115 @@ declare namespace ApplicationInsights {
 
     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}.
+     */
+    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.
+     */
+    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 */
     interface IPayloadData {
         urlString: string;
@@ -3733,6 +4063,13 @@ declare namespace ApplicationInsights {
      */
     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
+     */
+    function isW3cTraceState(value: any): value is IW3cTraceState;
+
     /**
      * Checks if XMLHttpRequest is supported
      * @returns True if supported, otherwise false
@@ -3803,9 +4140,10 @@ declare namespace ApplicationInsights {
      */
     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;
         /**
@@ -4085,6 +4423,76 @@ declare namespace ApplicationInsights {
         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
+     */
+    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;
+    }
+
     interface IWatchDetails<T = IConfiguration> {
         /**
          * The current config object
@@ -4873,6 +5281,18 @@ declare namespace ApplicationInsights {
      */
     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
+     */
+    function snapshotW3cTraceState(traceState: IW3cTraceState): IW3cTraceState;
+
     function sortPlugins<T = IPlugin>(plugins: T[]): T[];
 
     /**