@microsoft/applicationinsights-core-js 2.8.4-nightly.2205-07 → 2.8.4-nightly.2205-10

package/dist/applicationinsights-core-js.api.md

@@ -82,6 +82,7 @@ export class BaseCore implements IAppInsightsCore {
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
     // (undocumented)
     getProcessTelContext(): IProcessTelemetryContext;
+    getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
     // (undocumented)
     getTransmissionControls(): IChannelControls[][];
     // (undocumented)
@@ -97,6 +98,7 @@ export class BaseCore implements IAppInsightsCore {
     setCookieMgr(cookieMgr: ICookieMgr): void;
     // (undocumented)
     setPerfMgr(perfMgr: IPerfManager): void;
+    setTraceCtx(newTracectx: IDistributedTraceContext): void;
     stopPollingInternalLogs(): void;
     // (undocumented)
     track(telemetryItem: ITelemetryItem): void;
@@ -157,6 +159,9 @@ export function createEnumStyle<E>(values: {
 // @public
 export function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain | null, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext;
 
+// @public
+export function createTraceParent(traceId?: string, spanId?: string, flags?: number, version?: string): ITraceParent;
+
 // @public (undocumented)
 export function createUniqueNamespace(name: string, includeVersion?: boolean): string;
 
@@ -420,6 +425,18 @@ export const EventsDiscardedReason: EnumValue<typeof eEventsDiscardedReason>;
 // @public (undocumented)
 export type EventsDiscardedReason = number | eEventsDiscardedReason;
 
+// @public
+export function findMetaTag(name: string): any;
+
+// @public
+export function findNamedServerTiming(name: string): any;
+
+// @public
+export function findW3cTraceParent(): ITraceParent;
+
+// @public
+export function formatTraceParent(value: ITraceParent): string;
+
 // @public
 export function generateW3CId(): string;
 
@@ -521,6 +538,7 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     getNotifyMgr(): INotificationManager;
     getPlugin<T extends IPlugin = IPlugin>(pluginIdentifier: string): ILoadedPlugin<T>;
     getProcessTelContext(): IProcessTelemetryContext;
+    getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
     // (undocumented)
     getTransmissionControls(): IChannelControls[][];
     // (undocumented)
@@ -532,6 +550,7 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
     pollInternalLogs?(eventName?: string): number;
     removeNotificationListener?(listener: INotificationListener): void;
     setCookieMgr(cookieMgr: ICookieMgr): void;
+    setTraceCtx(newTraceCtx: IDistributedTraceContext | null | undefined): void;
     // (undocumented)
     stopPollingInternalLogs?(): void;
     // (undocumented)
@@ -694,6 +713,18 @@ export interface IDiagnosticLogger {
     warnToConsole(message: string): void;
 }
 
+// @public (undocumented)
+export interface IDistributedTraceContext {
+    getName(): string;
+    getSpanId(): string;
+    getTraceFlags(): number | undefined;
+    getTraceId(): string;
+    setName(pageName: string): void;
+    setSpanId(newValue: string): void;
+    setTraceFlags(newValue?: number): void;
+    setTraceId(newValue: string): void;
+}
+
 // @public (undocumented)
 export interface IEventHelper {
     Attach: (obj: any, eventNameWithoutOn: string, handlerRef: any) => boolean;
@@ -926,6 +957,9 @@ export function isReactNative(): boolean;
 // @public (undocumented)
 export function isSafari(userAgentStr?: string): boolean;
 
+// @public
+export function isSampledFlag(value: ITraceParent): boolean;
+
 // @public
 export function isString(value: any): value is string;
 
@@ -941,6 +975,15 @@ export function isTypeof(value: any, theType: string): boolean;
 // @public (undocumented)
 export function isUndefined(value: any): value is undefined;
 
+// @public
+export function isValidSpanId(value: string): boolean;
+
+// @public
+export function isValidTraceId(value: string): boolean;
+
+// @public
+export function isValidTraceParent(value: ITraceParent): boolean;
+
 // @public
 export function isXhrSupported(): boolean;
 
@@ -1004,6 +1047,14 @@ export interface ITelemetryUpdateState {
     removed?: IPlugin[];
 }
 
+// @public
+export interface ITraceParent {
+    spanId: string;
+    traceFlags: number;
+    traceId: string;
+    version: string;
+}
+
 // @public (undocumented)
 export interface IUnloadableComponent {
     _doUnload?: (unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void) => void | boolean;
@@ -1092,6 +1143,9 @@ export function objToString(obj: any): any;
 // @public
 export function optimizeObject<T>(theObject: T): T;
 
+// @public
+export function parseTraceParent(value: string): ITraceParent;
+
 // @public (undocumented)
 export class PerfEvent implements IPerfEvent {
     constructor(name: string, payloadDetails: () => any, isAsync: boolean);

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

@@ -1,5 +1,5 @@
 /*
- * Microsoft Application Insights Core Javascript SDK, 2.8.4-nightly.2205-07
+ * Microsoft Application Insights Core Javascript SDK, 2.8.4-nightly.2205-10
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -230,6 +230,15 @@ declare namespace ApplicationInsights {
          * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
          */
         flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason): void;
+        /**
+         * Gets the current distributed trace context for this instance if available
+         * @param createNew - Optional flag to create a new instance if one doesn't currently exist, defaults to true
+         */
+        getTraceCtx(createNew?: boolean): IDistributedTraceContext | null;
+        /**
+         * Sets the current distributed trace context for this instance if available
+         */
+        setTraceCtx(newTracectx: IDistributedTraceContext): void;
         protected releaseQueue(): void;
         /**
          * Hook for Core extensions to allow them to update their own configuration before updating all of the plugins.
@@ -383,6 +392,16 @@ declare namespace ApplicationInsights {
      */
     function createProcessTelemetryContext(telemetryChain: ITelemetryPluginChain | null, config: IConfiguration, core: IAppInsightsCore, startAt?: IPlugin): IProcessTelemetryContext;
 
+    /**
+     * Create a new ITraceParent instance using the provided values.
+     * @param traceId - The traceId to use, when invalid a new random W3C id will be generated.
+     * @param spanId - The parent/span id to use, a new random value will be generated if it is invalid.
+     * @param flags - The traceFlags to use, defaults to zero (0) if not supplied or invalid
+     * @param version - The version to used, defaults to version "01" if not supplied or invalid.
+     * @returns
+     */
+    function createTraceParent(traceId?: string, spanId?: string, flags?: number, version?: string): ITraceParent;
+
     function createUniqueNamespace(name: string, includeVersion?: boolean): string;
 
     function createUnloadHandlerContainer(): {
@@ -677,6 +696,34 @@ declare namespace ApplicationInsights {
 
     type EventsDiscardedReason = number | eEventsDiscardedReason;
 
+    /**
+     * Helper function to fetch the named meta-tag from the page.
+     * @param name
+     */
+    function findMetaTag(name: string): any;
+
+    /**
+     * Helper function to fetch the named server timing value from the page response (first navigation event).
+     * @param name
+     */
+    function findNamedServerTiming(name: string): any;
+
+    /**
+     * Helper function to fetch the passed traceparent from the page, looking for it as a meta-tag or a Server-Timing header.
+     * @returns
+     */
+    function findW3cTraceParent(): ITraceParent;
+
+    /**
+     * Format the ITraceParent value as a string using the supported and know version formats.
+     * So even if the passed traceParent is a later version the string value returned from this
+     * function will convert it to only the known version formats.
+     * This currently only supports version "00" and invalid "ff"
+     * @param value - The parsed traceParent value
+     * @returns
+     */
+    function formatTraceParent(value: ITraceParent): string;
+
     /**
      * generate W3C trace id
      */
@@ -936,6 +983,15 @@ declare namespace ApplicationInsights {
          * @returns - true if the callback will be return after the flush is complete otherwise the caller should assume that any provided callback will never be called
          */
         flush(isAsync?: boolean, callBack?: (flushComplete?: boolean) => void, sendReason?: SendRequestReason, 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
+         */
+        setTraceCtx(newTraceCtx: IDistributedTraceContext | null | undefined): void;
     }
 
     interface IBaseProcessingContext {
@@ -1510,6 +1566,50 @@ declare namespace ApplicationInsights {
         logInternalMessage?(severity: LoggingSeverity, message: _InternalLogMessage): void;
     }
 
+    interface IDistributedTraceContext {
+        /**
+         * Returns the current name of the page
+         */
+        getName(): string;
+        /**
+         * Sets the current name of the page
+         * @param pageName
+         */
+        setName(pageName: string): void;
+        /**
+         * Returns the unique identifier for a trace. All requests / spans from the same trace share the same traceId.
+         * Must be read from incoming headers or generated according to the W3C TraceContext specification,
+         * in a hex representation of 16-byte array. A.k.a. trace-id, TraceID or Distributed TraceID
+         */
+        getTraceId(): string;
+        /**
+         * 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
+         */
+        setTraceId(newValue: string): void;
+        /**
+         * 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
+         */
+        getSpanId(): string;
+        /**
+         * 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
+         */
+        setSpanId(newValue: string): void;
+        /**
+         * An integer representation of the W3C TraceContext trace-flags.
+         */
+        getTraceFlags(): number | undefined;
+        /**
+         * https://www.w3.org/TR/trace-context/#trace-flags
+         * @param newValue
+         */
+        setTraceFlags(newValue?: number): void;
+    }
+
     interface IEventHelper {
         /**
          * Binds the specified function to an event, so that the function gets called whenever the event fires on the object
@@ -2059,6 +2159,13 @@ declare namespace ApplicationInsights {
 
     function isSafari(userAgentStr?: string): boolean;
 
+    /**
+     * Is the parsed traceParent indicating that the trace is currently sampled.
+     * @param value - The parsed traceParent value
+     * @returns
+     */
+    function isSampledFlag(value: ITraceParent): boolean;
+
     /**
      * Checks if the type of value is a string.
      * @param {any} value - Value to be checked.
@@ -2080,6 +2187,31 @@ declare namespace ApplicationInsights {
 
     function isUndefined(value: any): value is undefined;
 
+    /**
+     * Is the provided W3c span id (aka. parent id) a valid string representation, it must be a 16-character
+     * string of lowercase hexadecimal characters, for example, 00f067aa0ba902b7.
+     * If all characters are zero (0000000000000000) this is considered an invalid value.
+     * @param value - The W3c span id to be validated
+     * @returns true if valid otherwise false
+     */
+    function isValidSpanId(value: string): boolean;
+
+    /**
+     * Is the provided W3c Trace Id a valid string representation, it must be a 32-character string
+     * of lowercase hexadecimal characters for example, 4bf92f3577b34da6a3ce929d0e0e4736.
+     * If all characters as zero (00000000000000000000000000000000) it will be considered an invalid value.
+     * @param value - The W3c trace Id to be validated
+     * @returns true if valid otherwise false
+     */
+    function isValidTraceId(value: string): boolean;
+
+    /**
+     * Validates that the provided ITraceParent instance conforms to the currently supported specifications
+     * @param value
+     * @returns
+     */
+    function isValidTraceParent(value: ITraceParent): boolean;
+
     /**
      * Checks if XMLHttpRequest is supported
      * @returns True if supported, otherwise false
@@ -2229,6 +2361,39 @@ declare namespace ApplicationInsights {
         removed?: IPlugin[];
     }
 
+    /**
+     * This interface represents the components of a W3C traceparent header
+     */
+    interface ITraceParent {
+        /**
+         * The version of the definition, this MUST be a string with a length of 2 and only contain lowercase
+         * hexadecimal characters. A value of 'ff' is considered to be an invalid version.
+         */
+        version: string;
+        /**
+         * This is the ID of the whole trace forest and is used to uniquely identify a distributed trace
+         * through a system. It is represented as a 32-character string of lowercase hexadecimal characters,
+         * for example, 4bf92f3577b34da6a3ce929d0e0e4736.
+         * All characters as zero (00000000000000000000000000000000) is considered an invalid value.
+         */
+        traceId: string;
+        /**
+         * This is the ID of the current request as known by the caller (in some tracing systems, this is also
+         * known as the parent-id, where a span is the execution of a client request). It is represented as an
+         * 16-character string of lowercase hexadecimal characters, for example, 00f067aa0ba902b7.
+         * All bytes as zero (0000000000000000) is considered an invalid value.
+         */
+        spanId: string;
+        /**
+         * An 8-bit value of flags that controls tracing such as sampling, trace level, etc. These flags are
+         * recommendations given by the caller rather than strict rules to follow.
+         * As this is a bit field, you cannot interpret flags by decoding the hex value and looking at the resulting
+         * number. For example, a flag 00000001 could be encoded as 01 in hex, or 09 in hex if present with the flag
+         * 00001000. A common mistake in bit fields is forgetting to mask when interpreting flags.
+         */
+        traceFlags: number;
+    }
+
     interface IUnloadableComponent {
         /**
          * Teardown / Unload hook to allow implementations to perform some additional unload operations before the BaseTelemetryPlugin
@@ -2407,6 +2572,14 @@ declare namespace ApplicationInsights {
      */
     function optimizeObject<T>(theObject: T): T;
 
+    /**
+     * Attempt to parse the provided string as a W3C TraceParent header value (https://www.w3.org/TR/trace-context/#traceparent-header)
+     *
+     * @param value
+     * @returns
+     */
+    function parseTraceParent(value: string): ITraceParent;
+
     class PerfEvent implements IPerfEvent {
         static ParentContextKey: string;
         static ChildrenContextKey: string;