microsoft/ApplicationInsights-JS 3.4.0-beta

3.4.0-beta

Repository: microsoft/ApplicationInsights-JS

Tag: 3.4.0-beta

Published: 2026-02-23T22:55:38Z

Prerelease: no

Release notes:

Significant Changes

• AppInsightsCommon Merged into AppInsightsCore: The @microsoft/applicationinsights-common package has been merged into @microsoft/applicationinsights-core-js to simplify dependency management and improve tree-shaking capabilities.
• All exports previously in applicationinsights-common are now available from applicationinsights-core-js
• The applicationinsights-common package continues to work as a compatibility layer (re-exports from Core)
• No breaking changes to existing APIs
• See the [Migration Guide](docs/upgrade/MergeCommonToCore.md) for details on updating your imports
• Timeline: The Common package will be deprecated and eventually removed in version 4.0.0

• W3C Trace State Support: Added full support for managing W3C Trace State and sending headers in distributed tracing, including new distributed tracing modes AI_AND_W3C_TRACE and W3C_TRACE that enable the `tracestate` header to be sent with requests when trace state information is available, the existing states will continue to not send the header.

• New Distributed Tracing Modes: Added new eDistributedTracingModes enum values:
• AI_AND_W3C_TRACE (17): Sends Application Insights headers + W3C traceparent + W3C tracestate headers (if state value is present)
• W3C_TRACE (18): Sends only W3C traceparent + W3C tracestate headers (if state value is present)

• Enhanced Distributed Tracing: Refactored the distributed tracing implementation to provide better support for the W3C Trace Context specification and prepare for future OpenTelemetry Span-style API integration.

• New W3C TraceState API: Introduced the IW3cTraceState interface that provides a mutable, ordered list of key/value pairs for trace state information with proper parent-child relationships.

• OpenTelemetry Integration Preparation: Added foundational OpenTelemetry interfaces (IOTelSpanContext, IOTelTraceState) to provide OpenTelemetry API compatibility.

• Additional Configuration: Added new configuration properties for W3C trace state support:
• traceHdrMode: Controls if the SDK should look for the traceparent and/or tracestate values from service timing headers or meta tags from the initial page load (in IConfiguration)
• Enhanced distributedTracingMode property to support the new W3C trace state modes (in ICorrelationConfig)

• Dependencies Extension: The dependency tracking extension now includes additional logic for W3C trace state handling, which may affect custom dependency listeners or initializers. The following interfaces and functions have been enhanced with W3C trace state support:
• IDependencyListenerDetails interface now also includes a readonly traceState along with the previous traceId, spanId, traceFlags properties
• addDependencyListener() function now provides access to W3C trace state information through the enhanced details object
• addDependencyInitializer() function continues to work with existing dependency telemetry processing
• Custom dependency listeners can now access and modify W3C trace state information before requests are sent

Breaking Changes

The following is a list of known breaking changes for anyone attempting to implement the interfaces, for end-users / consumers of the existing interface this is considered to be only a potential breaking change as the existing functions are still provided and provide the same level of functionality. The breaking nature of these changes is for anyone attempting to provide their own implementation of these changes.

Interface Changes

• The IDistributedTraceContext interface has been significantly expanded to include W3C trace state management capabilities, which may affect custom telemetry processors that interact with distributed tracing context.
• Added additional "required" property accessors which update ONLY the current trace context instance and DO NOT update any parent context instances (pageName, traceId, spanId and traceFlags).
• The previous set functions continue to also update (replace) any parent context values for existing backward compatability, but have been marked as depracted and will be removed in a future release due to their side-effects of overwriting the parent values.

Potential Breaking Changes

• Class Removal: The TelemetryTrace class has been removed and is no longer exported as part of the distributed tracing refactoring, with its functionality integrated into the new W3C trace state implementation.
• The properties telemetryTrace is now a complete adpater to the existing core.getTraceCtx() value and as such is now marked as deprecated and will be removed in a future release.
• The value of the appInsights.context.telemetryTrace is no longer an instance of this removed class.

• Trace Context Initialization: Due to the distributed tracing refactoring, the core instance and SDK will now always have a valid traceId available through core.getTraceCtx(). The traceId will be either a newly generated random value or inherited from any detected parent trace context. This ensures consistent trace context availability but may affect applications that previously relied on the absence of a traceId to determine if distributed tracing was active.

• Dependencies Extension - ajaxRecord Class Removal: The internal ajaxRecord class has been removed and is no longer exported from the dependencies extension (@microsoft/applicationinsights-dependencies-js). This class was previously used internally for AJAX request tracking and was referenced in the IInstrumentationRequirements.includeCorrelationHeaders() function signature. Important: The previous exporting of the ajaxRecord class was unintentional and was never meant to be part of the public API - it was an internal implementation detail that inadvertently became accessible to external code.
• Previous Signature: includeCorrelationHeaders(ajaxData: ajaxRecord, input?: Request | string, init?: RequestInit, xhr?: XMLHttpRequestInstrumented): any
• New Signature: includeCorrelationHeaders(ajaxData: IAjaxRecordData, input?: Request | string, init?: RequestInit, xhr?: XMLHttpRequestInstrumented): any
• New Interface: The...