@microsoft/applicationinsights-debugplugin-js 3.4.0-nightlybeta3.2507-22 → 3.4.0-nightlybeta3.2601-13

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

@@ -1,5 +1,5 @@
 /*
- * Microsoft.ApplicationInsights, 3.4.0-nightlybeta3.2507-22
+ * Microsoft.ApplicationInsights, 3.4.0-nightlybeta3.2601-13
  * 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,11 @@ declare namespace ApplicationInsights {
         SdkLdrUpdate = 111,
         InitPromiseException = 112,
         StatsBeatManagerException = 113,
-        StatsBeatException = 114
+        StatsBeatException = 114,
+        AttributeError = 115,
+        SpanError = 116,
+        TraceError = 117,
+        NotImplementedError = 118
     }
 
     const enum eLoggingSeverity {
@@ -264,6 +313,57 @@ 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.
@@ -308,8 +408,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.
          */
@@ -430,14 +529,13 @@ declare namespace ApplicationInsights {
          */
         flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason, cbTimeout?: number): boolean | void;
         /**
-         * Gets the current distributed trace active context for this instance
-         * @param createNew - Optional flag to create a new instance if one doesn't currently exist, defaults to true
-         */
-        getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
-        /**
-         * 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.
@@ -465,6 +563,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
@@ -529,6 +771,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
      */
@@ -555,7 +821,7 @@ declare namespace ApplicationInsights {
          * you DO NOT pass a callback function then a [IPromise](https://nevware21.github.io/ts-async/typedoc/interfaces/IPromise.html)
          * will be returned which will resolve once the flush is complete. The actual implementation of the `IPromise`
          * will be a native Promise (if supported) or the default as supplied by [ts-async library](https://github.com/nevware21/ts-async)
-         * @param async - send data asynchronously when true
+         * @param isAsync - send data asynchronously when true
          * @param callBack - if specified, notify caller when send is complete, the channel should return true to indicate to the caller that it will be called.
          * If the caller doesn't return true the caller should assume that it may never be called.
          * @param sendReason - specify the reason that you are calling "flush" defaults to ManualFlush (1) if not specified
@@ -563,9 +829,9 @@ declare namespace ApplicationInsights {
          * should assume that any provided callback will never be called, Nothing or if occurring asynchronously a
          * [IPromise](https://nevware21.github.io/ts-async/typedoc/interfaces/IPromise.html) which will be resolved once the unload is complete,
          * the [IPromise](https://nevware21.github.io/ts-async/typedoc/interfaces/IPromise.html) will only be returned when no callback is provided
-         * and async is true.
+         * and isAsync is true.
          */
-        flush?(async: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): boolean | void | IPromise<boolean>;
+        flush?(isAsync: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): boolean | void | IPromise<boolean>;
         /**
          * Get offline support
          * @returns IInternalOfflineSupport
@@ -648,7 +914,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.
          */
@@ -964,6 +1230,14 @@ declare namespace ApplicationInsights {
          * @param cookieValue - The value to set to expire the cookie
          */
         delCookie?: (name: string, cookieValue: string) => void;
+        /**
+         * Defaults to false, when true this will disable the deferral behavior that occurs when cookies are disabled,
+         * reverting to the previous behavior where cookie operations would simply return false when cookies are disabled.
+         * This is provided to maintain backward compatibility if applications depend on the previous behavior.
+         * When false (default), cookie operations are deferred until cookies are enabled, supporting consent scenarios.
+         * @since v3.3.10
+         */
+        disableCookieDefer?: boolean;
     }
 
     interface ICustomProperties {
@@ -1056,6 +1330,10 @@ 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 {
@@ -1134,8 +1412,12 @@ declare namespace ApplicationInsights {
          * 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.
+         * 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;
@@ -1173,8 +1455,8 @@ declare namespace ApplicationInsights {
         traceFlags?: number;
         /**
          * Returns the current trace state which will be used to propgate context across different services.
-         * Updating (adding / removing keys) of the trace state will modify the current context.
-         * @remarks Unlike the OpenTelemetry {@link TraceState}, this value is a mutable object, so you can
+         * 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
          */
@@ -1254,7 +1536,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;
@@ -1263,7 +1545,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;
@@ -1359,8 +1641,9 @@ declare namespace ApplicationInsights {
          * @param events - The array of events that have been discarded.
          * @param reason - The reason for discarding the events. The EventsDiscardedReason
          * constant should be used to check the different values.
+         * @param sendType - [Optional] The send type used when the events were discarded.
          */
-        eventsDiscarded?: (events: ITelemetryItem[], reason: number) => void;
+        eventsDiscarded?: (events: ITelemetryItem[], reason: number, sendType?: number) => void;
         /**
          * [Optional] A function called when the events have been requested to be sent to the sever.
          * @param sendReason - The reason why the event batch is being sent.
@@ -1428,8 +1711,9 @@ declare namespace ApplicationInsights {
          * @param events - The array of events that have been discarded by the SDK.
          * @param reason - The reason for which the SDK discarded the events. The EventsDiscardedReason
          * constant should be used to check the different values.
+         * @param sendType - [Optional] The send type used when the events were discarded.
          */
-        eventsDiscarded(events: ITelemetryItem[], reason: number): void;
+        eventsDiscarded(events: ITelemetryItem[], reason: number, sendType?: number): void;
         /**
          * [Optional] A function called when the events have been requested to be sent to the sever.
          * @param sendReason - The reason why the event batch is being sent.
@@ -1481,74 +1765,1053 @@ declare namespace ApplicationInsights {
 
     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)
+         * ```
          */
-        isAsync: boolean;
+        attributeValueLengthLimit?: number;
         /**
-         * Identifies the total inclusive time spent for this event, including the time spent for child events,
-         * this will be undefined until the event is completed
+         * 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)
+         * });
+         * ```
          */
-        time?: number;
+        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 {
         /**
-         * Identifies the exclusive time spent in for this event (not including child events),
-         * this will be undefined until the event is completed.
+         * 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
          */
-        exTime?: number;
+        traceCfg?: ITraceCfg;
         /**
-         * The Parent event that was started before this event was created
+         * 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);
+         *  }
+         * };
+         * ```
          */
-        parent?: IPerfEvent;
+        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 {
         /**
-         * The child perf events that are contained within the total time of this event.
+         * 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}`);
+         * }
+         * ```
          */
-        childEvts?: IPerfEvent[];
+        attribError?: (message: string, key: string, value: any) => void;
         /**
-         * Identifies whether this event is a child event of a parent
+         * 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}`);
+         * }
+         * ```
          */
-        isChildEvt: () => boolean;
+        spanError?: (message: string, spanName: string) => void;
         /**
-         * Get the names additional context associated with this perf event
+         * 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);
+         *   }
+         * }
+         * ```
          */
-        getCtx?: (key: string) => any;
+        debug?: (message: string) => void;
         /**
-         * Set the named additional context to be associated with this perf event, this will replace any existing value
+         * 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');
+         * }
+         * ```
          */
-        setCtx?: (key: string, value: any) => void;
+        warn?: (message: string) => void;
         /**
-         * Mark this event as completed, calculating the total execution time.
-         */
-        complete: () => 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;
+    }
+
+    /**
+     * Options for creating 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.)
+         * @param context - Optional context to use for extracting the parent span; if not provided, uses current context
+         *
+         * @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;
+    }
+
+    /** 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;
+        /**
+         * Identifies the total inclusive time spent for this event, including the time spent for child events,
+         * this will be undefined until the event is completed
+         */
+        time?: number;
+        /**
+         * Identifies the exclusive time spent in for this event (not including child events),
+         * this will be undefined until the event is completed.
+         */
+        exTime?: number;
+        /**
+         * The Parent event that was started before this event was created
+         */
+        parent?: IPerfEvent;
+        /**
+         * The child perf events that are contained within the total time of this event.
+         */
+        childEvts?: IPerfEvent[];
+        /**
+         * Identifies whether this event is a child event of a parent
+         */
+        isChildEvt: () => boolean;
+        /**
+         * Get the names additional context associated with this perf event
+         */
+        getCtx?: (key: string) => any;
+        /**
+         * Set the named additional context to be associated with this perf event, this will replace any existing value
+         */
+        setCtx?: (key: string, value: any) => void;
+        /**
+         * Mark this event as completed, calculating the total execution time.
+         */
+        complete: () => void;
     }
 
     /**
@@ -1800,7 +3063,7 @@ declare namespace ApplicationInsights {
          * });
          * ```
          */
-        then<TResult1 = T, TResult2 = never>(onResolved?: ResolvedPromiseHandler<T, TResult1>, onRejected?: RejectedPromiseHandler<TResult2>): Promise<TResult1 | TResult2>;
+        then<TResult1 = T, TResult2 = never>(onResolved?: ResolvedPromiseHandler<T, TResult1>, onRejected?: RejectedPromiseHandler<TResult2>): IPromise<TResult1 | TResult2>;
         /**
          * Attaches a callback for only the rejection of the Promise.
          * @param onRejected - The callback to execute when the Promise is rejected.
@@ -1851,7 +3114,7 @@ declare namespace ApplicationInsights {
          * // expected output: Uh-oh!
          * ```
          */
-        catch<TResult = never>(onRejected?: ((reason: any) => TResult | IPromise<TResult>) | undefined | null): Promise<T | TResult>;
+        catch<TResult = never>(onRejected?: ((reason: any) => TResult | IPromise<TResult>) | undefined | null): IPromise<T | TResult>;
         /**
          * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The
          * resolved value cannot be modified from the callback.
@@ -1881,6 +3144,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;
     }
@@ -2140,6 +3470,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): IReadableSpan;
+        /**
+         * Returns true if this {@link IDistributedTraceContext} is valid.
+         * @return true if this {@link IDistributedTraceContext} is valid.
+         */
+        isSpanContextValid(spanContext: IDistributedTraceContext): 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
      */
@@ -2267,6 +3796,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