Class AnalyticsPlugin

Internal interface to pass appInsights object to subcomponents without coupling

Hierarchy

  • BaseTelemetryPlugin
    • AnalyticsPlugin

Implements

Constructors

constructor

Properties

_doTeardown? _doUpdate? _getTelCtx _unloadHooks autoRoutePVDelay config core diagLog identifier isInitialized priority processNext queue setInitialized setNextPlugin? version? Version

Methods

_addHook _addUnloadCb _onerror addTelemetryInitializer getCookieMgr initialize processTelemetry sendExceptionInternal sendPageViewInternal sendPageViewPerformanceInternal startTrackEvent startTrackPage stopTrackEvent stopTrackPage teardown trackEvent trackException trackMetric trackPageView trackPageViewPerformance trackTrace update

Constructors

constructor

Properties

Protected Optional_doTeardown

_doTeardown?: ((unloadCtx?: IProcessTelemetryUnloadContext, unloadState?: ITelemetryUnloadState, asyncCallback?: (() => void)) => boolean | void)

Teardown / Unload hook to allow implementations to perform some additional unload operations before the BaseTelemetryPlugin finishes it's removal.

Type declaration

    • (unloadCtx?, unloadState?, asyncCallback?): boolean | void

    • Parameters

      • OptionalunloadCtx: IProcessTelemetryUnloadContext

        This is the context that should be used during unloading.

      • OptionalunloadState: ITelemetryUnloadState

        The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.

      • OptionalasyncCallback: (() => void)

        An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async unload/teardown operations.

          • (): void

          • Returns void

      Returns boolean | void

      boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.

Protected Optional_doUpdate

_doUpdate?: ((updateCtx?: IProcessTelemetryUpdateContext, updateState?: ITelemetryUpdateState, asyncCallback?: (() => void)) => boolean | void)

Extension hook to allow implementations to perform some additional update operations before the BaseTelemetryPlugin finishes it's removal

Type declaration

    • (updateCtx?, updateState?, asyncCallback?): boolean | void

    • Parameters

      • OptionalupdateCtx: IProcessTelemetryUpdateContext

        This is the context that should be used during updating.

      • OptionalupdateState: ITelemetryUpdateState

        The details / state of the update process, it holds details like the current and previous configuration.

      • OptionalasyncCallback: (() => void)

        An optional callback that the plugin must call if it returns true to inform the caller that it has completed any async update operations.

          • (): void

          • Returns void

      Returns boolean | void

      boolean - true if the plugin has or will call asyncCallback, this allows the plugin to perform any asynchronous operations.

Protected_getTelCtx

_getTelCtx: ((currentCtx?: IProcessTelemetryContext) => IProcessTelemetryContext)

Helper to return the current IProcessTelemetryContext, if the passed argument exists this just returns that value (helps with minification for callers), otherwise it will return the configured context or a temporary one.

Type declaration

    • (currentCtx?): IProcessTelemetryContext

    • Parameters

      • OptionalcurrentCtx: IProcessTelemetryContext

        [Optional] The current execution context

      Returns IProcessTelemetryContext

Protected Readonly_unloadHooks

_unloadHooks: IUnloadHookContainer

Exposes the underlying unload hook container instance for this extension to allow it to be passed down to any sub components of the class. This should NEVER be exposed or called publically as it's scope is for internal use by BaseTelemetryPlugin and any derived class (which is why it's scoped as protected)

autoRoutePVDelay

autoRoutePVDelay: number = 500

Readonlyconfig

config: IConfig & IConfiguration

core

core: IAppInsightsCore<IConfiguration>

Holds the core instance that was used during initialization

diagLog

diagLog: ((itemCtx?: IProcessTelemetryContext) => IDiagnosticLogger)

Returns the current diagnostic logger that can be used to log issues, if no logger is currently assigned a new default one will be created and returned.

identifier

identifier: string = AnalyticsPluginIdentifier

isInitialized

isInitialized: (() => boolean)

Returns whether the plugin has been initialized

priority

priority: number = 180

processNext

processNext: ((env: ITelemetryItem, itemCtx: IProcessTelemetryContext) => void)

Call back for telemetry processing before it it is sent

Type declaration

    • (env, itemCtx): void

    • Parameters

      • env: ITelemetryItem

        This is the current event being reported

      • itemCtx: IProcessTelemetryContext

        This is the context for the current request, ITelemetryPlugin instances can optionally use this to access the current core instance or define / pass additional information to later plugins (vs appending items to the telemetry item)

      Returns void

queue

queue: (() => void)[]

ProtectedsetInitialized

setInitialized: ((isInitialized: boolean) => void)

Internal helper to allow setting of the internal initialized setting for inherited instances and unit testing

OptionalsetNextPlugin

setNextPlugin?: ((next: ITelemetryPluginChain | ITelemetryPlugin) => void)

Set next extension for telemetry processing, this is now optional as plugins should use the processNext() function of the passed IProcessTelemetryContext instead. It is being kept for now for backward compatibility only.

Deprecated

  • Use processNext() function of the passed IProcessTelemetryContext instead

Optionalversion

version?: string

Plugin version (available in data.properties.version in common schema)

StaticVersion

Version: string = "#version#"

Methods

Protected_addHook

  • _addHook(hooks): void

  • Add this hook so that it is automatically removed during unloading

    Parameters

    • hooks:
          | ILegacyUnloadHook
          | IUnloadHook
          | IUnloadHook[]
          | Iterator<IUnloadHook, any, undefined>
          | ILegacyUnloadHook[]
          | Iterator<ILegacyUnloadHook, any, undefined>

      The single hook or an array of IInstrumentHook objects

    Returns void

Protected_addUnloadCb

  • _addUnloadCb(handler): void

  • Add an unload handler that will be called when the SDK is being unloaded

    Parameters

    • handler: UnloadHandler

      the handler

    Returns void

_onerror

  • _onerror(exception): void

  • Parameters

    • exception: IAutoExceptionTelemetry

      The exception item to be sent

    Returns void

    Description

    Custom error handler for Application Insights Analytics

addTelemetryInitializer

  • addTelemetryInitializer(telemetryInitializer): ITelemetryInitializerHandler

  • Parameters

    • telemetryInitializer: ((item: ITelemetryItem) => boolean | void)
        • (item): boolean | void

        • Parameters

          • item: ITelemetryItem

          Returns boolean | void

    Returns ITelemetryInitializerHandler

getCookieMgr

  • getCookieMgr(): ICookieMgr

  • Get the current cookie manager for this instance

    Returns ICookieMgr

initialize

  • initialize(config, core, extensions, pluginChain?): void

  • Parameters

    • config: IConfiguration & IConfig
    • core: IAppInsightsCore<IConfiguration>
    • extensions: IPlugin[]
    • OptionalpluginChain: ITelemetryPluginChain

    Returns void

processTelemetry

  • processTelemetry(env, itemCtx?): void

  • Parameters

    • env: ITelemetryItem
    • OptionalitemCtx: IProcessTelemetryContext

    Returns void

sendExceptionInternal

  • sendExceptionInternal(exception, customProperties?, systemProperties?): void

  • Parameters

    • exception: IExceptionTelemetry

      The exception item to be sent

    • OptionalcustomProperties: {
          [key: string]: any;
      }
      • [key: string]: any
    • OptionalsystemProperties: {
          [key: string]: any;
      }

      System level properties (Part A) that a user can add to the telemetry item

      • [key: string]: any

    Returns void

    Ignore

    INTERNAL ONLY

sendPageViewInternal

  • sendPageViewInternal(pageView, properties?, systemProperties?): void

  • Create a page view telemetry item and send it to the SDK pipeline through the core.track API

    Parameters

    • pageView: IPageViewTelemetryInternal

      Page view item to be sent

    • Optionalproperties: {
          [key: string]: any;
      }

      Custom properties (Part C) that a user can add to the telemetry item

      • [key: string]: any
    • OptionalsystemProperties: {
          [key: string]: any;
      }

      System level properties (Part A) that a user can add to the telemetry item

      • [key: string]: any

    Returns void

sendPageViewPerformanceInternal

  • sendPageViewPerformanceInternal(pageViewPerformance, properties?, systemProperties?): void

  • Parameters

    • pageViewPerformance: IPageViewPerformanceTelemetryInternal

      The page view performance item to be sent

    • Optionalproperties: {
          [key: string]: any;
      }

      Custom properties (Part C) that a user can add to the telemetry item

      • [key: string]: any
    • OptionalsystemProperties: {
          [key: string]: any;
      }
      • [key: string]: any

    Returns void

    Ignore

    INTERNAL ONLY

startTrackEvent

  • startTrackEvent(name): void

  • Start timing an extended event. Call stopTrackEvent to log the event when it ends.

    Parameters

    • name: string

      A string that identifies this event uniquely within the document.

    Returns void

startTrackPage

  • startTrackPage(name?): void

  • Starts the timer for tracking a page load time. Use this instead of trackPageView if you want to control when the page view timer starts and stops, but don't want to calculate the duration yourself. This method doesn't send any telemetry. Call stopTrackPage to log the end of the page view and send the event.

    Parameters

    • Optionalname: string

      A string that idenfities this item, unique within this HTML document. Defaults to the document title.

    Returns void

stopTrackEvent

  • stopTrackEvent(name, properties?, measurements?): void

  • Log an extended event that you started timing with startTrackEvent.

    Parameters

    • name: string

      The string you used to identify this event in startTrackEvent.

    • Optionalproperties: {
          [key: string]: string;
      }

      map[string, string] - additional data used to filter events and metrics in the portal. Defaults to empty.

      • [key: string]: string
    • Optionalmeasurements: {
          [key: string]: number;
      }

      map[string, number] - metrics associated with this event, displayed in Metrics Explorer on the portal. Defaults to empty.

      • [key: string]: number

    Returns void

stopTrackPage

  • stopTrackPage(name?, url?, properties?, measurement?): void

  • Stops the timer that was started by calling startTrackPage and sends the pageview load time telemetry with the specified properties and measurements. The duration of the page view will be the time between calling startTrackPage and stopTrackPage.

    Parameters

    • Optionalname: string

      The string you used as the name in startTrackPage. Defaults to the document title.

    • Optionalurl: string

      String - a relative or absolute URL that identifies the page or other item. Defaults to the window location.

    • Optionalproperties: {
          [key: string]: string;
      }

      map[string, string] - additional data used to filter pages and metrics in the portal. Defaults to empty.

      • [key: string]: string
    • Optionalmeasurement: {
          [key: string]: number;
      }
      • [key: string]: number

    Returns void

teardown

  • teardown(unloadCtx?, unloadState?): boolean | void

  • Tear down the plugin and remove any hooked value, the plugin should be removed so that it is no longer initialized and therefore could be re-initialized after being torn down. The plugin should ensure that once this has been called any further processTelemetry calls are ignored and it just calls the processNext() with the provided context.

    Parameters

    • OptionalunloadCtx: IProcessTelemetryUnloadContext

      This is the context that should be used during unloading.

    • OptionalunloadState: ITelemetryUnloadState

      The details / state of the unload process, it holds details like whether it should be unloaded synchronously or asynchronously and the reason for the unload.

    Returns boolean | void

    boolean - true if the plugin has or will call processNext(), this for backward compatibility as previously teardown was synchronous and returned nothing.

trackEvent

  • trackEvent(event, customProperties?): void

  • Parameters

    • event: IEventTelemetry
    • OptionalcustomProperties: ICustomProperties

    Returns void

trackException

  • trackException(exception, customProperties?): void

  • Log an exception you have caught.

    Parameters

    • exception: IExceptionTelemetry

      Object which contains exception to be sent

    • OptionalcustomProperties: ICustomProperties

      Additional data used to filter pages and metrics in the portal. Defaults to empty.

      Any property of type double will be considered a measurement, and will be treated by Application Insights as a metric.

    Returns void

trackMetric

  • trackMetric(metric, customProperties?): void

  • Parameters

    • metric: IMetricTelemetry

      input object argument. Only name and average are mandatory.

    • OptionalcustomProperties: ICustomProperties

      additional data used to filter metrics in the portal. Defaults to empty.

    Returns void

    Description

    Log a numeric value that is not associated with a specific event. Typically used to send regular reports of performance indicators. To send single measurement, just use the name and average fields of IMetricTelemetry. If you take measurements frequently, you can reduce the telemetry bandwidth by aggregating multiple measurements and sending the resulting average at intervals

trackPageView

  • trackPageView(pageView?, customProperties?): void

  • Logs that a page or other item was viewed.

    Parameters

    • OptionalpageView: IPageViewTelemetry
    • OptionalcustomProperties: ICustomProperties

      Additional data used to filter events and metrics. Defaults to empty. If a user wants to provide duration for pageLoad, it'll have to be in pageView.properties.duration

    Returns void

trackPageViewPerformance

  • trackPageViewPerformance(pageViewPerformance, customProperties?): void

  • Send browser performance metrics.

    Parameters

    • pageViewPerformance: IPageViewPerformanceTelemetry

      The page view performance item to be sent

    • OptionalcustomProperties: ICustomProperties

      Additional data used to filter pages and metrics in the portal. Defaults to empty.

    Returns void

trackTrace

  • trackTrace(trace, customProperties?): void

  • Parameters

    • trace: ITraceTelemetry

      the trace message

    • OptionalcustomProperties: ICustomProperties

      Additional custom properties to include in the event

    Returns void

    Description

    Log a diagnostic message

update

  • update(updateCtx, updateState): boolean | void

  • The the plugin should re-evaluate configuration and update any cached configuration settings.

    Parameters

    • updateCtx: IProcessTelemetryUpdateContext

      This is the context that should be used during updating.

    • updateState: ITelemetryUpdateState

      The details / state of the update process, it holds details like the current and previous configuration.

    Returns boolean | void

    boolean - true if the plugin has or will call updateCtx.processNext(), this allows the plugin to perform any asynchronous operations.

Settings

Member Visibility

On This Page

Constructors
Properties
Methods