@microsoft/applicationinsights-debugplugin-js 3.3.12-nightly3.2602-20 → 3.4.0-nightly3.2602-34

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

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 3.3.12-nightly3.2602-20
+ * Microsoft.ApplicationInsights, 3.4.0-nightly3.2602-34
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -134,6 +134,51 @@ declare namespace ApplicationInsights {
         PENDING = 3
     }
 
+    /**
+     * Const enum for attribute change operation types
+     */
+    const enum eAttributeChangeOp {
+        /**
+         * Clear operation - clearing all attributes
+         */
+        Clear = 0,
+        /**
+         * Set operation - setting an attribute value (generic)
+         */
+        Set = 1,
+        /**
+         * Add operation - adding a new attribute that didn't exist before
+         */
+        Add = 2,
+        /**
+         * Delete operation - deleting an attribute
+         */
+        Delete = 3,
+        /**
+         * Dropped attributes - attributes that were dropped due to size limits
+         */
+        DroppedAttributes = 4
+    }
+
+    /**
+     * Identifies the source of an attribute value in iterator operations
+     * @since 3.4.0
+     */
+    const enum eAttributeFilter {
+        /**
+         * The attribute exists local to the current container instance
+         */
+        Local = 0,
+        /**
+         * The attribute does not exist locally and is inherited from a parent container or attributes object
+         */
+        Inherited = 1,
+        /**
+         * The attribute exists or has been deleted locally (only) to the current container instance
+         */
+        LocalOrDeleted = 2
+    }
+
     const enum _eInternalMessageId {
         BrowserDoesNotSupportLocalStorage = 0,
         BrowserCannotReadLocalStorage = 1,
@@ -226,7 +271,12 @@ declare namespace ApplicationInsights {
         SdkLdrUpdate = 111,
         InitPromiseException = 112,
         StatsBeatManagerException = 113,
-        StatsBeatException = 114
+        StatsBeatException = 114,
+        AttributeError = 115,
+        SpanError = 116,
+        TraceError = 117,
+        NotImplementedError = 118,
+        VersionMismatch = 119
     }
 
     const enum eLoggingSeverity {
@@ -264,6 +314,81 @@ declare namespace ApplicationInsights {
 
     type EnumValue<E = any> = EnumCls<E>;
 
+    /**
+     * The defined set of Span Kinds as defined by the OpenTelemetry.
+     */
+    const enum eOTelSpanKind {
+        /** Default value. Indicates that the span is used internally. */
+        INTERNAL = 0,
+        /**
+         * Indicates that the span covers server-side handling of an RPC or other
+         * remote request.
+         */
+        SERVER = 1,
+        /**
+         * Indicates that the span covers the client-side wrapper around an RPC or
+         * other remote request.
+         */
+        CLIENT = 2,
+        /**
+         * Indicates that the span describes producer sending a message to a
+         * broker. Unlike client and server, there is no direct critical path latency
+         * relationship between producer and consumer spans.
+         */
+        PRODUCER = 3,
+        /**
+         * Indicates that the span describes consumer receiving a message from a
+         * broker. Unlike client and server, there is no direct critical path latency
+         * relationship between producer and consumer spans.
+         */
+        CONSUMER = 4
+    }
+
+    /**
+     * An enumeration of status codes, matching the OpenTelemetry specification.
+     *
+     * @since 3.4.0
+     */
+    const enum eOTelSpanStatusCode {
+        /**
+         * The default status.
+         */
+        UNSET = 0,
+        /**
+         * The operation has been validated by an Application developer or
+         * Operator to have completed successfully.
+         */
+        OK = 1,
+        /**
+         * The operation contains an error.
+         */
+        ERROR = 2
+    }
+
+    /**
+     * 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
+    }
+
     const enum FeatureOptInMode {
         /**
          * not set, completely depends on cdn cfg
@@ -284,8 +409,7 @@ declare namespace ApplicationInsights {
      */
     type FinallyPromiseHandler = (() => void) | undefined | null;
 
-    interface IAppInsightsCore<CfgType extends IConfiguration = IConfiguration> extends IPerfManagerProvider {
-        readonly config: CfgType;
+    interface IAppInsightsCore<CfgType extends IConfiguration = IConfiguration> extends IPerfManagerProvider, ITraceHost<CfgType> {
         /**
          * The current logger instance for this instance.
          */
@@ -406,14 +530,13 @@ 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
-         * @param createNew - Optional flag to create a new instance if one doesn't currently exist, defaults to true
-         */
-        getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
-        /**
-         * Sets the current distributed trace context for this instance if available
+         * Set the trace provider for creating spans.
+         * This allows different SKUs to provide their own span implementations.
+         *
+         * @param provider - The trace provider to use for span creation
+         * @since 3.4.0
          */
-        setTraceCtx(newTraceCtx: IDistributedTraceContext | null | undefined): void;
+        setTraceProvider(provider: ICachedValue<ITraceProvider>): void;
         /**
          * Watches and tracks changes for accesses to the current config, and if the accessed config changes the
          * handler will be recalled.
@@ -441,6 +564,150 @@ declare namespace ApplicationInsights {
         _setPendingStatus?: () => void;
     }
 
+    /**
+     * Information about what changed in an attribute container
+     */
+    interface IAttributeChangeInfo<V extends OTelAttributeValue = OTelAttributeValue> {
+        /**
+         * The Id of the container that is initiated the change (not the immediate sender -- which is always the parent)
+         * As children only receive listener notifications from their parent in reaction to both changes
+         * they make and any changes they receive from their parent
+         */
+        frm: string;
+        /**
+         * Operation type that occurred
+         */
+        op: eAttributeChangeOp;
+        /**
+         * The key that was changed (only present for 'set' operations)
+         */
+        k?: string;
+        /**
+         * The old value (only present for 'set' operations when replacing existing value)
+         */
+        prev?: V;
+        /**
+         * The new value (only present for 'set' operations)
+         */
+        val?: V;
+    }
+
+    /**
+     * Interface for an attribute container
+     * @since 3.4.0
+     */
+    interface IAttributeContainer<V extends OTelAttributeValue = OTelAttributeValue> {
+        /**
+         * Unique identifier for the attribute container
+         */
+        readonly id: string;
+        /**
+         * The number of attributes that have been set
+         * @returns The number of attributes that have been set
+         */
+        readonly size: number;
+        /**
+         * The number of attributes that were dropped due to the attribute limit being reached
+         * @returns The number of attributes that were dropped due to the attribute limit being reached
+         */
+        readonly droppedAttributes: number;
+        /**
+         * Return a snapshot of the current attributes, including inherited ones.
+         * This value is read-only and reflects the state of the attributes at the time of access,
+         * and the returned instance will not change if any attributes are modified later, you will need
+         * to access the attributes property again to get the latest state.
+         *
+         * Note: As this causes a snapshot to be taken, it is an expensive operation as it enumerates all
+         * attributes, so you SHOULD use this property sparingly.
+         * @returns A read-only snapshot of the current attributes
+         */
+        readonly attributes: IOTelAttributes;
+        /**
+         * Clear all existing attributes from the container, this will also remove any inherited attributes
+         * from this instance only (it will not change the inherited attributes / container(s))
+         */
+        clear: () => void;
+        /**
+         * Get the value of an attribute by key
+         * @param key - The attribute key to retrieve
+         * @param source - Optional filter to only check attributes from a specific source (Local or Inherited)
+         * @returns The attribute value if found, undefined otherwise
+         */
+        get: (key: string, source?: eAttributeFilter) => V | undefined;
+        /**
+         * Check if an attribute exists by key
+         * @param key - The attribute key to check
+         * @param source - Optional filter to only check attributes from a specific source (Local or Inherited)
+         * @returns True if the attribute exists, false otherwise
+         */
+        has: (key: string, source?: eAttributeFilter) => boolean;
+        /**
+         * Set the value of an attribute by key on this instance.
+         * @param key - The attribute key to set
+         * @param value - The value to assign to the named attribute
+         * @returns true if the value was successfully set / replaced
+         */
+        set: (key: string, value: V) => boolean;
+        /**
+         * Delete an existing attribute, if the key doesn't exist this will return false. If the key does
+         * exist then it will be removed from this instance and any inherited value will be hidden (even if
+         * the inherited value changes)
+         * @param key - The attribute key to delete
+         * @returns True if the attribute was deleted, false if it didn't exist (which includes if it has already been deleted)
+         */
+        del: (key: string) => boolean;
+        /**
+         * The keys() method returns a new iterator object that contains the existing keys for each element
+         * in this attribute container. It will return all locally set keys first and then the inherited keys.
+         * When a key exists in both the local and inherited attributes, only the local key will be returned.
+         * If the key has been deleted locally, it will not be included in the iterator.
+         * @returns An iterator over the keys of the attribute container
+         */
+        keys: () => Iterator<string>;
+        /**
+         * The entries() method of returns a new iterator object that contains the [key, value, source?] tuples for
+         * each attribute, it returns all existing attributes of this instance including all inherited ones. If the
+         * same key exists in both the local and inherited attributes, only the first (non-deleted) tuple will be returned.
+         * If the key has been deleted, it will not be included in the iterator.
+         *
+         * The source value of the tuple identifies the origin of the attribute (Local or Inherited).
+         * @returns An iterator over the entries of the attribute container
+         */
+        entries: () => Iterator<[string, V, eAttributeFilter]>;
+        /**
+         * The forEach() method of executes a provided function once per each key/value pair in this attribute container,
+         * it will process all local attributes first, then the inherited attributes.  If the same key exists in both the
+         * local and inherited attributes, only the first (non-deleted) key/value pair will be processed.
+         * If a key has been deleted, it will not be included in the set of processed key/value pairs.
+         * @param callback - The function to execute for each key/value pair
+         * @param thisArg - Optional value to use as `this` when executing `callback`
+         */
+        forEach: (callback: (key: string, value: V, source?: eAttributeFilter) => void, thisArg?: any) => void;
+        /**
+         * The values() method returns a new iterator instance that contains the values for each element in this
+         * attribute container. It will return all locally set values first and then the inherited values. If the
+         * same key is present in both the local or inherited attributes only the first (non-deleted) value will be
+         * returned. If a key has been deleted, it will not be included in the iterator.
+         * @returns An iterator over the values of the attribute container
+         */
+        values: () => Iterator<V>;
+        /**
+         * Register a callback listener for any attribute changes, this will include local and inherited changes.
+         * @param callback - Function to be called when attributes change, receives change information
+         * @returns IUnloadHook instance with rm() function to remove this listener, once called it will never be invoked again
+         */
+        listen: (callback: (changeInfo: IAttributeChangeInfo<V>) => void) => IUnloadHook;
+        /**
+         * Create a child attribute container that inherits from this one, optionally taking a snapshot
+         * so that any future changes to the parent container do not affect the child container.
+         * The child will use all of the configuration from the parent container.
+         * @param name - Optional name for the child container
+         * @param snapshot - If true, the child container will be a snapshot of the current state
+         * @returns A new attribute container instance
+         */
+        child: (name?: string, snapshot?: boolean) => IAttributeContainer;
+    }
+
     interface IBaseProcessingContext {
         /**
          * The current core instance for the request
@@ -455,9 +722,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
@@ -502,6 +772,30 @@ declare namespace ApplicationInsights {
         createNew: (plugins?: IPlugin[] | ITelemetryPluginChain, startAt?: IPlugin) => IBaseProcessingContext;
     }
 
+    /**
+     * A generic interface for holding a cached value
+     * @since 0.10.5
+     * @group Helpers
+     * @group Cache
+     * @typeParam T - The type of the value to be cached
+     * @example
+     * ```ts
+     * let cachedValue: ICachedValue<string> = {
+     *    v: "some value"
+     * };
+     * ```
+     */
+    interface ICachedValue<T> {
+        /**
+         * Returns the current cached value
+         */
+        v: T;
+        /**
+         * Returns the current cached value
+         */
+        toJSON(): T;
+    }
+
     /**
      * Provides data transmission capabilities
      */
@@ -621,7 +915,7 @@ declare namespace ApplicationInsights {
     /**
      * Configuration provided to SDK core
      */
-    interface IConfiguration {
+    interface IConfiguration extends IOTelConfig {
         /**
          * Instrumentation key of resource. Either this or connectionString must be specified.
          */
@@ -823,6 +1117,12 @@ declare namespace ApplicationInsights {
          * @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 {
@@ -983,7 +1283,7 @@ declare namespace ApplicationInsights {
         /**
          * The internal logging queue
          */
-        queue: _InternalLogMessage[];
+        queue: IInternalLogMessage[];
         /**
          * This method will throw exceptions in debug mode or attempt to log the error as a console warning.
          * @param severity - The severity of the log message
@@ -1016,7 +1316,7 @@ declare namespace ApplicationInsights {
          * @param severity - The severity of the log message
          * @param message - The message to log.
          */
-        logInternalMessage?(severity: LoggingSeverity, message: _InternalLogMessage): void;
+        logInternalMessage?(severity: LoggingSeverity, message: IInternalLogMessage): void;
         /**
          * Optional Callback hook to allow the diagnostic logger to update it's configuration
          * @param updateState - The new configuration state to apply to the diagnostic logger
@@ -1031,16 +1331,25 @@ declare namespace ApplicationInsights {
          * / Promise to allow any listeners to wait for the operation to complete.
          */
         unload?(isAsync?: boolean): void | IPromise<void>;
+        /**
+         * A flag that indicates whether this logger is in debug (throw real exceptions) mode
+         */
+        readonly dbgMode?: boolean;
     }
 
-    interface IDistributedTraceContext {
+    interface IDistributedTraceContext extends IDistributedTraceInit {
         /**
          * Returns the current name of the page
          */
         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;
         /**
@@ -1053,6 +1362,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;
         /**
@@ -1064,6 +1379,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;
         /**
@@ -1072,9 +1393,258 @@ 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 It is NOT recommended that you dynamically change this value after creation and it is actively
+         * being used as this may affect anyone accessing this context (as a parent for instance). You should logically
+         * treat this as readonly after creation.
+         * @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 which
+         * provides the previous behavior.
+         * @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.IOTelTraceState
+         * @remarks Unlike the OpenTelemetry {@link IOTelTraceState}, 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;
+    }
+
+    /**
+     * An object that can be used to populate a new {@link IDistributedTraceContext} instance,
+     * the included {@link IW3cTraceState} or {@link IOTelTraceState} is used as the parent of the
+     * created instances traceState
+     */
+    interface IDistributedTraceInit {
+        /**
+         * The unique identifier for the trace that this span belongs to.
+         *
+         * The trace ID is a globally unique identifier that connects all spans within a single
+         * distributed trace. It consists of 16 randomly generated bytes encoded as 32 lowercase
+         * hexadecimal characters, providing 128 bits of entropy to ensure worldwide uniqueness
+         * with practically sufficient probability.
+         *
+         * @remarks
+         * - Must be exactly 32 lowercase hexadecimal characters
+         * - Represents 128 bits (16 bytes) of random data
+         * - Shared by all spans within the same trace
+         * - Used for trace correlation across distributed systems
+         * - Should never be all zeros (invalid trace ID)
+         *
+         * @example
+         * ```typescript
+         * // Example trace ID format
+         * const traceId = "4bf92f3577b34da6a3ce929d0e0e4736";
+         *
+         * // All spans in the same trace share this ID
+         * console.log(parentSpan.spanContext().traceId === childSpan.spanContext().traceId); // true
+         * ```
+         */
+        traceId: string;
+        /**
+         * The unique identifier for this specific span within the trace.
+         *
+         * The span ID uniquely identifies this span within the trace and is used to establish
+         * parent-child relationships between spans. It consists of 8 randomly generated bytes
+         * encoded as 16 lowercase hexadecimal characters, providing 64 bits of entropy to
+         * ensure global uniqueness with practically sufficient probability.
+         *
+         * @remarks
+         * - Must be exactly 16 lowercase hexadecimal characters
+         * - Represents 64 bits (8 bytes) of random data
+         * - Unique within the trace (different spans have different span IDs)
+         * - Used as parent ID when creating child spans
+         * - Should never be all zeros (invalid span ID)
+         *
+         * @example
+         * ```typescript
+         * // Example span ID format
+         * const spanId = "00f067aa0ba902b7";
+         *
+         * // Each span has a unique ID within the trace
+         * const parentId = parentSpan.spanContext().spanId; // "00f067aa0ba902b7"
+         * const childId = childSpan.spanContext().spanId;   // "b9c7c989f97918e1"
+         *
+         * // Child span uses parent's span ID as its parent ID
+         * console.log(childSpan.parentSpanId === parentId); // true
+         * ```
+         */
+        spanId: string;
+        /**
+         * Indicates whether this span context was propagated from a remote parent span.
+         *
+         * This flag distinguishes between spans created locally within the same process
+         * and spans that represent operations in remote services. Remote spans are typically
+         * created when trace context is received via HTTP headers, message queues, or other
+         * inter-process communication mechanisms.
+         *
+         * @defaultValue false - spans are considered local unless explicitly marked as remote
+         *
+         * @remarks
+         * - True only when span context was received from another process/service
+         * - Helps distinguish local vs. distributed trace segments
+         * - Used by tracing systems for visualization and analysis
+         * - Local child spans of remote parents are NOT considered remote themselves
+         *
+         * @example
+         * ```typescript
+         * // HTTP service receiving trace context
+         * const incomingSpanContext = extractSpanContextFromHeaders(request.headers);
+         * console.log(incomingSpanContext.isRemote); // true
+         *
+         * // Child span created locally
+         * const localChild = tracer.startSpan('local-operation', {
+         *   parent: incomingSpanContext
+         * });
+         * console.log(localChild.spanContext().isRemote); // false
+         * ```
+         */
+        isRemote?: boolean;
+        /**
+         * Trace flags that control trace behavior and indicate sampling decisions.
+         *
+         * The trace flags are represented as a single byte (8-bit bitmap) that carries
+         * trace-level information. The least significant bit (0x01) indicates whether
+         * the trace is sampled. When this bit is set, it documents that the caller
+         * may have recorded trace data. Additional bits are reserved for future use
+         * and should be ignored when not understood.
+         *
+         * @remarks
+         * - Represented as a number (0-255) corresponding to 8 bits
+         * - Bit 0 (0x01): Sampled flag - indicates trace may contain recorded data
+         * - Bits 1-7: Reserved for future use, should be preserved during propagation
+         * - Used by sampling algorithms to make consistent decisions across services
+         * - See {@link eW3CTraceFlags} for standard flag values
+         *
+         * @example
+         * ```typescript
+         * // Check if trace is sampled
+         * const isSampled = (spanContext.traceFlags & 0x01) === 1;
+         *
+         * // Common flag values
+         * const UNSAMPLED = 0x00; // 00000000 - not sampled
+         * const SAMPLED = 0x01;   // 00000001 - sampled
+         *
+         * // Preserving unknown flags during propagation
+         * const preservedFlags = spanContext.traceFlags | 0x01; // Set sampled bit while preserving others
+         *
+         * // W3C traceparent header format includes these flags
+         * const traceparent = `00-${traceId}-${spanId}-${traceFlags.toString(16).padStart(2, '0')}`;
+         * ```
+         */
+        traceFlags?: number;
+        /**
+         * Vendor-specific trace state information for cross-system trace correlation.
+         *
+         * The trace state carries tracing-system-specific context in a standardized format
+         * defined by the W3C Trace Context specification. It allows multiple tracing systems
+         * to participate in the same trace by providing a mechanism for each system to add
+         * its own metadata without interfering with others.
+         *
+         * The trace state is formatted as a comma-separated list of key-value pairs, where
+         * each pair represents one tracing system's contribution. Keys should be unique
+         * within the trace state and follow specific naming conventions.
+         *
+         * @remarks
+         * - Maximum of 32 list members allowed
+         * - Each member format: `key=value` separated by commas
+         * - Keys should be namespaced to avoid conflicts (e.g., `vendor@system=value`)
+         * - Total size should not exceed 512 characters for practical header limits
+         * - Spaces around list members are ignored
+         * - Preserves vendor-specific information during trace propagation
+         *
+         * @see {@link https://www.w3.org/TR/trace-context/#tracestate-field | W3C Trace Context Specification}
+         *
+         * @example
+         * ```typescript
+         * // Single tracing system
+         * const singleVendor = {
+         *   get: (key: string) => key === 'rojo' ? '00f067aa0ba902b7' : undefined,
+         *   set: (key: string, value: string) => { ... },
+         *   unset: (key: string) => { ... },
+         *   serialize: () => 'rojo=00f067aa0ba902b7'
+         * };
+         *
+         * // Multiple tracing systems
+         * const multiVendor = {
+         *   serialize: () => 'rojo=00f067aa0ba902b7,congo=t61rcWkgMzE,vendor@system=custom-value'
+         * };
+         *
+         * // Accessing trace state
+         * const rojoValue = spanContext.traceState?.get('rojo');
+         * const serialized = spanContext.traceState?.serialize();
+         *
+         * // HTTP header format (When the traceState is an IOTelTraceState)
+         * headers['tracestate'] = spanContext.traceState?.serialize() || '';
+         *
+         * // HTTP header format (When the traceState is an IW3cTraceState)
+         * headers['tracestate'] = spanContext.traceState?.hdrs()[0] || '';
+         * ```
+         */
+        traceState?: IW3cTraceState | IOTelTraceState;
     }
 
     /**
@@ -1141,7 +1711,7 @@ declare namespace ApplicationInsights {
          * Identifies configuration override values when given feature is enabled
          * NOTE: should use flat string for fields, for example, if you want to set value for extensionConfig.Ananlytics.disableAjaxTrackig in configurations,
          * you should use "extensionConfig.Ananlytics.disableAjaxTrackig" as field name: \{["extensionConfig.Analytics.disableAjaxTrackig"]:1\}
-         * Default: undefined
+         * @default undefined
          */
         onCfg?: {
             [field: string]: any;
@@ -1150,7 +1720,7 @@ declare namespace ApplicationInsights {
          * Identifies configuration override values when given feature is disabled
          * NOTE: should use flat string for fields, for example, if you want to set value for extensionConfig.Ananlytics.disableAjaxTrackig in configurations,
          * you should use "extensionConfig.Ananlytics.disableAjaxTrackig" as field name: \{["extensionConfig.Analytics.disableAjaxTrackig"]:1\}
-         * Default: undefined
+         * @default undefined
          */
         offCfg?: {
             [field: string]: any;
@@ -1162,6 +1732,11 @@ declare namespace ApplicationInsights {
         blockCdnCfg?: boolean;
     }
 
+    interface IInternalLogMessage {
+        message: string;
+        messageId: _InternalMessageId;
+    }
+
     /**
      * Internal Interface
      */
@@ -1361,47 +1936,1094 @@ declare namespace ApplicationInsights {
         offlineBatchDrop?(cnt: number, reason?: number): void;
     }
 
-    class _InternalLogMessage {
-        static dataType: string;
-        message: string;
-        messageId: _InternalMessageId;
-        constructor(msgId: _InternalMessageId, msg: string, isUserAct?: boolean, properties?: Object);
-    }
-
     type _InternalMessageId = number | _eInternalMessageId;
 
-    /** IPayloadData describes interface of payload sent via POST channel */
-    interface IPayloadData {
-        urlString: string;
-        data: Uint8Array | string;
-        headers?: {
-            [name: string]: string;
-        };
-        timeout?: number;
-        disableXhrSync?: boolean;
-        disableFetchKeepAlive?: boolean;
-        sendReason?: SendRequestReason;
-    }
-
     /**
-     * This interface identifies the details of an internal performance event - it does not represent an outgoing reported event
+     * The main OpenTelemetry API interface that provides access to all OpenTelemetry functionality.
+     * This interface extends the IOTelTracerProvider and serves as the entry point for OpenTelemetry operations.
+     *
+     * @example
+     * ```typescript
+     * // Get a tracer from the API instance
+     * const tracer = otelApi.getTracer("my-component");
+     *
+     * // Create a span
+     * const span = tracer.startSpan("operation");
+     *
+     * // Access context manager
+     * const currentContext = otelApi.context.active();
+     *
+     * // Access trace API
+     * const activeSpan = otelApi.trace.getActiveSpan();
+     * ```
+     *
+     * @since 3.4.0
      */
-    interface IPerfEvent {
+    interface IOTelApi extends IOTelTracerProvider {
         /**
-         * The name of the performance event
+         * The configuration object that contains all OpenTelemetry-specific settings.
+         * This includes tracing configuration, error handlers, and other OpenTelemetry options.
+         *
+         * @remarks
+         * Changes to this configuration after initialization may not take effect until
+         * the next telemetry operation, depending on the implementation.
          */
-        name: string;
+        cfg: IOTelConfig;
         /**
-         * The start time of the performance event
+         * The current {@link ITraceHost} instance for this IOTelApi instance, this is effectively
+         * the OpenTelemetry ContextAPI instance without the static methods.
+         * @returns The ContextManager instance
          */
-        start: number;
+        host: ITraceHost;
         /**
-         * The payload (contents) of the perfEvent, may be null or only set after the event has completed depending on
-         * the runtime environment.
+         * The current {@link ITraceApi} instance for this IOTelApi instance, this is
+         * effectively the OpenTelemetry TraceAPI instance without the static methods.
+         * @returns The current {@link ITraceApi} instance
          */
-        payload: any;
+        trace: ITraceApi;
+    }
+
+    /**
+     * Configuration interface for OpenTelemetry attribute limits.
+     * These limits help control the size and number of attributes to prevent
+     * excessive memory usage and ensure consistent performance.
+     *
+     * @example
+     * ```typescript
+     * const limits: IOTelAttributeLimits = {
+     *   attributeCountLimit: 128,        // Maximum 128 attributes
+     *   attributeValueLengthLimit: 4096  // Maximum 4KB per attribute value
+     * };
+     * ```
+     *
+     * @remarks
+     * When limits are exceeded:
+     * - Additional attributes beyond `attributeCountLimit` are dropped
+     * - Attribute values longer than `attributeValueLengthLimit` are truncated
+     * - The behavior may vary based on the specific implementation
+     *
+     * @since 3.4.0
+     */
+    interface IOTelAttributeLimits {
         /**
-         * Is this occurring from an asynchronous event
+         * Maximum allowed length for attribute values in characters.
+         *
+         * @remarks
+         * - Values longer than this limit will be truncated
+         * - Applies to string attribute values only
+         * - Numeric and boolean values are not affected by this limit
+         * - Array values have this limit applied to each individual element
+         *
+         * @defaultValue 4096
+         *
+         * @example
+         * ```typescript
+         * // If attributeValueLengthLimit is 100:
+         * span.setAttribute("description", "a".repeat(200)); // Will be truncated to 100 characters
+         * span.setAttribute("count", 12345);                 // Not affected (number)
+         * span.setAttribute("enabled", true);                // Not affected (boolean)
+         * ```
+         */
+        attributeValueLengthLimit?: number;
+        /**
+         * Maximum number of attributes allowed per telemetry item.
+         *
+         * @remarks
+         * - Attributes added beyond this limit will be dropped
+         * - The order of attributes matters; earlier attributes take precedence
+         * - This limit applies to the total count of attributes, regardless of their type
+         * - Inherited or default attributes count toward this limit
+         *
+         * @defaultValue 128
+         *
+         * @example
+         * ```typescript
+         * // If attributeCountLimit is 5:
+         * span.setAttributes({
+         *   "attr1": "value1",  // Kept
+         *   "attr2": "value2",  // Kept
+         *   "attr3": "value3",  // Kept
+         *   "attr4": "value4",  // Kept
+         *   "attr5": "value5",  // Kept
+         *   "attr6": "value6"   // Dropped (exceeds limit)
+         * });
+         * ```
+         */
+        attributeCountLimit?: number;
+    }
+
+    /**
+     * Attributes is a map from string to attribute values.
+     *
+     * Note: only the own enumerable keys are counted as valid attribute keys.
+     *
+     * @since 3.4.0
+     */
+    interface IOTelAttributes {
+        [key: string]: OTelAttributeValue | undefined;
+    }
+
+    /**
+     * OpenTelemetry configuration interface
+     * Provides configuration specific to the OpenTelemetry extensions
+     */
+    interface IOTelConfig {
+        /**
+         * Configuration interface for OpenTelemetry tracing functionality.
+         * This interface contains all the settings that control how traces are created,
+         * processed, and managed within the OpenTelemetry system.
+         *
+         * @example
+         * ```typescript
+         * const traceCfg: ITraceCfg = {
+         *   serviceName: "my-service",
+         *   generalLimits: {
+         *     attributeCountLimit: 128,
+         *     attributeValueLengthLimit: 4096
+         *   },
+         *   spanLimits: {
+         *     attributeCountLimit: 128,
+         *     linkCountLimit: 128,
+         *     eventCountLimit: 128
+         *   }
+         * };
+         * ```
+         *
+         * @since 3.4.0
+         */
+        traceCfg?: ITraceCfg;
+        /**
+         * Error handlers for OpenTelemetry operations.
+         * This interface allows you to specify custom error handling logic for various
+         * OpenTelemetry components, enabling better control over how errors are managed
+         * within the OpenTelemetry system.
+         *
+         * @see {@link IOTelErrorHandlers}
+         *
+         * @example
+         * ```typescript
+         * const errorHandlers: IOTelErrorHandlers = {
+         *   attribError: (message, key, value) => {
+         *    console.warn(`Attribute error for ${key}:`, message);
+         *  }
+         * };
+         * ```
+         */
+        errorHandlers?: IOTelErrorHandlers;
+    }
+
+    /**
+     * Configuration interface for OpenTelemetry error handling callbacks.
+     * Provides hooks to customize how different types of errors and diagnostic
+     * messages are handled within the OpenTelemetry system.
+     *
+     * @example
+     * ```typescript
+     * const errorHandlers: IOTelErrorHandlers = {
+     *   attribError: (message, key, value) => {
+     *     console.warn(`Attribute error for ${key}:`, message);
+     *   },
+     *   spanError: (message, spanName) => {
+     *     logger.error(`Span ${spanName} error:`, message);
+     *   },
+     *   warn: (message) => {
+     *     logger.warn(message);
+     *   },
+     *   error: (message) => {
+     *     logger.error(message);
+     *   }
+     * };
+     * ```
+     *
+     * @remarks
+     * If handlers are not provided, default behavior will be used:
+     * - `attribError`: Throws an `OTelInvalidAttributeError`
+     * - `spanError`: Logs to console or calls warn handler
+     * - `debug`: Logs to console.log
+     * - `warn`: Logs to console.warn
+     * - `error`: Logs to console.error
+     * - `notImplemented`: Logs to console.error
+     *
+     * @since 3.4.0
+     */
+    interface IOTelErrorHandlers {
+        /**
+         * Handles attribute-related errors, such as invalid attribute values or keys.
+         * Called when an attribute operation fails validation or processing.
+         *
+         * @param message - Descriptive error message explaining what went wrong
+         * @param key - The attribute key that caused the error
+         * @param value - The attribute value that caused the error (may be of any type)
+         *
+         * @remarks
+         * Common scenarios that trigger this handler:
+         * - Invalid attribute key format
+         * - Attribute value exceeds length limits
+         * - Unsupported attribute value type
+         * - Attribute count exceeds limits
+         *
+         * @default Throws an `OTelInvalidAttributeError`
+         *
+         * @example
+         * ```typescript
+         * attribError: (message, key, value) => {
+         *   metrics.increment('otel.attribute.errors', { key, type: typeof value });
+         *   logger.warn(`Attribute ${key} rejected: ${message}`);
+         * }
+         * ```
+         */
+        attribError?: (message: string, key: string, value: any) => void;
+        /**
+         * Handles span-related errors that occur during span operations.
+         * Called when a span operation fails or encounters an unexpected condition.
+         *
+         * @param message - Descriptive error message explaining the span error
+         * @param spanName - The name of the span that encountered the error
+         *
+         * @remarks
+         * Common scenarios that trigger this handler:
+         * - Span operation called on an ended span
+         * - Invalid span configuration
+         * - Span processor errors
+         * - Context propagation failures
+         *
+         * @default Logs to console or calls the warn handler
+         *
+         * @example
+         * ```typescript
+         * spanError: (message, spanName) => {
+         *   metrics.increment('otel.span.errors', { span_name: spanName });
+         *   logger.error(`Span operation failed for "${spanName}": ${message}`);
+         * }
+         * ```
+         */
+        spanError?: (message: string, spanName: string) => void;
+        /**
+         * Handles debug-level diagnostic messages.
+         * Used for detailed troubleshooting information that is typically
+         * only relevant during development or when diagnosing issues.
+         *
+         * @param message - Debug message to be handled
+         *
+         * @remarks
+         * Debug messages are typically:
+         * - Verbose operational details
+         * - Internal state information
+         * - Performance metrics
+         * - Development-time diagnostics
+         *
+         * @default Logs to console.log
+         *
+         * @example
+         * ```typescript
+         * debug: (message) => {
+         *   if (process.env.NODE_ENV === 'development') {
+         *     console.debug('[OTel Debug]', message);
+         *   }
+         * }
+         * ```
+         */
+        debug?: (message: string) => void;
+        /**
+         * Handles warning-level messages for non-fatal issues.
+         * Used for conditions that are unusual but don't prevent continued operation.
+         *
+         * @param message - Warning message to be handled
+         *
+         * @remarks
+         * Warning scenarios include:
+         * - Configuration issues that fall back to defaults
+         * - Performance degradation
+         * - Deprecated API usage
+         * - Resource limit approaches
+         *
+         * @default Logs to console.warn
+         *
+         * @example
+         * ```typescript
+         * warn: (message) => {
+         *   logger.warn('[OTel Warning]', message);
+         *   metrics.increment('otel.warnings');
+         * }
+         * ```
+         */
+        warn?: (message: string) => void;
+        /**
+         * Handles general error conditions that may affect functionality.
+         * Used for significant errors that should be investigated but may not be fatal.
+         *
+         * @param message - Error message to be handled
+         *
+         * @remarks
+         * Error scenarios include:
+         * - Failed network requests
+         * - Configuration validation failures
+         * - Resource allocation failures
+         * - Unexpected runtime conditions
+         *
+         * @default Logs to console.error
+         *
+         * @example
+         * ```typescript
+         * error: (message) => {
+         *   logger.error('[OTel Error]', message);
+         *   errorReporting.captureException(new Error(message));
+         * }
+         * ```
+         */
+        error?: (message: string) => void;
+        /**
+         * Handles errors related to unimplemented functionality.
+         * Called when a method or feature is not yet implemented or is intentionally
+         * disabled in the current configuration.
+         *
+         * @param message - Message describing the unimplemented functionality
+         *
+         * @remarks
+         * Common scenarios:
+         * - Placeholder methods that haven't been implemented
+         * - Features disabled in the current build
+         * - Platform-specific functionality not available
+         * - Optional features not included in the configuration
+         *
+         * @default Logs to console.error
+         *
+         * @example
+         * ```typescript
+         * notImplemented: (message) => {
+         *   logger.warn(`[OTel Not Implemented] ${message}`);
+         *   if (process.env.NODE_ENV === 'development') {
+         *     console.trace('Not implemented method called');
+         *   }
+         * }
+         * ```
+         */
+        notImplemented?: (message: string) => void;
+    }
+
+    interface IOTelExceptionWithCode {
+        code: string | number;
+        name?: string;
+        message?: string;
+        stack?: string;
+    }
+
+    interface IOTelExceptionWithMessage {
+        code?: string | number;
+        message: string;
+        name?: string;
+        stack?: string;
+    }
+
+    interface IOTelExceptionWithName {
+        code?: string | number;
+        message?: string;
+        name: string;
+        stack?: string;
+    }
+
+    /**
+     * Enhanced high-resolution time interface that extends the base tuple with additional properties.
+     * Provides a more structured way to work with high-resolution timestamps.
+     *
+     * @example
+     * ```typescript
+     * const hrTime: IOTelHrTime = {
+     *   0: 1609459200,     // seconds since Unix epoch
+     *   1: 500000000,      // nanoseconds (0-999,999,999)
+     * };
+     * ```
+     *
+     * @since 3.4.0
+     */
+    interface IOTelHrTime extends OTelHrTimeBase {
+        /**
+         * Seconds since Unix epoch (January 1, 1970 00:00:00 UTC).
+         * Must be a non-negative integer.
+         */
+        0: number;
+        /**
+         * Nanoseconds within the second specified by index 0.
+         * Must be in the range [0, 999999999].
+         */
+        1: number;
+    }
+
+    /**
+     * Provides an OpenTelemetry compatible interface for spans conforming to the OpenTelemetry API specification (v1.9.0).
+     *
+     * A span represents an operation within a trace and is the fundamental unit of work in distributed tracing.
+     * Spans can be thought of as a grouping mechanism for a set of operations that are executed as part of
+     * a single logical unit of work, providing timing information and contextual data about the operation.
+     *
+     * Spans form a tree structure within a trace, with a single root span that may have zero or more child spans,
+     * which in turn may have their own children. This hierarchical structure allows for detailed analysis of
+     * complex, multi-step operations across distributed systems.
+     *
+     * @since 3.4.0
+     *
+     * @remarks
+     * - All spans created by this library implement the ISpan interface and extend the IReadableSpan interface
+     * - Spans should be ended by calling `end()` when the operation completes
+     * - Once ended, spans should generally not be used for further operations
+     * - Spans automatically track timing information from creation to end
+     *
+     * @example
+     * ```typescript
+     * // Basic span usage
+     * const span = tracer.startSpan('user-authentication');
+     * span.setAttribute('user.id', '12345');
+     * span.setAttribute('auth.method', 'oauth2');
+     *
+     * try {
+     *   const result = await authenticateUser();
+     *   span.setStatus({ code: SpanStatusCode.OK });
+     *   span.setAttribute('auth.success', true);
+     * } catch (error) {
+     *   span.recordException(error);
+     *   span.setStatus({
+     *     code: SpanStatusCode.ERROR,
+     *     message: 'Authentication failed'
+     *   });
+     * } finally {
+     *   span.end();
+     * }
+     * ```
+     */
+    interface IOTelSpan {
+        /**
+         * Returns the span context object associated with this span.
+         *
+         * The span context is an immutable, serializable identifier that uniquely identifies
+         * this span within a trace. It contains the trace ID, span ID, and trace flags that
+         * can be used to create new child spans or propagate trace context across process boundaries.
+         *
+         * The returned span context remains valid even after the span has ended, making it
+         * useful for asynchronous operations and cross-service communication.
+         *
+         * @returns The immutable span context associated with this span
+         *
+         * @remarks
+         * - The span context is the primary mechanism for trace propagation
+         * - Context can be serialized and transmitted across network boundaries
+         * - Contains trace ID (unique to the entire trace) and span ID (unique to this span)
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('parent-operation');
+         * const spanContext = span.spanContext();
+         *
+         * // Use context to create child spans in other parts of the system
+         * const childSpan = tracer.startSpan('child-operation', {
+         *   parent: spanContext
+         * });
+         *
+         * // Context can be serialized for cross-service propagation
+         * const traceId = spanContext.traceId;
+         * const spanId = spanContext.spanId;
+         * ```
+         */
+        spanContext(): IDistributedTraceContext;
+        /**
+         * Sets a single attribute on the span with the specified key and value.
+         *
+         * Attributes provide contextual information about the operation represented by the span.
+         * They are key-value pairs that help with filtering, grouping, and understanding spans
+         * in trace analysis tools. Attributes should represent meaningful properties of the operation.
+         *
+         * @param key - The attribute key, should be descriptive and follow naming conventions
+         * @param value - The attribute value; null or undefined values are invalid and result in undefined behavior
+         *
+         * @returns This span instance for method chaining
+         *
+         * @remarks
+         * - Attribute keys should follow semantic conventions when available
+         * - Common attributes include service.name, http.method, db.statement, etc.
+         * - Setting null or undefined values is invalid and may cause unexpected behavior
+         * - Attributes set after span creation don't affect sampling decisions
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('http-request');
+         *
+         * // Set individual attributes with descriptive keys
+         * span.setAttribute('http.method', 'POST')
+         *     .setAttribute('http.url', 'https://api.example.com/users')
+         *     .setAttribute('http.status_code', 201)
+         *     .setAttribute('user.id', '12345')
+         *     .setAttribute('request.size', 1024);
+         * ```
+         */
+        setAttribute(key: string, value: OTelAttributeValue): this;
+        /**
+         * Sets multiple attributes on the span at once using an attributes object.
+         *
+         * This method allows efficient batch setting of multiple attributes in a single call.
+         * All attributes in the provided object will be added to the span, supplementing any
+         * existing attributes (duplicate keys will be overwritten).
+         *
+         * @param attributes - An object containing key-value pairs to set as span attributes
+         *
+         * @returns This span instance for method chaining
+         *
+         * @remarks
+         * - Null or undefined attribute values are invalid and will result in undefined behavior
+         * - More efficient than multiple `setAttribute` calls for bulk operations
+         * - Existing attributes with the same keys will be overwritten
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('database-query');
+         *
+         * // Set multiple attributes efficiently
+         * span.setAttributes({
+         *   'db.system': 'postgresql',
+         *   'db.name': 'user_database',
+         *   'db.table': 'users',
+         *   'db.operation': 'SELECT',
+         *   'db.rows_affected': 5,
+         *   'query.duration_ms': 15.7
+         * });
+         * ```
+         */
+        setAttributes(attributes: IOTelAttributes): this;
+        /**
+         * The {@link IAttributeContainer | attribute container} associated with this span, providing
+         * advanced attribute management capabilities. Rather than using the {@link IReadableSpan#attributes}
+         * directly which returns a readonly {@link IOTelAttributes} map that is a snapshot of the attributes at
+         * the time of access, the attribute container offers methods to get, set, delete, and iterate over attributes
+         * with fine-grained control.
+         * It is recommended that you only access the {@link IReadableSpan#attributes} property sparingly due to the
+         * performance cost of taking a snapshot of all attributes.
+         */
+        readonly attribContainer: IAttributeContainer;
+        /**
+         * Sets the status of the span to indicate the success or failure of the operation.
+         *
+         * The span status provides a standardized way to indicate whether the operation
+         * completed successfully, encountered an error, or is in an unknown state.
+         * This status is used by observability tools to provide meaningful insights
+         * about system health and operation outcomes.
+         *
+         * @param status - The status object containing code and optional message
+         *
+         * @returns This span instance for method chaining
+         *
+         * @remarks
+         * - Default status is UNSET until explicitly set
+         * - Setting status overrides any previous status values
+         * - ERROR status should be accompanied by a descriptive message when possible
+         * - Status should reflect the final outcome of the operation
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('payment-processing');
+         *
+         * try {
+         *   const result = await processPayment(paymentData);
+         *
+         *   // Indicate successful completion
+         *   span.setStatus({
+         *     code: SpanStatusCode.OK
+         *   });
+         *
+         * } catch (error) {
+         *   // Indicate operation failed
+         *   span.setStatus({
+         *     code: SpanStatusCode.ERROR,
+         *     message: 'Payment processing failed: ' + error.message
+         *   });
+         *
+         *   span.recordException(error);
+         * }
+         * ```
+         */
+        setStatus(status: IOTelSpanStatus): this;
+        /**
+         * Updates the name of the span, overriding the name provided during creation.
+         *
+         * Span names should be descriptive and represent the operation being performed.
+         * Updating the name can be useful when the operation's scope becomes clearer
+         * during execution, or when implementing generic spans that need specific naming
+         * based on runtime conditions.
+         *
+         * @param name - The new name for the span, should be descriptive of the operation
+         *
+         * @returns This span instance for method chaining
+         *
+         * @remarks
+         * - Name updates may affect sampling behavior depending on implementation
+         * - Choose names that are meaningful but not too specific to avoid cardinality issues
+         * - Follow naming conventions consistent with your observability strategy
+         * - Consider the impact on existing traces and dashboards when changing names
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('generic-operation');
+         *
+         * // Update name based on runtime determination
+         * if (operationType === 'user-registration') {
+         *   span.updateName('user-registration');
+         *   span.setAttribute('operation.type', 'registration');
+         * } else if (operationType === 'user-login') {
+         *   span.updateName('user-authentication');
+         *   span.setAttribute('operation.type', 'authentication');
+         * }
+         * ```
+         */
+        updateName(name: string): this;
+        /**
+         * Marks the end of the span's execution and records the end timestamp.
+         *
+         * This method finalizes the span and makes it available for export to tracing systems.
+         * Once ended, the span should not be used for further operations. The span's duration
+         * is calculated from its start time to the end time provided or current time.
+         *
+         * @param endTime - Optional end time; if not provided, current time is used
+         *
+         * @remarks
+         * - This method does NOT return `this` to discourage chaining after span completion
+         * - Ending a span has no effect on child spans, which may continue running
+         * - Child spans can be ended independently after their parent has ended
+         * - The span becomes eligible for export once ended
+         * - Calling end() multiple times has no additional effect
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('file-processing');
+         *
+         * try {
+         *   // Perform the operation
+         *   const result = await processFile(filePath);
+         *
+         *   // Record success
+         *   span.setStatus({ code: SpanStatusCode.OK });
+         *   span.setAttribute('file.size', result.size);
+         *
+         * } catch (error) {
+         *   span.recordException(error);
+         *   span.setStatus({
+         *     code: SpanStatusCode.ERROR,
+         *     message: error.message
+         *   });
+         * } finally {
+         *   // Always end the span
+         *   span.end();
+         *   // Don't use span after this point
+         * }
+         *
+         * // Custom end time example
+         * const customEndTime = Date.now() * 1000000; // nanoseconds
+         * span.end(customEndTime);
+         * ```
+         */
+        end(endTime?: OTelTimeInput): void;
+        /**
+         * Returns whether this span is actively recording information.
+         *
+         * A recording span accepts and stores attributes, events, status, and other span data.
+         * Non-recording spans (typically due to sampling decisions) may ignore operations
+         * like setAttribute() to optimize performance. This method allows conditional
+         * logic to avoid expensive operations on non-recording spans.
+         *
+         * @returns True if the span is actively recording information, false otherwise
+         *
+         * @remarks
+         * - Recording status is typically determined at span creation time
+         * - Non-recording spans still provide valid span context for propagation
+         * - Use this check to avoid expensive attribute calculations for non-recording spans
+         * - Recording status remains constant throughout the span's lifetime
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('data-processing');
+         *
+         * // Only perform expensive operations if span is recording
+         * if (span.isRecording()) {
+         *   const metadata = await expensiveMetadataCalculation();
+         *   span.setAttributes({
+         *     'process.metadata': JSON.stringify(metadata),
+         *     'process.complexity': metadata.complexity,
+         *     'process.estimated_duration': metadata.estimatedMs
+         *   });
+         * }
+         *
+         * // Always safe to set basic attributes
+         * span.setAttribute('process.started', true);
+         * ```
+         */
+        isRecording(): boolean;
+        /**
+         * Records an exception as a span event with automatic error status handling.
+         *
+         * This method captures exception information and automatically creates a span event
+         * with standardized exception attributes. It's the recommended way to handle errors
+         * within spans, providing consistent error reporting across the application.
+         *
+         * @param exception - The exception to record; accepts string messages or Error objects
+         * @param time - Optional timestamp for when the exception occurred; defaults to current time
+         *
+         * @remarks
+         * - Automatically extracts exception type, message, and stack trace when available
+         * - Creates a standardized span event with exception details
+         * - Does NOT automatically set span status to ERROR - call setStatus() explicitly if needed
+         * - Exception events are useful for debugging and error analysis
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('risky-operation');
+         *
+         * try {
+         *   await performRiskyOperation();
+         *   span.setStatus({ code: SpanStatusCode.OK });
+         *
+         * } catch (error) {
+         *   // Record the exception details
+         *   span.recordException(error);
+         *
+         *   // Explicitly set error status
+         *   span.setStatus({
+         *     code: SpanStatusCode.ERROR,
+         *     message: 'Operation failed due to: ' + error.message
+         *   });
+         *
+         *   // Re-throw if needed
+         *   throw error;
+         * } finally {
+         *   span.end();
+         * }
+         *
+         * // Recording string exceptions
+         * span.recordException('Custom error message occurred');
+         *
+         * // Recording with custom timestamp
+         * const errorTime = Date.now() * 1000000; // nanoseconds
+         * span.recordException(error, errorTime);
+         * ```
+         */
+        recordException(exception: OTelException, time?: OTelTimeInput): void;
+    }
+
+    /**
+     * A SpanContext represents the portion of a {@link IOTelSpan} which must be
+     * serialized and propagated along side of a {@link IOTelBaggage}.
+     */
+    interface IOTelSpanContext extends IDistributedTraceInit {
+        /**
+         * 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;
+    }
+
+    /**
+     * Provides an OpenTelemetry like Interface for the Open Telemetry Api (1.9.0) SpanOptions
+     * type. Where SpanOptions are options that can be used to configure a span.
+     */
+    interface IOTelSpanOptions {
+        /**
+         * The SpanKind of a span of this span, this is used to specify
+         * the relationship between the span and its parent span.
+         * @see {@link eOTelSpanKind} for possible values.
+         * @default eOTelSpanKind.INTERNAL
+         */
+        kind?: OTelSpanKind;
+        /**
+         * A span's attributes
+         */
+        attributes?: IOTelAttributes;
+        /** A manually specified start time for the created `Span` object. */
+        startTime?: OTelTimeInput;
+        /** The new span should be a root span. (Ignore parent from context). */
+        root?: boolean;
+        /** Specify whether the span should be a recording span, default is true */
+        recording?: boolean;
+    }
+
+    interface IOTelSpanStatus {
+        /**
+         * The status code of this message.
+         */
+        code: eOTelSpanStatusCode;
+        /**
+         * A developer-facing error message.
+         */
+        message?: string;
+    }
+
+    /**
+     * OpenTelemetry tracer interface for creating and managing spans within a trace.
+     *
+     * A tracer is responsible for creating spans that represent units of work within a distributed system.
+     * Each tracer is typically associated with a specific instrumentation library or component,
+     * allowing for fine-grained control over how different parts of an application generate telemetry.
+     *
+     * @example
+     * ```typescript
+     * // Get a tracer instance
+     * const tracer = otelApi.getTracer('my-service');
+     *
+     * // Create a simple span
+     * const span = tracer.startSpan('database-query');
+     * span.setAttribute('db.operation', 'SELECT');
+     * span.end();
+     *
+     * // Create an active span with automatic context management
+     * tracer.startActiveSpan('process-request', (span) => {
+     *   span.setAttribute('request.id', '12345');
+     *
+     *   // Any spans created within this block will be children of this span
+     *   processRequest();
+     *
+     *   span.end();
+     * });
+     * ```
+     *
+     * @see {@link IReadableSpan} - Interface for individual spans
+     * @see {@link IOTelSpanOptions} - Configuration options for span creation
+     *
+     * @since 3.4.0
+     */
+    interface IOTelTracer {
+        /**
+         * Creates and starts a new span without setting it as the active span in the current context.
+         *
+         * This method creates a span but does NOT modify the current execution context.
+         * The caller is responsible for managing the span's lifecycle, including calling `end()`
+         * when the operation completes.
+         *
+         * @param name - The name of the span, should be descriptive of the operation being traced
+         * @param options - Optional configuration for span creation (parent context, attributes, etc.)
+         *
+         * @returns The newly created span, or null if span creation failed
+         *
+         * @remarks
+         * - The returned span must be manually ended by calling `span.end()`
+         * - This span will not automatically become the parent for spans created in nested operations
+         * - Use `startActiveSpan` if you want automatic context management
+         *
+         * @example
+         * ```typescript
+         * const span = tracer.startSpan('database-operation');
+         * if (span) {
+         *   try {
+         *     span.setAttribute('db.table', 'users');
+         *     span.setAttribute('db.operation', 'SELECT');
+         *
+         *     // Perform database operation
+         *     const result = await db.query('SELECT * FROM users');
+         *
+         *     span.setAttributes({
+         *       'db.rows_affected': result.length,
+         *       'operation.success': true
+         *     });
+         *   } catch (error) {
+         *     span.setStatus({
+         *       code: SpanStatusCode.ERROR,
+         *       message: error.message
+         *     });
+         *     span.recordException(error);
+         *   } finally {
+         *     span.end(); // Always end the span
+         *   }
+         * }
+         * ```
+         */
+        startSpan(name: string, options?: IOTelSpanOptions): IReadableSpan | null;
+        /**
+         * Creates and starts a new span, sets it as the active span in the current context,
+         * and executes a provided function within this context.
+         *
+         * This method creates a span, makes it active during the execution of the provided
+         * function, and automatically ends the span when the function completes (or throws).
+         * This provides automatic span lifecycle management and context propagation.
+         *
+         * @param name - The name of the span, should be descriptive of the operation being traced
+         * @param options - Optional configuration for span creation (parent context, attributes, etc.)
+         * @param fn - The function to execute within the span's active context
+         *
+         * @returns The result of executing the provided function
+         *
+         * @remarks
+         * - The span is automatically ended when the function completes or throws an exception
+         * - The span becomes the active parent for any spans created within the function
+         * - If the function throws an error, the span status is automatically set to ERROR
+         * - This is the recommended method for most tracing scenarios due to automatic lifecycle management
+         * - Multiple overloads available for different parameter combinations
+         *
+         * @example
+         * ```typescript
+         * // Synchronous operation with just name and function
+         * const result = tracer.startActiveSpan('user-service', (span) => {
+         *   span.setAttribute('operation', 'get-user-details');
+         *   return { user: getUserData(), timestamp: new Date().toISOString() };
+         * });
+         *
+         * // With options
+         * const result2 = tracer.startActiveSpan('database-query',
+         *   { attributes: { 'db.table': 'users' } },
+         *   (span) => {
+         *     span.setAttribute('db.operation', 'SELECT');
+         *     return database.getUser('123');
+         *   }
+         * );
+         *
+         * // With full context control
+         * const result3 = tracer.startActiveSpan('external-api',
+         *   { attributes: { 'service.name': 'payment-api' } },
+         *   currentContext,
+         *   async (span) => {
+         *     try {
+         *       const response = await fetch('/api/payment');
+         *       span.setAttributes({
+         *         'http.status_code': response.status,
+         *         'operation.success': response.ok
+         *       });
+         *       return response.json();
+         *     } catch (error) {
+         *       span.setAttribute('error.type', error.constructor.name);
+         *       throw error; // Error automatically recorded
+         *     }
+         *   }
+         * );
+         * ```
+         */
+        startActiveSpan<F extends (span: IReadableSpan) => unknown>(name: string, fn: F): ReturnType<F>;
+        startActiveSpan<F extends (span: IReadableSpan) => unknown>(name: string, options: IOTelSpanOptions, fn: F): ReturnType<F>;
+    }
+
+    interface IOTelTracerOptions {
+        /**
+         * The schemaUrl of the tracer or instrumentation library
+         */
+        schemaUrl?: string;
+    }
+
+    /**
+     * OpenTelemetry Trace API for getting tracers.
+     * This provides the standard OpenTelemetry trace API entry point.
+     */
+    interface IOTelTracerProvider {
+        /**
+         * Returns a Tracer, creating one if one with the given name and version is
+         * not already created. This may return
+         * - The same Tracer instance if one has already been created with the same name and version
+         * - A new Tracer instance if one has not already been created with the same name and version
+         * - A non-operational Tracer if the provider is not operational
+         *
+         * @param name - The name of the tracer or instrumentation library.
+         * @param version - The version of the tracer or instrumentation library.
+         * @param options - The options of the tracer or instrumentation library.
+         * @returns Tracer A Tracer with the given name and version
+         */
+        getTracer(name: string, version?: string, options?: IOTelTracerOptions): IOTelTracer;
+        /**
+         * Forces the tracer provider to flush any buffered data.
+         * @returns A promise that resolves when the flush is complete.
+         */
+        forceFlush?: () => IPromise<void> | void;
+        /**
+         * Shuts down the tracer provider and releases any resources.
+         * @returns A promise that resolves when the shutdown is complete.
+         */
+        shutdown?: () => IPromise<void> | void;
+    }
+
+    /**
+     * 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;
+        data: Uint8Array | string;
+        headers?: {
+            [name: string]: string;
+        };
+        timeout?: number;
+        disableXhrSync?: boolean;
+        disableFetchKeepAlive?: boolean;
+        sendReason?: SendRequestReason;
+    }
+
+    /**
+     * This interface identifies the details of an internal performance event - it does not represent an outgoing reported event
+     */
+    interface IPerfEvent {
+        /**
+         * The name of the performance event
+         */
+        name: string;
+        /**
+         * The start time of the performance event
+         */
+        start: number;
+        /**
+         * The payload (contents) of the perfEvent, may be null or only set after the event has completed depending on
+         * the runtime environment.
+         */
+        payload: any;
+        /**
+         * Is this occurring from an asynchronous event
          */
         isAsync: boolean;
         /**
@@ -1770,6 +3392,73 @@ declare namespace ApplicationInsights {
         finally(onfinally?: FinallyPromiseHandler): IPromise<T>;
     }
 
+    /**
+     * Provides an OpenTelemetry compatible Interface for the Open Telemetry Sdk-Trace-Base (1.8.0 and 2.0.0) ReadableSpan type.
+     *
+     * The IReadableSpan interface is used to represent a span that can be read and exported, while the OpenTelemetry
+     * specification defines a ReadableSpan as a Span that has been ended and is ready to be exported. By default all
+     * spans created by this library implement the IReadableSpan interface which also extends the {@link IOTelSpan} interface.
+     *
+     * This interface is defined to provide compatibility with exporters defined by the OpenTelemetry Trace SDK.
+     * @since 3.4.0
+     */
+    interface IReadableSpan extends IOTelSpan {
+        /**
+         * The span's unique identifier.
+         */
+        readonly name: string;
+        /**
+         * Identifies the type (or kind) that this span is representing.
+         */
+        readonly kind: OTelSpanKind;
+        readonly spanContext: () => IDistributedTraceContext;
+        readonly parentSpanId?: string;
+        readonly parentSpanContext?: IDistributedTraceContext;
+        readonly startTime: IOTelHrTime;
+        readonly endTime: IOTelHrTime;
+        readonly status: IOTelSpanStatus;
+        /**
+         * Provides a snapshot of the span's attributes at the time this span was ended.
+         * @returns A read-only snapshot of the span's attributes
+         * @remarks
+         * It is recommended that you only access this property sparingly due to the
+         * performance cost of taking a snapshot of all attributes.
+         */
+        readonly attributes: IOTelAttributes;
+        readonly duration: IOTelHrTime;
+        readonly ended: boolean;
+        readonly droppedAttributesCount: number;
+    }
+
+    /**
+     * Represents the execution scope for a span, combining the trace instance and the active span.
+     * This interface is used as the context for executing functions within a span's scope.
+     *
+     * @since 3.4.0
+     */
+    interface ISpanScope<T extends ITraceHost = ITraceHost> {
+        /**
+         * The trace host (core or AISKU instance).
+         * @since 3.4.0
+         */
+        readonly host: T;
+        /**
+         * The active span for this execution scope.
+         * @since 3.4.0
+         */
+        readonly span: IReadableSpan;
+        /**
+         * The previously active span before this scope was created, if any.
+         * @since 3.4.0
+         */
+        readonly prvSpan?: IReadableSpan;
+        /**
+         * Restores the previous active span in the trace instance.
+         * @since 3.4.0
+         */
+        restore(): void;
+    }
+
     interface ITelemetryInitializerHandler extends ILegacyUnloadHook {
         remove(): void;
     }
@@ -2029,6 +3718,205 @@ declare namespace ApplicationInsights {
         enabled: boolean;
     }
 
+    /**
+     * ITraceApi provides an interface definition which is simular to the OpenTelemetry TraceAPI
+     */
+    interface ITraceApi {
+        /**
+         * Returns a Tracer, creating one if one with the given name and version
+         * if one has not already created.
+         *
+         * @param name - The name of the tracer or instrumentation library.
+         * @param version - The version of the tracer or instrumentation library.
+         * @param options - The options of the tracer or instrumentation library.
+         * @returns Tracer A Tracer with the given name and version
+         */
+        getTracer(name: string, version?: string, options?: IOTelTracerOptions): IOTelTracer;
+        /**
+         * Wrap the given {@link IDistributedTraceContext} in a new non-recording {@link IReadableSpan}
+         *
+         * @param spanContext - The {@link IDistributedTraceContext} to be wrapped
+         * @returns a new non-recording {@link IReadableSpan} with the provided context
+         */
+        wrapSpanContext(spanContext: IDistributedTraceContext | IDistributedTraceInit | IOTelSpanContext): IReadableSpan;
+        /**
+         * Returns true if this {@link IDistributedTraceContext} is valid.
+         * @return true if this {@link IDistributedTraceContext} is valid.
+         */
+        isSpanContextValid(spanContext: IDistributedTraceContext | IDistributedTraceInit | IOTelSpanContext): boolean;
+        /**
+         * Gets the span from the current context, if one exists.
+         */
+        getActiveSpan(): IReadableSpan | undefined | null;
+        /**
+         * Set or clear the current active span.
+         * @param span - The span to set as the active span, or null/undefined to clear the active span.
+         * @return An ISpanScope instance returned by the host, or void if there is no defined host.
+         */
+        setActiveSpan(span: IReadableSpan | undefined | null): ISpanScope | undefined | null;
+    }
+
+    /**
+     * Configuration interface for OpenTelemetry compatible tracing functionality.
+     * This interface contains all the settings that control how traces are created,
+     * processed, and managed within the OpenTelemetry system.
+     *
+     * @example
+     * ```typescript
+     * const traceCfg: ITraceCfg = {
+     *   serviceName: "my-service",
+     *   generalLimits: {
+     *     attributeCountLimit: 128,
+     *     attributeValueLengthLimit: 4096
+     *   },
+     *   spanLimits: {
+     *     attributeCountLimit: 128,
+     *     linkCountLimit: 128,
+     *     eventCountLimit: 128
+     *   }
+     * };
+     * ```
+     *
+     * @since 3.4.0
+     */
+    interface ITraceCfg {
+        /**
+         * Global attribute limits that apply to all telemetry items.
+         * These limits help prevent excessive memory usage and ensure consistent
+         * behavior across different telemetry types.
+         *
+         * @remarks
+         * These limits are inherited by more specific configurations unless overridden.
+         * For example, spans will use these limits unless `spanLimits` specifies different values.
+         */
+        generalLimits?: IOTelAttributeLimits;
+        /**
+         * The name of the service generating telemetry data.
+         * This name will be included in all telemetry items as a resource attribute.
+         *
+         * @remarks
+         * The service name is crucial for identifying and filtering telemetry data
+         * in observability systems. It should be consistent across all instances
+         * of the same service.
+         *
+         * @example
+         * ```typescript
+         * serviceName: "user-authentication-service"
+         * ```
+         */
+        serviceName?: string;
+        /**
+         * A flag that indicates whether the tracing (creating of a "trace" event) should be suppressed
+         * when a {@link IOTelSpan} ends and the span {@link IOTelSpan#isRecording | isRecording} is true.
+         * This value is also inherited by spans when they are created.
+         */
+        suppressTracing?: boolean;
+    }
+
+    /**
+     * Interface for OpenTelemetry trace operations.
+     * This interface provides span creation, context management, and trace provider operations
+     * that are common across different SDK implementations (Core, AISKU, etc.).
+     *
+     * @since 3.4.0
+     */
+    interface ITraceHost<CfgType extends IConfiguration = IConfiguration> {
+        readonly config: CfgType;
+        /**
+         * 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. By default this
+         * will use any located parent as defined by the {@link IConfiguration.traceHdrMode} configuration for each new instance created.
+         */
+        getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
+        /**
+         * Sets the current distributed trace context for this instance if available
+         */
+        setTraceCtx(newTraceCtx: IDistributedTraceContext | null | undefined): void;
+        /**
+         * Start a new span with the given name and optional parent context.
+         *
+         * Note: This method only creates and returns the span. It does not automatically
+         * set the span as the active trace context. Context management should be handled
+         * separately using setTraceCtx() if needed.
+         *
+         * @param name - The name of the span
+         * @param options - Options for creating the span (kind, attributes, startTime)
+         * @param parent - Optional parent context. If not provided, uses the current active trace context
+         * @returns A new span instance, or null if no trace provider is available
+         * @since 3.4.0
+         *
+         * @see {@link IReadableSpan} - Interface for individual spans
+         * @see {@link IOTelSpanOptions} - Configuration options for span creation
+         */
+        startSpan(name: string, options?: IOTelSpanOptions, parent?: IDistributedTraceContext): IReadableSpan | null;
+        /**
+         * Return the current active span, if no trace provider is available null will be returned
+         * but when a trace provider is available a span instance will always be returned, even if
+         * there is no active span (in which case a non-recording span will be returned).
+         * @param createNew - Optional flag to create a non-recording span if no active span exists, defaults to true.
+         * When false, returns the existing active span or null without creating a non-recording span, which can improve
+         * performance when only checking if an active span exists.
+         * @returns The current active span or null if no trace provider is available or if createNew is false and no active span exists
+         * @since 3.4.0
+         */
+        getActiveSpan(createNew?: boolean): IReadableSpan | null;
+        /**
+         * Set the current Active Span, if no trace provider is available the span will be not be set as the active span.
+         * @param span - The span to set as the active span
+         * @returns An ISpanScope instance that provides the current scope, the span will always be the span passed in
+         * even when no trace provider is available
+         * @since 3.4.0
+         */
+        setActiveSpan(span: IReadableSpan): ISpanScope;
+        /**
+         * Get the current trace provider.
+         *
+         * @returns The current trace provider, or null if none is set
+         * @since 3.4.0
+         */
+        getTraceProvider(): ITraceProvider | null;
+    }
+
+    /**
+     * A trace provider interface that enables different SKUs to provide their own
+     * span implementations while being managed by the core SDK.
+     *
+     * This follows the OpenTelemetry TraceProvider pattern, allowing the core to
+     * delegate span creation to the appropriate implementation based on the SDK variant.
+     *
+     * @since 3.4.0
+     */
+    interface ITraceProvider {
+        /**
+         * The OpenTelemetry API instance associated with this trace provider.
+         * This provides access to the tracer provider and other OpenTelemetry functionality.
+         * @since 3.4.0
+         */
+        readonly api: IOTelApi;
+        /**
+         * Creates a new span with the given name and options.
+         *
+         * @param name - The name of the span
+         * @param options - Options for creating the span (kind, attributes, startTime)
+         * @param parent - Optional parent context. If not provided, uses the current active trace context
+         * @returns A new span instance specific to this provider's implementation
+         * @since 3.4.0
+         */
+        createSpan(name: string, options?: IOTelSpanOptions, parent?: IDistributedTraceContext): IReadableSpan;
+        /**
+         * Gets the provider identifier for debugging and logging purposes.
+         * @returns A string identifying this trace provider implementation
+         * @since 3.4.0
+         */
+        getProviderId(): string;
+        /**
+         * Determines if this provider is available and ready to create spans.
+         * @returns true if the provider can create spans, false otherwise
+         * @since 3.4.0
+         */
+        isAvailable(): boolean;
+    }
+
     /**
      * An interface which provides automatic removal during unloading of the component
      */
@@ -2048,6 +3936,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
@@ -2086,6 +4044,74 @@ declare namespace ApplicationInsights {
 
     type LoggingSeverity = number | eLoggingSeverity;
 
+    /**
+     * Attribute values may be any non-nullish primitive value except an object.
+     *
+     * null or undefined attribute values are invalid and will result in undefined behavior.
+     *
+     * @since 3.4.0
+     */
+    type OTelAttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+
+    /**
+     * Defines Exception.
+     *
+     * string or an object with one of (message or name or code) and optional stack
+     *
+     * @since 3.4.0
+     */
+    type OTelException = IOTelExceptionWithCode | IOTelExceptionWithMessage | IOTelExceptionWithName | string;
+
+    /**
+     * High-resolution time represented as a tuple of [seconds, nanoseconds].
+     * This is the base type for all OpenTelemetry high-resolution time values.
+     *
+     * @remarks
+     * The first element represents seconds since Unix epoch, and the second element
+     * represents nanoseconds (0-999,999,999) within that second.
+     *
+     * @example
+     * ```typescript
+     * const hrTime: OTelHrTimeBase = [1609459200, 500000000]; // 2021-01-01 00:00:00.5 UTC
+     * ```
+     *
+     * @since 3.4.0
+     */
+    type OTelHrTimeBase = [number, number];
+
+    /**
+     * Creates an enum style object for the OTelSpanKind enum, providing the enum
+     * values as properties of the object as both string and number types.
+     * This allows for easy access to the enum values in a more readable format.
+     */
+    const OTelSpanKind: EnumValue<typeof eOTelSpanKind>;
+
+    type OTelSpanKind = number | eOTelSpanKind;
+
+    /**
+     * Union type representing all valid time input formats accepted by OpenTelemetry APIs.
+     *
+     * @remarks
+     * - `IOTelHrTime`: High-resolution time with nanosecond precision
+     * - `number`: Milliseconds since Unix epoch (JavaScript Date.now() format)
+     * - `Date`: JavaScript Date object
+     *
+     * @example
+     * ```typescript
+     * // All of these are valid time inputs:
+     * const hrTime: OTelTimeInput = [1609459200, 500000000];
+     * const msTime: OTelTimeInput = Date.now();
+     * const dateTime: OTelTimeInput = new Date();
+     *
+     * span.addEvent("event", {}, hrTime);
+     * span.addEvent("event", {}, msTime);
+     * span.addEvent("event", {}, dateTime);
+     * ```
+     *
+     * @since 3.4.0
+     */
+    type OTelTimeInput = IOTelHrTime | number | Date;
+
     /**
      * This defines the handler function for when a promise is rejected.
      * @param value - This is the value passed as part of resolving the Promise