feat: log telemetry for downloads from Colab servers (#576)

Author: kevineger

src/colab/content-browser/commands.ts

@@ -114,38 +114,47 @@ export async function newFolder(vs: typeof vscode, contextItem: ContentItem) {
  * @param contextItem - The tree view context item.
  */
 export async function download(vs: typeof vscode, contextItem: ContentItem) {
-  if (contextItem.type !== vs.FileType.File) {
-    return;
-  }
+  let outcome = Outcome.OUTCOME_CANCELLED;
+  let downloadedBytes = 0;
+  try {
+    if (contextItem.type !== vs.FileType.File) {
+      return;
+    }
 
-  const fileName = contextItem.uri.path.split('/').pop() ?? 'file';
-  const targetUri = await vs.window.showSaveDialog({
-    defaultUri: vs.Uri.file(fileName),
-    title: 'Download File',
-  });
+    const fileName = contextItem.uri.path.split('/').pop() ?? 'file';
+    const targetUri = await vs.window.showSaveDialog({
+      defaultUri: vs.Uri.file(fileName),
+      title: 'Download File',
+    });
 
-  if (!targetUri) {
-    return;
-  }
+    if (!targetUri) {
+      return;
+    }
 
-  await vs.window.withProgress(
-    {
-      location: vs.ProgressLocation.Notification,
-      title: `Downloading ${fileName}...`,
-      cancellable: false,
-    },
-    async () => {
-      try {
-        const content = await vs.workspace.fs.readFile(contextItem.uri);
-        await vs.workspace.fs.writeFile(targetUri, content);
-      } catch (err: unknown) {
-        const msg = err instanceof Error ? err.message : 'unknown error';
-        void vs.window.showErrorMessage(
-          `Failed to download ${fileName}: ${msg}`,
-        );
-      }
-    },
-  );
+    await vs.window.withProgress(
+      {
+        location: vs.ProgressLocation.Notification,
+        title: `Downloading ${fileName}...`,
+        cancellable: false,
+      },
+      async () => {
+        try {
+          const content = await vs.workspace.fs.readFile(contextItem.uri);
+          await vs.workspace.fs.writeFile(targetUri, content);
+          downloadedBytes = content.byteLength;
+          outcome = Outcome.OUTCOME_SUCCEEDED;
+        } catch (err: unknown) {
+          const msg = err instanceof Error ? err.message : 'unknown error';
+          void vs.window.showErrorMessage(
+            `Failed to download ${fileName}: ${msg}`,
+          );
+          outcome = Outcome.OUTCOME_FAILED;
+        }
+      },
+    );
+  } finally {
+    telemetry.logDownload(outcome, downloadedBytes);
+  }
 }
 
 /**

src/colab/content-browser/commands.unit.test.ts

@@ -283,6 +283,64 @@ describe('Server Browser Commands', () => {
 
       sinon.assert.notCalled(vsStub.window.showSaveDialog);
     });
+
+    describe('telemetry', () => {
+      let logStub: SinonStubbedFunction<typeof telemetry.logDownload>;
+
+      beforeEach(() => {
+        logStub = sinon.stub(telemetry, 'logDownload');
+      });
+
+      afterEach(() => {
+        logStub.restore();
+      });
+
+      it('logs OUTCOME_SUCCEEDED with file size when a file is downloaded', async () => {
+        const localUri = TestUri.file('/local/path/foo.txt');
+        vsStub.window.showSaveDialog.resolves(localUri);
+        vsStub.workspace.fs.readFile.resolves(new Uint8Array([1, 2, 3, 4, 5]));
+
+        await download(vs, FILE_ITEM);
+
+        sinon.assert.calledOnceWithExactly(
+          logStub,
+          Outcome.OUTCOME_SUCCEEDED,
+          5,
+        );
+      });
+
+      it('logs OUTCOME_CANCELLED when the user dismisses the save dialog', async () => {
+        vsStub.window.showSaveDialog.resolves(undefined);
+
+        await download(vs, FILE_ITEM);
+
+        sinon.assert.calledOnceWithExactly(
+          logStub,
+          Outcome.OUTCOME_CANCELLED,
+          0,
+        );
+      });
+
+      it('logs OUTCOME_CANCELLED when the target item is not a file', async () => {
+        await download(vs, CONTENT_ROOT);
+
+        sinon.assert.calledOnceWithExactly(
+          logStub,
+          Outcome.OUTCOME_CANCELLED,
+          0,
+        );
+      });
+
+      it('logs OUTCOME_FAILED when the underlying read fails', async () => {
+        const localUri = TestUri.file('/local/path/foo.txt');
+        vsStub.window.showSaveDialog.resolves(localUri);
+        vsStub.workspace.fs.readFile.rejects(new Error('fail'));
+
+        await download(vs, FILE_ITEM);
+
+        sinon.assert.calledOnceWithExactly(logStub, Outcome.OUTCOME_FAILED, 0);
+      });
+    });
   });
 
   describe('renameFile', () => {

src/telemetry/api.ts

@@ -62,6 +62,10 @@ export type ColabEvent =
       /** An event representing a content browser file or folder operation. */
       content_browser_file_operation_event: ContentBrowserFileOperationEvent;
     }
+  | {
+      /** An event representing a file download from a Colab server. */
+      download_event: DownloadEvent;
+    }
   | {
       /** An event representing an error. */
       error_event: ErrorEvent;
@@ -212,6 +216,17 @@ interface ContentBrowserFileOperationEvent {
   target: ContentBrowserTarget;
 }
 
+/** An event representing a file download from a Colab server. */
+interface DownloadEvent {
+  /**
+   * The outcome of the download. `OUTCOME_CANCELLED` covers both the user
+   * dismissing the save dialog and the target item not being a file.
+   */
+  outcome: Outcome;
+  /** The size, in bytes, of the file that was successfully downloaded. */
+  downloaded_bytes: number;
+}
+
 /** An event representing an error. */
 interface ErrorEvent {
   /** The name of the error. */

src/telemetry/index.ts

@@ -91,6 +91,11 @@ export const telemetry = {
       content_browser_file_operation_event: { operation, outcome, target },
     });
   },
+  logDownload: (outcome: Outcome, downloadedBytes: number) => {
+    log({
+      download_event: { outcome, downloaded_bytes: downloadedBytes },
+    });
+  },
   logError: (e: unknown) => {
     if (e instanceof Error) {
       log({

src/telemetry/telemetry.unit.test.ts

@@ -295,6 +295,18 @@ describe('Telemetry Module', () => {
       });
     });
 
+    it('logs on download', () => {
+      telemetry.logDownload(Outcome.OUTCOME_SUCCEEDED, 2048);
+
+      sinon.assert.calledOnceWithExactly(logStub, {
+        ...baseLog,
+        download_event: {
+          outcome: Outcome.OUTCOME_SUCCEEDED,
+          downloaded_bytes: 2048,
+        },
+      });
+    });
+
     it('logs on mount Drive snippet', () => {
       const source = CommandSource.COMMAND_SOURCE_COMMAND_PALETTE;