Add a simple interface to enable custom buffer storage solutions #1419 (

#2037)

This can be used like:

```
const appInsights = new ApplicationInsights({
  config: {
    enableSessionStorageBuffer: true,
    bufferOverride: {
      getItem: (logger, key) => localStorage.getItem(key),
      setItem: (logger, key, value) => localStorage.setItem(key, value),
    }
  }
});
```

Co-authored-by: Nev <54870357+MSNev@users.noreply.github.com>

README.md

@@ -310,7 +310,7 @@ Most configuration fields are named such that they can be defaulted to falsey. A
 | disableExceptionTracking | boolean || false | If true, exceptions are not autocollected. Default is false. |
 | disableTelemetry | boolean | false | If true, telemetry is not collected or sent. Default is false. |
 | enableDebug | boolean | false | If true, **internal** debugging data is thrown as an exception **instead** of being logged, regardless of SDK logging settings. Default is false. <br>***Note:*** Enabling this setting will result in dropped telemetry whenever an internal error occurs. This can be useful for quickly identifying issues with your configuration or usage of the SDK. If you do not want to lose telemetry while debugging, consider using `loggingLevelConsole` or `loggingLevelTelemetry` instead of `enableDebug`.
-| enableDebugExceptions | boolean | false | Prior to v2.8.12 this was the only supported value and the documented `enableDebug` was incorrect, since v2.8.12 both `enableDebug` and `enableDebugExceptions` is supported. However, this configuration has been removed from v3.x
+| enableDebugExceptions | boolean | false | Removed from v3.x, Prior to v2.8.12 this was the only supported value and the documented `enableDebug` was incorrect, since v2.8.12 both `enableDebug` and `enableDebugExceptions` is supported.
 | loggingLevelConsole | numeric | 0 | Logs **internal** Application Insights errors to console. <br>0: off, <br>1: Critical errors only, <br>2: Everything (errors & warnings) |
 | loggingLevelTelemetry | numeric | 1 | Sends **internal** Application Insights errors as telemetry. <br>0: off, <br>1: Critical errors only, <br>2: Everything (errors & warnings) |
 | diagnosticLogInterval | numeric | 10000 | (internal) Polling interval (in ms) for internal logging queue |

channels/applicationinsights-channel-js/Tests/Unit/src/Sender.tests.ts

@@ -657,6 +657,92 @@ export class SenderTests extends AITestClass {
  }
  });
 
+ this.testCase({
+ name: "Channel Config: Session storage can be enabled",
+ test: () => {
+ let setItemSpy = this.sandbox.spy(window.sessionStorage, "setItem");
+ let getItemSpy = this.sandbox.spy(window.sessionStorage, "getItem");
+
+ this._sender.initialize(
+ {
+ enableSessionStorageBuffer: true
+ }, new AppInsightsCore(), []
+ );
+
+ const telemetryItem: ITelemetryItem = {
+ name: 'fake item',
+ iKey: 'iKey',
+ baseType: 'some type',
+ baseData: {}
+ };
+ this._sender.processTelemetry(telemetryItem, null);
+
+ QUnit.assert.true(this._sender._buffer instanceof SessionStorageSendBuffer, 'Channel config can be set from root config (enableSessionStorageBuffer)');
+ QUnit.assert.equal(false, setItemSpy.calledOnce, "The setItem has not yet been triggered");
+ QUnit.assert.equal(false, getItemSpy.calledOnce, "The getItemSpy has not yet been triggered");
+ }
+ });
+
+ this.testCase({
+ name: "Channel Config: Session storage with buffer override is used",
+ test: () => {
+ let setItemSpy = this.sandbox.stub();
+ let getItemSpy = this.sandbox.stub();
+
+ this._sender.initialize(
+ {
+ enableSessionStorageBuffer: true,
+ bufferOverride: {
+ getItem: getItemSpy,
+ setItem: setItemSpy
+ }
+ }, new AppInsightsCore(), []
+ );
+
+ const telemetryItem: ITelemetryItem = {
+ name: 'fake item',
+ iKey: 'iKey',
+ baseType: 'some type',
+ baseData: {}
+ };
+ this._sender.processTelemetry(telemetryItem, null);
+
+ QUnit.assert.true(this._sender._buffer instanceof SessionStorageSendBuffer, 'Channel config can be set from root config (enableSessionStorageBuffer)');
+ QUnit.assert.equal(false, setItemSpy.calledOnce, "The setItem has not yet been triggered");
+ QUnit.assert.equal(false, getItemSpy.calledOnce, "The getItemSpy has not yet been triggered");
+ }
+ });
+
+ this.testCase({
+ name: "Channel Config: Session storage can be disabled",
+ test: () => {
+ this._sender.initialize(
+ {
+ enableSessionStorageBuffer: false
+ }, new AppInsightsCore(), []
+ );
+
+ QUnit.assert.true(this._sender._buffer instanceof ArraySendBuffer, 'Channel config can be set from root config (enableSessionStorageBuffer)');
+ }
+ });
+
+ this.testCase({
+ name: "Channel Config: Session storage ignores buffer override when disabled",
+ test: () => {
+ this._sender.initialize(
+ {
+ enableSessionStorageBuffer: false,
+ bufferOverride: {
+ getItem: this.sandbox.stub(),
+ setItem: this.sandbox.stub()
+ }
+ }, new AppInsightsCore(), []
+ );
+
+ QUnit.assert.true(this._sender._buffer instanceof ArraySendBuffer, 'Channel config can be set from root config (enableSessionStorageBuffer)');
+ }
+ });
+
  this.testCase({
  name: "processTelemetry can be called with optional fields undefined",
  useFakeTimers: true,

channels/applicationinsights-channel-js/src/Interfaces.ts

@@ -1,3 +1,5 @@
+import { IStorageBuffer } from "@microsoft/applicationinsights-common";
+
 export interface ISenderConfig {
  /**
  * The url to which payloads will be sent
@@ -29,6 +31,11 @@ export interface ISenderConfig {
  */
  enableSessionStorageBuffer: boolean;
 
+ /**
+ * Specify the storage buffer type implementation.
+ */
+ bufferOverride: IStorageBuffer | false;
+
  /**
  * Is retry handler disabled.
  * If enabled, retry on 206 (partial success), 408 (timeout), 429 (too many requests), 500 (internal server error) and 503 (service unavailable).

channels/applicationinsights-channel-js/src/SendBuffer.ts

@@ -224,6 +224,7 @@ export class SessionStorageSendBuffer extends BaseSendBuffer implements ISendBuf
  let _bufferFullMessageSent = false;
  //Note: should not use config.namePrefix directly, because it will always refers to the latest namePrefix
  let _namePrefix = config?.namePrefix;
+ const { getItem, setItem } = config.bufferOverride || { getItem: utlGetSessionStorage, setItem: utlSetSessionStorage };
 
  dynamicProto(SessionStorageSendBuffer, this, (_self, _base) => {
  const bufferItems = _getBuffer(SessionStorageSendBuffer.BUFFER_KEY);
@@ -331,7 +332,7 @@ export class SessionStorageSendBuffer extends BaseSendBuffer implements ISendBuf
  let prefixedKey = key;
  try {
  prefixedKey = _namePrefix ? _namePrefix + "_" + prefixedKey : prefixedKey;
- const bufferJson = utlGetSessionStorage(logger, prefixedKey);
+ const bufferJson = getItem(logger, prefixedKey);
  if (bufferJson) {
  let buffer: string[] = getJSON().parse(bufferJson);
  if (isString(buffer)) {
@@ -358,11 +359,11 @@ export class SessionStorageSendBuffer extends BaseSendBuffer implements ISendBuf
  try {
  prefixedKey = _namePrefix ? _namePrefix + "_" + prefixedKey : prefixedKey;
  const bufferJson = JSON.stringify(buffer);
- utlSetSessionStorage(logger, prefixedKey, bufferJson);
+ setItem(logger, prefixedKey, bufferJson);
  } catch (e) {
  // if there was an error, clear the buffer
  // telemetry is stored in the _buffer array so we won't loose any items
- utlSetSessionStorage(logger, prefixedKey, JSON.stringify([]));
+ setItem(logger, prefixedKey, JSON.stringify([]));
 
  _throwInternal(logger, eLoggingSeverity.WARNING,
  _eInternalMessageId.FailedToSetStorageBuffer,

channels/applicationinsights-channel-js/src/Sender.ts

@@ -1,8 +1,8 @@
 import dynamicProto from "@microsoft/dynamicproto-js";
 import {
  BreezeChannelIdentifier, DEFAULT_BREEZE_ENDPOINT, DEFAULT_BREEZE_PATH, DisabledPropertyName, Event, Exception, IConfig, IEnvelope,
- ISample, Metric, PageView, PageViewPerformance, ProcessLegacy, RemoteDependencyData, RequestHeaders, SampleRate, Trace, eRequestHeaders,
- isInternalApplicationInsightsEndpoint, utlCanUseSessionStorage
+ ISample, IStorageBuffer, Metric, PageView, PageViewPerformance, ProcessLegacy, RemoteDependencyData, RequestHeaders, SampleRate, Trace,
+ eRequestHeaders, isInternalApplicationInsightsEndpoint, utlCanUseSessionStorage
 } from "@microsoft/applicationinsights-common";
 import {
  BaseTelemetryPlugin, IAppInsightsCore, IChannelControls, IConfigDefaults, IConfiguration, IDiagnosticLogger, INotificationManager,
@@ -62,7 +62,8 @@ const defaultAppInsightsChannelConfig: IConfigDefaults<ISenderConfig> = objDeepF
  samplingPercentage: cfgDfValidate(_chkSampling, 100),
  customHeaders: UNDEFINED_VALUE,
  convertUndefined: UNDEFINED_VALUE,
- eventsLimitInMem: 10000
+ eventsLimitInMem: 10000,
+ bufferOverride: false
 });
 
 function _chkSampling(value: number) {
@@ -153,6 +154,7 @@ export class Sender extends BaseTelemetryPlugin implements IChannelControls {
  let _isRetryDisabled: boolean;
  let _maxBatchInterval: number;
  let _sessionStorageUsed: boolean;
+ let _bufferOverrideUsed: IStorageBuffer | false;
  let _namePrefix: string;
 
  dynamicProto(Sender, this, (_self, _base) => {
@@ -260,13 +262,16 @@ export class Sender extends BaseTelemetryPlugin implements IChannelControls {
  _maxBatchSizeInBytes = senderConfig.maxBatchSizeInBytes;
  _beaconSupported = (senderConfig.onunloadDisableBeacon === false || senderConfig.isBeaconApiDisabled === false) && isBeaconsSupported();
 
- let canUseSessionStorage = !!senderConfig.enableSessionStorageBuffer && utlCanUseSessionStorage();
+ let bufferOverride = senderConfig.bufferOverride;
+ let canUseSessionStorage = !!senderConfig.enableSessionStorageBuffer &&
+ (!!bufferOverride || utlCanUseSessionStorage());
  let namePrefix = senderConfig.namePrefix;
 
  //Note: emitLineDelimitedJson and eventsLimitInMem is directly accessed via config in senderBuffer
  //Therefore, if canUseSessionStorage is not changed, we do not need to re initialize a new one
  let shouldUpdate = (canUseSessionStorage !== _sessionStorageUsed)
- || (canUseSessionStorage && (_namePrefix !== namePrefix)); // prefixName is only used in session storage
+ || (canUseSessionStorage && (_namePrefix !== namePrefix)) // prefixName is only used in session storage
+ || (canUseSessionStorage && (_bufferOverrideUsed !== bufferOverride));
 
  if (_self._buffer) {
  // case1 (Pre and Now enableSessionStorageBuffer settings are same)
@@ -296,6 +301,7 @@ export class Sender extends BaseTelemetryPlugin implements IChannelControls {
 
  _namePrefix = namePrefix;
  _sessionStorageUsed = canUseSessionStorage;
+ _bufferOverrideUsed = bufferOverride;
 
  _self._sample = new Sample(senderConfig.samplingPercentage, diagLog);