@fluidframework/fluid-telemetry 2.0.0-dev-rc.3.0.0.253463

package/lib/fluid-telemetry-untrimmed.d.ts

@@ -0,0 +1,213 @@
+/**
+ * This package provides an implementation and types for producing and consuming telemetry for Fluid Framework applications
+ * @packageDocumentation
+ */
+
+import { ICriticalContainerError } from '@fluidframework/container-definitions';
+import type { IFluidContainer } from '@fluidframework/fluid-static';
+
+/**
+ * The container "connected" telemetry event.
+ * It is produced from an internal Fluid container system event {@link @fluidframework/container-definitions#IContainerEvents} which is emitted when the {@link @fluidframework/container-definitions#IContainer} completes connecting to the Fluid service.
+ *
+ * @see More details about {@link @fluidframework/container-definitions#IContainer.connectionState  | the containers connection state}
+ * @see More details about {@link @fluidframework/container-definitions#IContainer.connect | the function to connect a container }
+ * @see More details about {@link @fluidframework/container-definitions#IContainer.connectionState  | the containers connection state}
+ *
+ * @beta
+ */
+export declare interface ContainerConnectedTelemetry extends IContainerTelemetry {
+    /**
+     * {@inheritDoc IFluidTelemetry.eventName}
+     */
+    eventName: "fluidframework.container.connected";
+}
+
+/**
+ * The container "disconnected" telemetry event. This telemetry is produced from an internal Fluid container system event
+ * {@link @fluidframework/container-definitions#IContainerEvents} which is emitted when the {@link @fluidframework/container-definitions#IContainer}
+ * becomes disconnected from the Fluid service.
+ *
+ * @see More details about{@link @fluidframework/container-definitions#IContainer.connectionState | the containers connection state}
+ *
+ * @see More details about{@link @fluidframework/container-definitions#IContainer.disconnect | the function to disconnect a container}
+ *
+ * @beta
+ */
+export declare interface ContainerDisconnectedTelemetry extends IContainerTelemetry {
+    /**
+     * {@inheritDoc IFluidTelemetry.eventName}
+     */
+    eventName: "fluidframework.container.disconnected";
+}
+
+/**
+ *
+ * The Fluid container "disposed" telemetry event. This telemetry is produced from the "disposed" Fluid container system event
+ * which is emitted when the {@link @fluidframework/fluid-static#IFluidContainer} is closed, which permanently disables it.
+ *
+ * @see More details about{@link @fluidframework/container-definitions#IContainer.close | the container close event}
+ *
+ * @beta
+ */
+export declare interface ContainerDisposedTelemetry extends IContainerTelemetry {
+    /**
+     * {@inheritDoc IFluidTelemetry.eventName}
+     */
+    eventName: "fluidframework.container.disposed";
+    /**
+     * If the container was closed due to error (as opposed to an explicit call to
+     * {@link @fluidframework/fluid-static#IFluidContainer."dispose"}), this will contain details about the error that caused it.
+     */
+    error?: ICriticalContainerError;
+}
+
+/**
+ * The aggregate type for all values within {@link ContainerTelemetryEventNames}
+ * @beta
+ */
+export declare type ContainerTelemetryEventName = (typeof ContainerTelemetryEventNames)[keyof typeof ContainerTelemetryEventNames];
+
+/**
+ * This object contains names for Container Telemetry. Unlike the raw {@link @fluidframework/fluid-static#IFluidContainerEvents | IFluidContainer system event names} they contain more information such as the scope
+ *
+ * @beta
+ */
+export declare const ContainerTelemetryEventNames: {
+    /**
+     * Name for the container telemetry event that is intended to be produced from the IFluidContainer "connected" {@link @fluidframework/fluid-static#IFluidContainerEvents | system event}
+     *
+     * @see {@link ContainerConnectedTelemetry}
+     */
+    readonly CONNECTED: "fluidframework.container.connected";
+    /**
+     * Name for the container telemetry event that is intended to be produced from the IFluidContainer "disconnected" {@link @fluidframework/fluid-static#IFluidContainerEvents | system event}
+     *
+     * @see {@link ContainerDisconnectedTelemetry}
+     */
+    readonly DISCONNECTED: "fluidframework.container.disconnected";
+    /**
+     * Name for the container telemetry event that is intended to be produced from the IFluidContainer "disposed" {@link @fluidframework/fluid-static#IFluidContainerEvents | system event}
+     *
+     * @see {@link ContainerDisposedTelemetry}
+     */
+    readonly DISPOSED: "fluidframework.container.disposed";
+};
+
+/**
+ * Aggregate type for all the different types of Fluid telemetry event names.
+ *
+ * @privateremarks This only looks odd right now because {@link ContainerTelemetryEventName} is the only aggregation at the moment.
+ *
+ * @beta
+ */
+export declare type FluidTelemetryEventName = ContainerTelemetryEventName;
+
+/**
+ * The base interface for all Container telemetry
+ * @beta
+ */
+export declare interface IContainerTelemetry extends IFluidTelemetry {
+    /**
+     * {@inheritdoc IFluidTelemetry.eventName}
+     */
+    eventName: ContainerTelemetryEventName;
+    /**
+     * Unique identifier for a container, stable across creation and load.
+     * I.e. different clients loading the same container (or the same client loading the container two separate times)
+     * will agree on this value.
+     *
+     * @remarks This can be undefined for a container that has not been attached.
+     */
+    containerId?: string;
+    /**
+     * Unique identifier for the container instance that generated the telemetry.
+     * This is not a stable identifier for the container across clients/time.
+     * Every load of the container will result in a different value.
+     *
+     */
+    containerInstanceId: string;
+}
+
+export { ICriticalContainerError }
+
+/**
+ * The base interface extended by all Fluid telemetry
+ *
+ * @see {@link @fluidframework/fluid-telemetry#IContainerTelemetry} for an extension of this interface for all container related telemetry.
+ *
+ * @beta
+ */
+export declare interface IFluidTelemetry {
+    /**
+     * The unique name of the telemetry event. The event name contains scope concatenated together
+     * with periods to enable more granular log searching
+     *
+     * @example
+     * "fluidframework.container.connected"
+     */
+    eventName: FluidTelemetryEventName;
+}
+
+/**
+ * Base interface for all telemetry consumers.
+ * Conusmers are intended to take incoming produced {@link IFluidTelemetry} and do something of your choice with it.
+ * This could be sending the telemetry to a cloud platform or just console logging.
+ *
+ * @example
+ * Here is an example of how we construct a consumer to send telemetry to Azure App Insights, a cloud logging platform:
+ * ```ts
+ * class AppInsightsTelemetryConsumer implements ITelemetryConsumer {
+ *	   constructor(private readonly appInsightsClient: ApplicationInsights) {}
+ *
+ *	   consume(event: IFluidTelemetry) {
+ *		   this.appInsightsClient.trackEvent({
+ *			   name: event.eventName,
+ *			   properties: event,
+ *		   });
+ *	   }
+ * }
+ *```
+ *
+ * @beta
+ */
+export declare interface ITelemetryConsumer {
+    /**
+     * This method is intended to take created {@link IFluidTelemetry} and do something with it.
+     * This could be sending the telemetry to a cloud platform, just console logging or something else of your choice.
+     */
+    consume(event: IFluidTelemetry): any;
+}
+
+/**
+ * Starts creating {@link @fluidframework/fluid-telemetry#IFluidTelemetry} by transforming raw system events emitted by the specified container
+ * into said telemetry and passing it onto to the specified {@link ITelemetryConsumer}
+ *
+ * @beta
+ */
+export declare const startTelemetry: (config: TelemetryConfig) => void;
+
+/**
+ * Configuration object for subscribing to {@link @fluidframework/fluid-telemetry#IFluidTelemetry} and consuming said telemetry via one or more {@link ITelemetryConsumer}
+ *
+ * @beta
+ */
+export declare interface TelemetryConfig {
+    /**
+     * The container whose events should be monitored, transformed into Fluid telemetry, and sent to a {@link ITelemetryConsumer}.
+     */
+    container: IFluidContainer;
+    /**
+     * Unique identifier for the passed in container, i.e. the return value of a call
+     * to {@link @fluidframework/fluid-static#IFluidContainer.attach | `IFluidContainer.attach()`} when creating a new
+     * Fluid container, or the id used to load a pre-existing one.
+     */
+    containerId: string;
+    /**
+     * Conusmers take incoming produced {@link @fluidframework/fluid-telemetry#IFluidTelemetry} and do something of your choice with it.
+     * This could be sending the telemetry to a cloud platform or just console logging.
+     */
+    consumers: ITelemetryConsumer[];
+}
+
+export { }

package/lib/index.d.ts

@@ -0,0 +1,13 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+/**
+ * This package provides an implementation and types for producing and consuming telemetry for Fluid Framework applications
+ * @packageDocumentation
+ */
+export { type ICriticalContainerError } from "@fluidframework/container-definitions";
+export { type IFluidTelemetry, type FluidTelemetryEventName, type ITelemetryConsumer, } from "./common/index.js";
+export { type IContainerTelemetry, type ContainerTelemetryEventName, ContainerTelemetryEventNames, type ContainerConnectedTelemetry, type ContainerDisconnectedTelemetry, type ContainerDisposedTelemetry, } from "./container/index.js";
+export { startTelemetry, type TelemetryConfig } from "./factory/index.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,OAAO,EAAE,KAAK,uBAAuB,EAAE,MAAM,uCAAuC,CAAC;AACrF,OAAO,EACN,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,4BAA4B,EAC5B,KAAK,2BAA2B,EAChC,KAAK,8BAA8B,EACnC,KAAK,0BAA0B,GAC/B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/lib/index.js

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export { ContainerTelemetryEventNames, } from "./container/index.js";
+export { startTelemetry } from "./factory/index.js";
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,EAGN,4BAA4B,GAI5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAwB,MAAM,oBAAoB,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * This package provides an implementation and types for producing and consuming telemetry for Fluid Framework applications\n * @packageDocumentation\n */\nexport { type ICriticalContainerError } from \"@fluidframework/container-definitions\";\nexport {\n\ttype IFluidTelemetry,\n\ttype FluidTelemetryEventName,\n\ttype ITelemetryConsumer,\n} from \"./common/index.js\";\nexport {\n\ttype IContainerTelemetry,\n\ttype ContainerTelemetryEventName,\n\tContainerTelemetryEventNames,\n\ttype ContainerConnectedTelemetry,\n\ttype ContainerDisconnectedTelemetry,\n\ttype ContainerDisposedTelemetry,\n} from \"./container/index.js\";\nexport { startTelemetry, type TelemetryConfig } from \"./factory/index.js\";\n"]}

package/lib/test/containerTelemetry.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=containerTelemetry.spec.d.ts.map

package/lib/test/containerTelemetry.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerTelemetry.spec.d.ts","sourceRoot":"","sources":["../../src/test/containerTelemetry.spec.ts"],"names":[],"mappings":""}

package/lib/test/containerTelemetry.spec.js

@@ -0,0 +1,138 @@
+import { spy } from "sinon";
+import { expect } from "chai";
+import { TypedEventEmitter } from "@fluid-internal/client-utils";
+import { ApplicationInsights } from "@microsoft/applicationinsights-web";
+import { startTelemetry } from "../factory/index.js";
+import { IFluidContainerSystemEventNames } from "../container/index.js";
+import { ContainerTelemetryEventNames, } from "../index.js";
+/**
+ * For these unit tests, we are just interested in the event emitter part of the Fluid container.
+ * The rest of the functionality of IFluidContainer is irrelevant.
+ */
+class MockFluidContainer extends TypedEventEmitter {
+    connect() {
+        this.emit(IFluidContainerSystemEventNames.CONNECTED);
+    }
+    disconnect() {
+        this.emit(IFluidContainerSystemEventNames.DISCONNECTED);
+    }
+    dispose(error) {
+        this.emit(IFluidContainerSystemEventNames.DISPOSED, error);
+    }
+}
+describe("container telemetry via", () => {
+    let mockFluidContainer;
+    const mockContainerId = "mockContainerId";
+    let appInsightsClient;
+    let trackEventSpy;
+    let telemetryConfig;
+    beforeEach(() => {
+        appInsightsClient = new ApplicationInsights({
+            config: {
+                connectionString: 
+                // (this is an example string)
+                "InstrumentationKey=abcdefgh-ijkl-mnop-qrst-uvwxyz6ffd9c;IngestionEndpoint=https://westus2-2.in.applicationinsights.azure.com/;LiveEndpoint=https://westus2.livediagnostics.monitor.azure.com/",
+            },
+        });
+        trackEventSpy = spy(appInsightsClient, "trackEvent");
+        mockFluidContainer = new MockFluidContainer();
+        class AppInsightsTelemetryConsumer {
+            constructor(client) {
+                this.client = client;
+            }
+            consume(event) {
+                this.client.trackEvent({
+                    name: event.eventName,
+                    properties: event,
+                });
+            }
+        }
+        telemetryConfig = {
+            container: mockFluidContainer,
+            containerId: mockContainerId,
+            consumers: [new AppInsightsTelemetryConsumer(appInsightsClient)],
+        };
+    });
+    it("Emitting 'connected' container system event produces expected ContainerConnectedTelemetry using Azure App Insights", () => {
+        startTelemetry(telemetryConfig);
+        mockFluidContainer.connect();
+        expect(trackEventSpy.callCount).to.equal(1);
+        // Obtain the events from the method that the spy was called with
+        const actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0];
+        const actualContainerTelemetry = actualAppInsightsTelemetry.properties;
+        const expectedAppInsightsTelemetry = {
+            name: ContainerTelemetryEventNames.CONNECTED,
+            properties: {
+                eventName: ContainerTelemetryEventNames.CONNECTED,
+                containerId: mockContainerId,
+                containerInstanceId: actualContainerTelemetry.containerInstanceId,
+            },
+        };
+        expect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);
+        // We won't know what the container containerInstanceId will be but we can still check that it is defined.
+        expect(actualContainerTelemetry.containerInstanceId).to.be.a("string").with.length.above(0);
+    });
+    it("Emitting 'disconnected' container system event produces expected ContainerDisconnectedTelemetry using Azure App Insights", () => {
+        startTelemetry(telemetryConfig);
+        mockFluidContainer.disconnect();
+        expect(trackEventSpy.callCount).to.equal(1);
+        // Obtain the events from the method that the spy was called with
+        const actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0];
+        const actualContainerTelemetry = actualAppInsightsTelemetry.properties;
+        const expectedAppInsightsTelemetry = {
+            name: ContainerTelemetryEventNames.DISCONNECTED,
+            properties: {
+                eventName: ContainerTelemetryEventNames.DISCONNECTED,
+                containerId: mockContainerId,
+                containerInstanceId: actualContainerTelemetry.containerInstanceId,
+            },
+        };
+        expect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);
+        // We won't know what the container containerInstanceId will be but we can still check that it is defined.
+        expect(actualContainerTelemetry.containerInstanceId).to.be.a("string").with.length.above(0);
+    });
+    it("Emitting 'disposed' system event produces expected ContainerDisposedTelemetry using Azure App Insights", () => {
+        startTelemetry(telemetryConfig);
+        mockFluidContainer.dispose();
+        expect(trackEventSpy.callCount).to.equal(1);
+        // Obtain the events from the method that the spy was called with
+        const actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0];
+        const actualContainerTelemetry = actualAppInsightsTelemetry.properties;
+        const expectedAppInsightsTelemetry = {
+            name: ContainerTelemetryEventNames.DISPOSED,
+            properties: {
+                eventName: ContainerTelemetryEventNames.DISPOSED,
+                containerId: mockContainerId,
+                containerInstanceId: actualContainerTelemetry.containerInstanceId,
+            },
+        };
+        expect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);
+        // We won't know what the container containerInstanceId will be but we can still check that it is defined.
+        expect(actualContainerTelemetry.containerInstanceId).to.be.a("string").with.length.above(0);
+    });
+    it("Emitting 'disposed' system event with an error produces expected ContainerDisposedTelemetry using Azure App Insights", () => {
+        startTelemetry(telemetryConfig);
+        const containerError = {
+            errorType: "unknown error",
+            message: "An unknown error occured",
+            stack: "example stack error at line 52 of Container.ts",
+        };
+        mockFluidContainer.dispose(containerError);
+        // Obtain the events from the method that the spy was called with
+        const actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0];
+        const actualContainerTelemetry = actualAppInsightsTelemetry.properties;
+        const expectedAppInsightsTelemetry = {
+            name: ContainerTelemetryEventNames.DISPOSED,
+            properties: {
+                eventName: ContainerTelemetryEventNames.DISPOSED,
+                containerId: mockContainerId,
+                containerInstanceId: actualContainerTelemetry.containerInstanceId,
+                error: containerError,
+            },
+        };
+        expect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);
+        // We won't know what the container containerInstanceId will be but we can still check that it is defined.
+        expect(actualContainerTelemetry.containerInstanceId).to.be.a("string").with.length.above(0);
+    });
+});
+//# sourceMappingURL=containerTelemetry.spec.js.map

package/lib/test/containerTelemetry.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerTelemetry.spec.js","sourceRoot":"","sources":["../../src/test/containerTelemetry.spec.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\nimport type Sinon from \"sinon\";\nimport { spy } from \"sinon\";\nimport { expect } from \"chai\";\nimport { TypedEventEmitter } from \"@fluid-internal/client-utils\";\nimport type { ICriticalContainerError } from \"@fluidframework/container-definitions\";\nimport { ApplicationInsights, type IEventTelemetry } from \"@microsoft/applicationinsights-web\";\nimport type { IFluidContainer, IFluidContainerEvents } from \"@fluidframework/fluid-static\";\nimport { startTelemetry, type TelemetryConfig } from \"../factory/index.js\";\nimport { IFluidContainerSystemEventNames, type IContainerTelemetry } from \"../container/index.js\";\nimport {\n\tContainerTelemetryEventNames,\n\ttype ContainerConnectedTelemetry,\n\ttype ContainerDisconnectedTelemetry,\n\ttype ContainerDisposedTelemetry,\n\ttype IFluidTelemetry,\n\ttype ITelemetryConsumer,\n} from \"../index.js\";\n\n/**\n * For these unit tests, we are just interested in the event emitter part of the Fluid container.\n * The rest of the functionality of IFluidContainer is irrelevant.\n */\nclass MockFluidContainer extends TypedEventEmitter<IFluidContainerEvents> {\n\tpublic connect(): void {\n\t\tthis.emit(IFluidContainerSystemEventNames.CONNECTED);\n\t}\n\n\tpublic disconnect(): void {\n\t\tthis.emit(IFluidContainerSystemEventNames.DISCONNECTED);\n\t}\n\n\tpublic dispose(error?: ICriticalContainerError): void {\n\t\tthis.emit(IFluidContainerSystemEventNames.DISPOSED, error);\n\t}\n}\n\ndescribe(\"container telemetry via\", () => {\n\tlet mockFluidContainer: MockFluidContainer;\n\tconst mockContainerId = \"mockContainerId\";\n\tlet appInsightsClient: ApplicationInsights;\n\tlet trackEventSpy: Sinon.SinonSpy;\n\tlet telemetryConfig: TelemetryConfig;\n\n\tbeforeEach(() => {\n\t\tappInsightsClient = new ApplicationInsights({\n\t\t\tconfig: {\n\t\t\t\tconnectionString:\n\t\t\t\t\t// (this is an example string)\n\t\t\t\t\t\"InstrumentationKey=abcdefgh-ijkl-mnop-qrst-uvwxyz6ffd9c;IngestionEndpoint=https://westus2-2.in.applicationinsights.azure.com/;LiveEndpoint=https://westus2.livediagnostics.monitor.azure.com/\",\n\t\t\t},\n\t\t});\n\n\t\ttrackEventSpy = spy(appInsightsClient, \"trackEvent\");\n\t\tmockFluidContainer = new MockFluidContainer();\n\n\t\tclass AppInsightsTelemetryConsumer implements ITelemetryConsumer {\n\t\t\tpublic constructor(private readonly client: ApplicationInsights) {}\n\n\t\t\tpublic consume(event: IFluidTelemetry): void {\n\t\t\t\tthis.client.trackEvent({\n\t\t\t\t\tname: event.eventName,\n\t\t\t\t\tproperties: event,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\ttelemetryConfig = {\n\t\t\tcontainer: mockFluidContainer as unknown as IFluidContainer,\n\t\t\tcontainerId: mockContainerId,\n\t\t\tconsumers: [new AppInsightsTelemetryConsumer(appInsightsClient)],\n\t\t};\n\t});\n\n\tit(\"Emitting 'connected' container system event produces expected ContainerConnectedTelemetry using Azure App Insights\", () => {\n\t\tstartTelemetry(telemetryConfig);\n\n\t\tmockFluidContainer.connect();\n\n\t\texpect(trackEventSpy.callCount).to.equal(1);\n\n\t\t// Obtain the events from the method that the spy was called with\n\t\tconst actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0] as IEventTelemetry;\n\t\tconst actualContainerTelemetry =\n\t\t\tactualAppInsightsTelemetry.properties as IContainerTelemetry;\n\n\t\tconst expectedAppInsightsTelemetry: IEventTelemetry = {\n\t\t\tname: ContainerTelemetryEventNames.CONNECTED,\n\t\t\tproperties: {\n\t\t\t\teventName: ContainerTelemetryEventNames.CONNECTED,\n\t\t\t\tcontainerId: mockContainerId,\n\t\t\t\tcontainerInstanceId: actualContainerTelemetry.containerInstanceId,\n\t\t\t} satisfies ContainerConnectedTelemetry,\n\t\t};\n\n\t\texpect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);\n\t\t// We won't know what the container containerInstanceId will be but we can still check that it is defined.\n\t\texpect(actualContainerTelemetry.containerInstanceId).to.be.a(\"string\").with.length.above(0);\n\t});\n\n\tit(\"Emitting 'disconnected' container system event produces expected ContainerDisconnectedTelemetry using Azure App Insights\", () => {\n\t\tstartTelemetry(telemetryConfig);\n\n\t\tmockFluidContainer.disconnect();\n\n\t\texpect(trackEventSpy.callCount).to.equal(1);\n\n\t\t// Obtain the events from the method that the spy was called with\n\t\tconst actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0] as IEventTelemetry;\n\t\tconst actualContainerTelemetry =\n\t\t\tactualAppInsightsTelemetry.properties as IContainerTelemetry;\n\n\t\tconst expectedAppInsightsTelemetry: IEventTelemetry = {\n\t\t\tname: ContainerTelemetryEventNames.DISCONNECTED,\n\t\t\tproperties: {\n\t\t\t\teventName: ContainerTelemetryEventNames.DISCONNECTED,\n\t\t\t\tcontainerId: mockContainerId,\n\t\t\t\tcontainerInstanceId: actualContainerTelemetry.containerInstanceId,\n\t\t\t} satisfies ContainerDisconnectedTelemetry,\n\t\t};\n\n\t\texpect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);\n\t\t// We won't know what the container containerInstanceId will be but we can still check that it is defined.\n\t\texpect(actualContainerTelemetry.containerInstanceId).to.be.a(\"string\").with.length.above(0);\n\t});\n\n\tit(\"Emitting 'disposed' system event produces expected ContainerDisposedTelemetry using Azure App Insights\", () => {\n\t\tstartTelemetry(telemetryConfig);\n\n\t\tmockFluidContainer.dispose();\n\n\t\texpect(trackEventSpy.callCount).to.equal(1);\n\n\t\t// Obtain the events from the method that the spy was called with\n\t\tconst actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0] as IEventTelemetry;\n\t\tconst actualContainerTelemetry =\n\t\t\tactualAppInsightsTelemetry.properties as IContainerTelemetry;\n\n\t\tconst expectedAppInsightsTelemetry: IEventTelemetry = {\n\t\t\tname: ContainerTelemetryEventNames.DISPOSED,\n\t\t\tproperties: {\n\t\t\t\teventName: ContainerTelemetryEventNames.DISPOSED,\n\t\t\t\tcontainerId: mockContainerId,\n\t\t\t\tcontainerInstanceId: actualContainerTelemetry.containerInstanceId,\n\t\t\t} satisfies ContainerDisposedTelemetry,\n\t\t};\n\n\t\texpect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);\n\t\t// We won't know what the container containerInstanceId will be but we can still check that it is defined.\n\t\texpect(actualContainerTelemetry.containerInstanceId).to.be.a(\"string\").with.length.above(0);\n\t});\n\n\tit(\"Emitting 'disposed' system event with an error produces expected ContainerDisposedTelemetry using Azure App Insights\", () => {\n\t\tstartTelemetry(telemetryConfig);\n\n\t\tconst containerError: ICriticalContainerError = {\n\t\t\terrorType: \"unknown error\",\n\t\t\tmessage: \"An unknown error occured\",\n\t\t\tstack: \"example stack error at line 52 of Container.ts\",\n\t\t};\n\n\t\tmockFluidContainer.dispose(containerError);\n\n\t\t// Obtain the events from the method that the spy was called with\n\t\tconst actualAppInsightsTelemetry = trackEventSpy.getCall(0).args[0] as IEventTelemetry;\n\t\tconst actualContainerTelemetry =\n\t\t\tactualAppInsightsTelemetry.properties as IContainerTelemetry;\n\n\t\tconst expectedAppInsightsTelemetry: IEventTelemetry = {\n\t\t\tname: ContainerTelemetryEventNames.DISPOSED,\n\t\t\tproperties: {\n\t\t\t\teventName: ContainerTelemetryEventNames.DISPOSED,\n\t\t\t\tcontainerId: mockContainerId,\n\t\t\t\tcontainerInstanceId: actualContainerTelemetry.containerInstanceId,\n\t\t\t\terror: containerError,\n\t\t\t} satisfies ContainerDisposedTelemetry,\n\t\t};\n\n\t\texpect(expectedAppInsightsTelemetry).to.deep.equal(actualAppInsightsTelemetry);\n\t\t// We won't know what the container containerInstanceId will be but we can still check that it is defined.\n\t\texpect(actualContainerTelemetry.containerInstanceId).to.be.a(\"string\").with.length.above(0);\n\t});\n});\n"]}

package/lib/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.42.3"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,145 @@
+{
+  "name": "@fluidframework/fluid-telemetry",
+  "version": "2.0.0-dev-rc.3.0.0.253463",
+  "description": "Customer facing Fluid telemetry types and classes for both producing and consuming said telemetry",
+  "homepage": "https://fluidframework.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/FluidFramework.git",
+    "directory": "packages/framework/client-logger/fluid-telemetry"
+  },
+  "license": "MIT",
+  "author": "Microsoft and contributors",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./public": {
+      "import": {
+        "types": "./lib/fluid-telemetry-public.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/fluid-telemetry-public.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./beta": {
+      "import": {
+        "types": "./lib/fluid-telemetry-beta.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/fluid-telemetry-beta.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./app-insights": {
+      "import": {
+        "types": "./lib/app-insights/index.d.ts",
+        "default": "./lib/app-insights/index.js"
+      },
+      "require": {
+        "types": "./dist/app-insights/index.d.ts",
+        "default": "./dist/app-insights/index.js"
+      }
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@fluidframework/container-definitions": "2.0.0-dev-rc.3.0.0.253463",
+    "@fluidframework/container-loader": "2.0.0-dev-rc.3.0.0.253463",
+    "@fluidframework/fluid-static": "2.0.0-dev-rc.3.0.0.253463",
+    "@microsoft/applicationinsights-web": "^2.8.11",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.15.2",
+    "@fluid-internal/client-utils": "2.0.0-dev-rc.3.0.0.253463",
+    "@fluid-internal/mocha-test-setup": "2.0.0-dev-rc.3.0.0.253463",
+    "@fluid-tools/build-cli": "^0.34.0",
+    "@fluidframework/build-tools": "^0.34.0",
+    "@microsoft/api-extractor": "^7.42.3",
+    "@types/chai": "^4.0.0",
+    "@types/mocha": "^9.1.1",
+    "@types/sinon": "^17.0.3",
+    "@types/uuid": "^9.0.2",
+    "chai": "^4.2.0",
+    "eslint": "~8.55.0",
+    "mocha": "^10.2.0",
+    "prettier": "~3.0.3",
+    "rimraf": "^4.4.0",
+    "sinon": "^17.0.1",
+    "tslib": "^1.10.0",
+    "typescript": "~5.1.6"
+  },
+  "fluidBuild": {
+    "tasks": {
+      "build:docs": {
+        "dependsOn": [
+          "...",
+          "api-extractor:commonjs",
+          "api-extractor:esnext"
+        ],
+        "script": false
+      },
+      "tsc": [
+        "...",
+        "typetests:gen"
+      ]
+    }
+  },
+  "typeValidation": {
+    "broken": {},
+    "disabled": true
+  },
+  "scripts": {
+    "api": "fluid-build . --task api",
+    "api-extractor:commonjs": "api-extractor run --config ./api-extractor-cjs.json",
+    "api-extractor:esnext": "api-extractor run --local",
+    "build": "fluid-build . --task build",
+    "build:commonjs": "fluid-build . --task commonjs",
+    "build:compile": "fluid-build . --task compile",
+    "build:docs": "fluid-build . --task api",
+    "build:esnext": "tsc --project ./tsconfig.json",
+    "check:are-the-types-wrong": "attw --pack . --entrypoints .",
+    "check:release-tags": "api-extractor run --local --config ./api-extractor-lint.json",
+    "ci:build:docs": "api-extractor run",
+    "clean": "rimraf --glob _api-extractor-temp coverage dist lib nyc \"**/*.tsbuildinfo\" \"**/*.build.log\"",
+    "eslint": "eslint --format stylish src",
+    "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
+    "format": "fluid-build --task format .",
+    "format-and-build": "npm run format && npm run build",
+    "format-and-compile": "npm run format && npm run build:compile",
+    "format:prettier": "prettier --write . --cache --ignore-path ../../../../.prettierignore",
+    "lint": "fluid-build . --task lint",
+    "lint:fix": "fluid-build . --task eslint:fix --task format",
+    "test": "npm run test:mocha",
+    "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",
+    "test:mocha:cjs": "mocha --recursive \"dist/test/**/*.spec.*js\" --exit",
+    "test:mocha:esm": "mocha --recursive \"lib/test/**/*.spec.*js\" --exit",
+    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../../common/build/build-common/src/cjs/package.json ./dist",
+    "typetests:gen": "fluid-type-test-generator",
+    "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"
+  }
+}

package/src/app-insights/appInsightsTelemetryConsumer.ts

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type ApplicationInsights } from "@microsoft/applicationinsights-web";
+import type { IFluidTelemetry, ITelemetryConsumer } from "../common/index.js";
+
+/**
+ * An implementation of {@link ITelemetryConsumer} that routes {@link IFluidTelemetry} to Azure App Insights
+ * in a format that is supported by Fluid Framework service offerings such as Cloud dashboards and alarms.
+ */
+export class AppInsightsTelemetryConsumer implements ITelemetryConsumer {
+	public constructor(private readonly appInsightsClient: ApplicationInsights) {}
+
+	public consume(event: IFluidTelemetry): void {
+		this.appInsightsClient.trackEvent({
+			name: event.eventName,
+			properties: event,
+		});
+	}
+}

package/src/app-insights/index.ts

@@ -0,0 +1,6 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { AppInsightsTelemetryConsumer } from "./appInsightsTelemetryConsumer.js";

package/src/common/consumers/index.ts

@@ -0,0 +1,36 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IFluidTelemetry } from "../index.js";
+
+/**
+ * Base interface for all telemetry consumers.
+ * Conusmers are intended to take incoming produced {@link IFluidTelemetry} and do something of your choice with it.
+ * This could be sending the telemetry to a cloud platform or just console logging.
+ *
+ * @example
+ * Here is an example of how we construct a consumer to send telemetry to Azure App Insights, a cloud logging platform:
+ * ```ts
+ * class AppInsightsTelemetryConsumer implements ITelemetryConsumer {
+ *	   constructor(private readonly appInsightsClient: ApplicationInsights) {}
+ *
+ *	   consume(event: IFluidTelemetry) {
+ *		   this.appInsightsClient.trackEvent({
+ *			   name: event.eventName,
+ *			   properties: event,
+ *		   });
+ *	   }
+ * }
+ *```
+ *
+ * @beta
+ */
+export interface ITelemetryConsumer {
+	/**
+	 * This method is intended to take created {@link IFluidTelemetry} and do something with it.
+	 * This could be sending the telemetry to a cloud platform, just console logging or something else of your choice.
+	 */
+	consume(event: IFluidTelemetry);
+}

package/src/common/index.ts

@@ -0,0 +1,7 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export { type ITelemetryConsumer } from "./consumers/index.js";
+export { type IFluidTelemetry, type FluidTelemetryEventName } from "./telemetry/index.js";