@microsoft/applicationinsights-common 2.8.0-nightly.2204-06 → 2.8.0-nightly.2204-07

package/dist/applicationinsights-common.api.md

@@ -9,7 +9,6 @@ import { EnumValue } from '@microsoft/applicationinsights-core-js';
 import { IChannelControls } from '@microsoft/applicationinsights-core-js';
 import { IConfiguration } from '@microsoft/applicationinsights-core-js';
 import { ICookieMgr } from '@microsoft/applicationinsights-core-js';
-import { ICookieMgrConfig } from '@microsoft/applicationinsights-core-js';
 import { ICustomProperties } from '@microsoft/applicationinsights-core-js';
 import { IDiagnosticLogger } from '@microsoft/applicationinsights-core-js';
 import { IPlugin } from '@microsoft/applicationinsights-core-js';
@@ -57,6 +56,16 @@ export const CorrelationIdHelper: ICorrelationIdHelper;
 // @public (undocumented)
 export function createDomEvent(eventName: string): Event;
 
+// @public
+export function createTelemetryItem<T>(item: T, baseType: string, envelopeName: string, logger: IDiagnosticLogger, customProperties?: {
+    [key: string]: any;
+}, systemProperties?: {
+    [key: string]: any;
+}): ITelemetryItem;
+
+// @public
+export function createTraceParent(traceId?: string, spanId?: string, flags?: number, version?: string): ITraceParent;
+
 // @public (undocumented)
 export let CtxTagKeys: ContextTagKeys;
 
@@ -131,11 +140,7 @@ export const DEFAULT_BREEZE_ENDPOINT = "https://dc.services.visualstudio.com";
 export const DisabledPropertyName: string;
 
 // @public (undocumented)
-export const DistributedTracingModes: EnumValue<    {
-AI: number;
-AI_AND_W3C: number;
-W3C: number;
-}>;
+export const DistributedTracingModes: EnumValue<typeof eDistributedTracingModes>;
 
 // @public (undocumented)
 export type DistributedTracingModes = number | eDistributedTracingModes;
@@ -164,6 +169,42 @@ export class Envelope implements IEnvelope {
     ver: number;
 }
 
+// @public (undocumented)
+export const enum eRequestHeaders {
+    // (undocumented)
+    requestContextAppIdFormat = 2,
+    // (undocumented)
+    requestContextHeader = 0,
+    // (undocumented)
+    requestContextHeaderLowerCase = 8,
+    // (undocumented)
+    requestContextTargetKey = 1,
+    // (undocumented)
+    requestIdHeader = 3,
+    // (undocumented)
+    sdkContextHeader = 6,
+    // (undocumented)
+    sdkContextHeaderAppIdRequest = 7,
+    // (undocumented)
+    traceParentHeader = 4,
+    // (undocumented)
+    traceStateHeader = 5
+}
+
+// @public
+export const enum eSeverityLevel {
+    // (undocumented)
+    Critical = 4,
+    // (undocumented)
+    Error = 3,
+    // (undocumented)
+    Information = 1,
+    // (undocumented)
+    Verbose = 0,
+    // (undocumented)
+    Warning = 2
+}
+
 // Warning: (ae-forgotten-export) The symbol "IEventData" needs to be exported by the entry point applicationinsights-common.d.ts
 //
 // @public (undocumented)
@@ -259,6 +300,12 @@ export const enum FieldType {
     Required = 1
 }
 
+// @public
+export function findW3cTraceParent(): ITraceParent;
+
+// @public
+export function formatTraceParent(value: ITraceParent): string;
+
 // @public (undocumented)
 export function getExtensionByName(extensions: IPlugin[], identifier: string): IPlugin | null;
 
@@ -341,7 +388,6 @@ export interface IConfig {
     autoUnhandledPromiseInstrumented?: boolean;
     convertUndefined?: any;
     cookieDomain?: string;
-    cookieMgrCfg?: ICookieMgrConfig;
     cookiePath?: string;
     // (undocumented)
     correlationHeaderDomains?: string[];
@@ -786,6 +832,18 @@ export interface ISession {
 // @public (undocumented)
 export function isInternalApplicationInsightsEndpoint(endpointUrl: string): boolean;
 
+// @public
+export function isSampledFlag(value: ITraceParent): boolean;
+
+// @public
+export function isValidSpanId(value: string): boolean;
+
+// @public
+export function isValidTraceId(value: string): boolean;
+
+// @public
+export function isValidTraceParent(value: ITraceParent): boolean;
+
 // @public (undocumented)
 export interface ITelemetryContext {
     appId: () => string;
@@ -809,6 +867,14 @@ export interface ITelemetryTrace {
     traceState?: ITraceState;
 }
 
+// @public
+export interface ITraceParent {
+    spanId: string;
+    traceFlags: number;
+    traceId: string;
+    version: string;
+}
+
 // @public (undocumented)
 export interface ITraceState {
 }
@@ -1023,6 +1089,9 @@ export class PageViewPerformance implements IPageViewPerfData, ISerializable {
 // @public (undocumented)
 export function parseConnectionString(connectionString?: string): ConnectionString;
 
+// @public
+export function parseTraceParent(value: string): ITraceParent;
+
 // @public (undocumented)
 export const ProcessLegacy = "ProcessLegacy";
 
@@ -1076,24 +1145,35 @@ export class RemoteDependencyData implements IRemoteDependencyData, ISerializabl
 }
 
 // @public (undocumented)
-export const RequestHeaders: IRequestHeaders;
+export const RequestHeaders: IRequestHeaders & {
+    requestContextHeader: "Request-Context";
+    requestContextTargetKey: "appId";
+    requestContextAppIdFormat: "appId=cid-v1:";
+    requestIdHeader: "Request-Id";
+    traceParentHeader: "traceparent";
+    traceStateHeader: "tracestate";
+    sdkContextHeader: "Sdk-Context";
+    sdkContextHeaderAppIdRequest: "appId";
+    requestContextHeaderLowerCase: "request-context";
+    0: "Request-Context";
+    1: "appId";
+    2: "appId=cid-v1:";
+    3: "Request-Id";
+    4: "traceparent";
+    5: "tracestate";
+    6: "Sdk-Context";
+    7: "appId";
+    8: "request-context";
+};
 
 // @public (undocumented)
 export const SampleRate = "sampleRate";
 
 // @public
-export enum SeverityLevel {
-    // (undocumented)
-    Critical = 4,
-    // (undocumented)
-    Error = 3,
-    // (undocumented)
-    Information = 1,
-    // (undocumented)
-    Verbose = 0,
-    // (undocumented)
-    Warning = 2
-}
+export const SeverityLevel: EnumValue<typeof eSeverityLevel>;
+
+// @public (undocumented)
+export type SeverityLevel = number | eSeverityLevel;
 
 // @public (undocumented)
 export function stringToBoolOrDefault(str: any, defaultValue?: boolean): boolean;
@@ -1103,11 +1183,7 @@ export const strNotSpecified = "not_specified";
 
 // @public (undocumented)
 export class TelemetryItemCreator {
-    static create<T>(item: T, baseType: string, envelopeName: string, logger: IDiagnosticLogger, customProperties?: {
-        [key: string]: any;
-    }, systemProperties?: {
-        [key: string]: any;
-    }): ITelemetryItem;
+    static create: typeof createTelemetryItem;
 }
 
 // Warning: (ae-forgotten-export) The symbol "IMessageData" needs to be exported by the entry point applicationinsights-common.d.ts

package/dist/applicationinsights-common.d.ts

@@ -1,5 +1,5 @@
 /*
- * Microsoft Application Insights Common JavaScript Library, 2.8.0-nightly.2204-06
+ * Microsoft Application Insights Common JavaScript Library, 2.8.0-nightly.2204-07
  * Copyright (c) Microsoft and contributors. All rights reserved.
  *
  * Microsoft Application Insights Team
@@ -12,7 +12,6 @@ declare namespace ApplicationInsights {
     import { IChannelControls } from '@microsoft/applicationinsights-core-js';
     import { IConfiguration } from '@microsoft/applicationinsights-core-js';
     import { ICookieMgr } from '@microsoft/applicationinsights-core-js';
-    import { ICookieMgrConfig } from '@microsoft/applicationinsights-core-js';
     import { ICustomProperties } from '@microsoft/applicationinsights-core-js';
     import { IDiagnosticLogger } from '@microsoft/applicationinsights-core-js';
     import { IPlugin } from '@microsoft/applicationinsights-core-js';
@@ -71,6 +70,31 @@ declare namespace ApplicationInsights {
 
     function createDomEvent(eventName: string): Event;
 
+    /**
+     * Create a telemetry item that the 1DS channel understands
+     * @param item domain specific properties; part B
+     * @param baseType telemetry item type. ie PageViewData
+     * @param envelopeName name of the envelope. ie Microsoft.ApplicationInsights.<instrumentation key>.PageView
+     * @param customProperties user defined custom properties; part C
+     * @param systemProperties system properties that are added to the context; part A
+     * @returns ITelemetryItem that is sent to channel
+     */
+    function createTelemetryItem<T>(item: T, baseType: string, envelopeName: string, logger: IDiagnosticLogger, customProperties?: {
+        [key: string]: any;
+    }, systemProperties?: {
+        [key: string]: any;
+    }): ITelemetryItem;
+
+    /**
+     * 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;
+
     let CtxTagKeys: ContextTagKeys;
 
     class Data<TDomain> implements AIData<TDomain>, ISerializable {
@@ -222,11 +246,7 @@ declare namespace ApplicationInsights {
      */
     const DisabledPropertyName: string;
 
-    const DistributedTracingModes: EnumValue<    {
-    AI: number;
-    AI_AND_W3C: number;
-    W3C: number;
-    }>;
+    const DistributedTracingModes: EnumValue<typeof eDistributedTracingModes>;
 
     type DistributedTracingModes = number | eDistributedTracingModes;
 
@@ -290,6 +310,29 @@ declare namespace ApplicationInsights {
         constructor(logger: IDiagnosticLogger, data: AIBase, name: string);
     }
 
+    const enum eRequestHeaders {
+        requestContextHeader = 0,
+        requestContextTargetKey = 1,
+        requestContextAppIdFormat = 2,
+        requestIdHeader = 3,
+        traceParentHeader = 4,
+        traceStateHeader = 5,
+        sdkContextHeader = 6,
+        sdkContextHeaderAppIdRequest = 7,
+        requestContextHeaderLowerCase = 8
+    }
+
+    /**
+     * Defines the level of severity for the event.
+     */
+    const enum eSeverityLevel {
+        Verbose = 0,
+        Information = 1,
+        Warning = 2,
+        Error = 3,
+        Critical = 4
+    }
+
     class Event_2 implements IEventData, ISerializable {
         static envelopeType: string;
         static dataType: string;
@@ -397,12 +440,28 @@ declare namespace ApplicationInsights {
         Hidden = 4
     }
 
+    /**
+     * 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;
+
     /**
      * Formats the provided errorObj for display and reporting, it may be a String, Object, integer or undefined depending on the browser.
      * @param errorObj The supplied errorObj
      */
     function _formatErrorCode(errorObj: any): any;
 
+    /**
+     * 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;
+
     function getExtensionByName(extensions: IPlugin[], identifier: string): IPlugin | null;
 
     const HttpMethod = "http.method";
@@ -653,7 +712,7 @@ declare namespace ApplicationInsights {
          */
         enableSessionStorageBuffer?: boolean;
         /**
-         * @deprecated Use either disableCookiesUsage or specify a cookieMgrCfg with the enabled value set.
+         * @deprecated Use either disableCookiesUsage or specify a cookieCfg with the enabled value set.
          * If true, the SDK will not store or read any data from cookies. Default is false. As this field is being deprecated, when both
          * isCookieUseDisabled and disableCookiesUsage are used disableCookiesUsage will take precedent.
          * @defaultValue false
@@ -661,7 +720,7 @@ declare namespace ApplicationInsights {
         isCookieUseDisabled?: boolean;
         /**
          * If true, the SDK will not store or read any data from cookies. Default is false.
-         * If you have also specified a cookieMgrCfg then enabled property (if specified) will take precedent over this value.
+         * If you have also specified a cookieCfg then enabled property (if specified) will take precedent over this value.
          * @defaultValue false
          */
         disableCookiesUsage?: boolean;
@@ -675,12 +734,6 @@ declare namespace ApplicationInsights {
          * @defaultValue ""
          */
         cookiePath?: string;
-        /**
-         * [Optional] A Cookie Manager configuration which includes hooks to allow interception of the get, set and delete cookie
-         * operations. If this configuration is specified any specified enabled and domain properties will take precedence over the
-         * cookieDomain and disableCookiesUsage values.
-         */
-        cookieMgrCfg?: ICookieMgrConfig;
         /**
          * Default false. If false, retry on 206 (partial success), 408 (timeout), 429 (too many requests), 500 (internal server error), 503 (service unavailable), and 0 (offline, only if detected)
          * @description
@@ -1839,6 +1892,13 @@ declare namespace ApplicationInsights {
 
     function isInternalApplicationInsightsEndpoint(endpointUrl: 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;
+
     interface IStackDetails {
         src: string;
         obj: string[];
@@ -1870,6 +1930,31 @@ declare namespace ApplicationInsights {
         line: number;
     }
 
+    /**
+     * 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;
+
     interface ITelemetryContext {
         /**
          * The object describing a component tracked by this object.
@@ -1936,6 +2021,39 @@ declare namespace ApplicationInsights {
         name?: string;
     }
 
+    /**
+     * 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 ITraceState {
     }
 
@@ -2372,6 +2490,14 @@ declare namespace ApplicationInsights {
 
     function parseConnectionString(connectionString?: string): ConnectionString;
 
+    /**
+     * 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;
+
     const ProcessLegacy = "ProcessLegacy";
 
     const PropertiesPluginIdentifier = "AppInsightsPropertiesPlugin";
@@ -2452,20 +2578,35 @@ declare namespace ApplicationInsights {
         constructor(logger: IDiagnosticLogger, id: string, absoluteUrl: string, commandName: string, value: number, success: boolean, resultCode: number, method?: string, requestAPI?: string, correlationContext?: string, properties?: Object, measurements?: Object);
     }
 
-    const RequestHeaders: IRequestHeaders;
+    const RequestHeaders: IRequestHeaders & {
+        requestContextHeader: "Request-Context";
+        requestContextTargetKey: "appId";
+        requestContextAppIdFormat: "appId=cid-v1:";
+        requestIdHeader: "Request-Id";
+        traceParentHeader: "traceparent";
+        traceStateHeader: "tracestate";
+        sdkContextHeader: "Sdk-Context";
+        sdkContextHeaderAppIdRequest: "appId";
+        requestContextHeaderLowerCase: "request-context";
+        0: "Request-Context";
+        1: "appId";
+        2: "appId=cid-v1:";
+        3: "Request-Id";
+        4: "traceparent";
+        5: "tracestate";
+        6: "Sdk-Context";
+        7: "appId";
+        8: "request-context";
+    };
 
     const SampleRate = "sampleRate";
 
     /**
      * Defines the level of severity for the event.
      */
-    enum SeverityLevel {
-        Verbose = 0,
-        Information = 1,
-        Warning = 2,
-        Error = 3,
-        Critical = 4
-    }
+    const SeverityLevel: EnumValue<typeof eSeverityLevel>;
+
+    type SeverityLevel = number | eSeverityLevel;
 
     function stringToBoolOrDefault(str: any, defaultValue?: boolean): boolean;
 
@@ -2481,11 +2622,7 @@ declare namespace ApplicationInsights {
          * @param systemProperties system properties that are added to the context; part A
          * @returns ITelemetryItem that is sent to channel
          */
-        static create<T>(item: T, baseType: string, envelopeName: string, logger: IDiagnosticLogger, customProperties?: {
-            [key: string]: any;
-        }, systemProperties?: {
-            [key: string]: any;
-        }): ITelemetryItem;
+        static create: typeof createTelemetryItem;
     }
 
     class Trace implements IMessageData, ISerializable {