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

package/src/JavaScriptSDK.Interfaces/ITraceParent.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+/**
+ * This interface represents the components of a W3C traceparent header
+ */
+export 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;
+}

package/tsconfig.json

@@ -9,9 +9,8 @@
     "forceConsistentCasingInFileNames": true,
     "importHelpers": true,
     "noEmitHelpers": true,
-    "skipLibCheck": true,
+    "skipLibCheck": false,
     "alwaysStrict": true,
-    "skipLibCheck": true,
     "skipDefaultLibCheck": true,
     "declaration": true,
     "declarationDir": "shared/AppInsightsCore/types",

package/types/JavaScriptSDK/BaseCore.d.ts

@@ -14,6 +14,7 @@ import { UnloadHandler } from "./UnloadHandlerContainer";
 import { ITelemetryUpdateState } from "../JavaScriptSDK.Interfaces/ITelemetryUpdateState";
 import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
 import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
+import { IDistributedTraceContext } from "../JavaScriptSDK.Interfaces/IDistributedTraceContext";
 export declare class BaseCore implements IAppInsightsCore {
     static defaultConfig: IConfiguration;
     config: IConfiguration;
@@ -103,6 +104,15 @@ export declare class BaseCore implements IAppInsightsCore {
      * @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.

package/types/JavaScriptSDK/EnvUtils.d.ts

@@ -140,3 +140,13 @@ export declare function useXDomainRequest(): boolean | undefined;
  * @returns True if supported, otherwise false
  */
 export declare function isXhrSupported(): boolean;
+/**
+ * Helper function to fetch the named meta-tag from the page.
+ * @param name
+ */
+export declare function findMetaTag(name: string): any;
+/**
+ * Helper function to fetch the named server timing value from the page response (first navigation event).
+ * @param name
+ */
+export declare function findNamedServerTiming(name: string): any;

package/types/JavaScriptSDK/TelemetryHelpers.d.ts

@@ -3,6 +3,7 @@ import { IProcessTelemetryContext, IProcessTelemetryUnloadContext } from "../Jav
 import { IAppInsightsCore } from "../JavaScriptSDK.Interfaces/IAppInsightsCore";
 import { IUnloadableComponent } from "../JavaScriptSDK.Interfaces/IUnloadableComponent";
 import { ITelemetryUnloadState } from "../JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+import { IDistributedTraceContext } from "../JavaScriptSDK.Interfaces/IDistributedTraceContext";
 export interface IPluginState {
     core?: IAppInsightsCore;
     isInitialized?: boolean;
@@ -29,3 +30,9 @@ export declare function sortPlugins<T = IPlugin>(plugins: T[]): T[];
  * @returns boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.
  */
 export declare function unloadComponents(components: any | IUnloadableComponent[], unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: () => void): void | boolean;
+/**
+ * Creates a IDistributedTraceContext which optionally also "sets" the value on a parent
+ * @param parentCtx - An optional parent distributed trace instance
+ * @returns A new IDistributedTraceContext instance that uses an internal temporary object
+ */
+export declare function createDistributedTraceContext(parentCtx?: IDistributedTraceContext): IDistributedTraceContext;

package/types/JavaScriptSDK/W3cTraceParent.d.ts

@@ -0,0 +1,59 @@
+import { ITraceParent } from "../JavaScriptSDK.Interfaces/ITraceParent";
+/**
+ * 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
+ */
+export declare function createTraceParent(traceId?: string, spanId?: string, flags?: number, version?: string): ITraceParent;
+/**
+ * Attempt to parse the provided string as a W3C TraceParent header value (https://www.w3.org/TR/trace-context/#traceparent-header)
+ *
+ * @param value
+ * @returns
+ */
+export declare function parseTraceParent(value: string): ITraceParent;
+/**
+ * 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
+ */
+export declare function isValidTraceId(value: string): boolean;
+/**
+ * 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
+ */
+export declare function isValidSpanId(value: string): boolean;
+/**
+ * Validates that the provided ITraceParent instance conforms to the currently supported specifications
+ * @param value
+ * @returns
+ */
+export declare function isValidTraceParent(value: ITraceParent): boolean;
+/**
+ * Is the parsed traceParent indicating that the trace is currently sampled.
+ * @param value - The parsed traceParent value
+ * @returns
+ */
+export declare function isSampledFlag(value: ITraceParent): boolean;
+/**
+ * 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
+ */
+export declare function formatTraceParent(value: ITraceParent): string;
+/**
+ * Helper function to fetch the passed traceparent from the page, looking for it as a meta-tag or a Server-Timing header.
+ * @returns
+ */
+export declare function findW3cTraceParent(): ITraceParent;

package/types/JavaScriptSDK.Interfaces/IAppInsightsCore.d.ts

@@ -12,6 +12,7 @@ import { ITelemetryInitializerHandler, TelemetryInitializerFunction } from "./IT
 import { ITelemetryUnloadState } from "./ITelemetryUnloadState";
 import { UnloadHandler } from "../JavaScriptSDK/UnloadHandlerContainer";
 import { SendRequestReason } from "../JavaScriptSDK.Enums/SendRequestReason";
+import { IDistributedTraceContext } from "./IDistributedTraceContext";
 export interface ILoadedPlugin<T extends IPlugin> {
     plugin: T;
     /**
@@ -120,4 +121,13 @@ export interface IAppInsightsCore extends IPerfManagerProvider {
      * @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;
 }

package/types/JavaScriptSDK.Interfaces/IDistributedTraceContext.d.ts

@@ -0,0 +1,43 @@
+export 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;
+}

package/types/JavaScriptSDK.Interfaces/ITraceParent.d.ts

@@ -0,0 +1,32 @@
+/**
+ * This interface represents the components of a W3C traceparent header
+ */
+export 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;
+}

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

@@ -21,7 +21,7 @@ export { CoreUtils, ICoreUtils, EventHelper, IEventHelper, Undefined, newGuid, p
 export { isTypeof, isUndefined, isNullOrUndefined, hasOwnProperty, isObject, isFunction, normalizeJsName, objForEachKey, strEndsWith, strStartsWith, isDate, isArray, isError, isString, isNumber, isBoolean, toISOString, arrForEach, arrIndexOf, arrMap, arrReduce, strTrim, objKeys, objDefineAccessors, dateNow, getExceptionName, throwError, strContains, isSymbol, setValue, getSetValue, isNotTruthy, isTruthy, proxyAssign, proxyFunctions, proxyFunctionAs, createClassFromInterface, optimizeObject, isNotUndefined, isNotNullOrUndefined, objFreeze, objSeal, objExtend, objToString, deepFreeze } from "./JavaScriptSDK/HelperFuncs";
 export { EnumValue, createEnumStyle, EnumMap, createEnumMap, createValueMap } from "./JavaScriptSDK.Enums/EnumHelperFuncs";
 export { attachEvent, detachEvent, addEventHandler, addEventListeners, addPageUnloadEventListener, addPageHideEventListener, addPageShowEventListener, removeEventHandler, removeEventListeners, removePageUnloadEventListener, removePageHideEventListener, removePageShowEventListener, eventOn, eventOff, mergeEvtNamespace, _IRegisteredEvents, __getRegisteredEvents } from "./JavaScriptSDK/EventHelpers";
-export { getGlobalInst, hasWindow, getWindow, hasDocument, getDocument, getCrypto, getMsCrypto, hasNavigator, getNavigator, hasHistory, getHistory, getLocation, getPerformance, hasJSON, getJSON, isReactNative, getConsole, dumpObj, isIE, getIEVersion, isSafari, setEnableEnvMocks, isBeaconsSupported, isFetchSupported, useXDomainRequest, isXhrSupported } from "./JavaScriptSDK/EnvUtils";
+export { getGlobalInst, hasWindow, getWindow, hasDocument, getDocument, getCrypto, getMsCrypto, hasNavigator, getNavigator, hasHistory, getHistory, getLocation, getPerformance, hasJSON, getJSON, isReactNative, getConsole, dumpObj, isIE, getIEVersion, isSafari, setEnableEnvMocks, isBeaconsSupported, isFetchSupported, useXDomainRequest, isXhrSupported, findMetaTag, findNamedServerTiming } from "./JavaScriptSDK/EnvUtils";
 export { getGlobal, objCreateFn as objCreate, strShimPrototype as strPrototype, strShimFunction as strFunction, strShimUndefined as strUndefined, strShimObject as strObject } from "@microsoft/applicationinsights-shims";
 export { NotificationManager } from "./JavaScriptSDK/NotificationManager";
 export { INotificationManager } from "./JavaScriptSDK.Interfaces/INotificationManager";
@@ -42,3 +42,6 @@ export { createUniqueNamespace } from "./JavaScriptSDK/DataCacheHelper";
 export { UnloadHandler, IUnloadHandlerContainer, createUnloadHandlerContainer } from "./JavaScriptSDK/UnloadHandlerContainer";
 export { ITelemetryUpdateState } from "./JavaScriptSDK.Interfaces/ITelemetryUpdateState";
 export { ITelemetryUnloadState } from "./JavaScriptSDK.Interfaces/ITelemetryUnloadState";
+export { IDistributedTraceContext } from "./JavaScriptSDK.Interfaces/IDistributedTraceContext";
+export { ITraceParent } from "./JavaScriptSDK.Interfaces/ITraceParent";
+export { createTraceParent, parseTraceParent, isValidTraceId, isValidSpanId, isValidTraceParent, isSampledFlag, formatTraceParent, findW3cTraceParent } from "./JavaScriptSDK/W3cTraceParent";

package/types/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.23.2"
+      "packageVersion": "7.24.2"
     }
   ]
 }