Add basic, anonymous telemetry which can be disabled with a command l…

…ine argument
timrogers · Dec 8, 2023 · a9b5809 · a9b5809
1 parent d27a907
commit a9b5809
Show file tree

Hide file tree

Showing 7 changed files with 183 additions and 8 deletions.
diff --git a/.github/workflows/end_to_end_tests.yml b/.github/workflows/end_to_end_tests.yml
@@ -30,7 +30,7 @@ jobs:
       - name: Make macOS binary executable
         run: chmod +x bin/gh-migrate-project-darwin-amd64
       - name: Export a project from GitHub.com
-        run: ./bin/gh-migrate-project-darwin-amd64 export --project-owner gh-migrate-project-sandbox --project-number 1
+        run: ./bin/gh-migrate-project-darwin-amd64 export --project-owner gh-migrate-project-sandbox --project-number 1 --disable-telemetry
         env:
           EXPORT_GITHUB_TOKEN: ${{ secrets.GH_MIGRATE_PROJECT_SANDBOX_TOKEN }}
       - name: Copy outputs to output/ directory
@@ -44,7 +44,7 @@ jobs:
           echo "source_repository,target_repository
           gh-migrate-project-sandbox/initial-repository,gh-migrate-project-sandbox/initial-repository" > completed-repository-mappings.csv
       - name: Import project to GitHub.com
-        run: ./bin/gh-migrate-project-darwin-amd64 import --input-path project.json --repository-mappings-path completed-repository-mappings.csv --project-owner gh-migrate-project-sandbox
+        run: ./bin/gh-migrate-project-darwin-amd64 import --input-path project.json --repository-mappings-path completed-repository-mappings.csv --project-owner gh-migrate-project-sandbox --disable-telemetry
         env:
           IMPORT_GITHUB_TOKEN: ${{ secrets.GH_MIGRATE_PROJECT_SANDBOX_TOKEN }}
       - name: Upload outputs as artifacts
@@ -79,7 +79,7 @@ jobs:
       - name: Make Linux binary executable
         run: chmod +x bin/gh-migrate-project-linux-amd64
       - name: Export a project from GitHub.com
-        run: ./bin/gh-migrate-project-linux-amd64 export --project-owner gh-migrate-project-sandbox --project-number 1
+        run: ./bin/gh-migrate-project-linux-amd64 export --project-owner gh-migrate-project-sandbox --project-number 1 --disable-telemetry
         env:
           EXPORT_GITHUB_TOKEN: ${{ secrets.GH_MIGRATE_PROJECT_SANDBOX_TOKEN }}
       - name: Copy outputs to output/ directory
@@ -93,7 +93,7 @@ jobs:
           echo "source_repository,target_repository
           gh-migrate-project-sandbox/initial-repository,gh-migrate-project-sandbox/initial-repository" > completed-repository-mappings.csv
       - name: Import project to GitHub.com
-        run: ./bin/gh-migrate-project-linux-amd64 import --input-path project.json --repository-mappings-path completed-repository-mappings.csv --project-owner gh-migrate-project-sandbox
+        run: ./bin/gh-migrate-project-linux-amd64 import --input-path project.json --repository-mappings-path completed-repository-mappings.csv --project-owner gh-migrate-project-sandbox --disable-telemetry
         env:
           IMPORT_GITHUB_TOKEN: ${{ secrets.GH_MIGRATE_PROJECT_SANDBOX_TOKEN }}
       - name: Upload outputs as artifacts
@@ -133,7 +133,7 @@ jobs:
       - name: Create `output` directory
         run: mkdir output
       - name: Export a project from GitHub.com
-        run: bin/gh-migrate-project-windows-amd64.exe export --project-owner gh-migrate-project-sandbox --project-number 1
+        run: bin/gh-migrate-project-windows-amd64.exe export --project-owner gh-migrate-project-sandbox --project-number 1 --disable-telemetry
         env:
           EXPORT_GITHUB_TOKEN: ${{ secrets.GH_MIGRATE_PROJECT_SANDBOX_TOKEN }}
       - name: Copy outputs to output/ directory
@@ -147,7 +147,7 @@ jobs:
           echo "source_repository,target_repository
           gh-migrate-project-sandbox/initial-repository,gh-migrate-project-sandbox/initial-repository" > completed-repository-mappings.csv
       - name: Import project to GitHub.com
-        run: bin/gh-migrate-project-windows-amd64.exe import --input-path project.json --repository-mappings-path completed-repository-mappings.csv --project-owner gh-migrate-project-sandbox
+        run: bin/gh-migrate-project-windows-amd64.exe import --input-path project.json --repository-mappings-path completed-repository-mappings.csv --project-owner gh-migrate-project-sandbox --disable-telemetry
         env:
           IMPORT_GITHUB_TOKEN: ${{ secrets.GH_MIGRATE_PROJECT_SANDBOX_TOKEN }}
       - name: Upload outputs as artifacts

diff --git a/README.md b/README.md
@@ -80,7 +80,9 @@ gh migrate-project export \
     # OPTIONAL: The URL of an HTTP(S) proxy to use for requests to the GitHub API (e.g. `http://localhost:3128`). This can also be set using the EXPORT_PROXY_URL environment variable.
     --proxy-url https://10.0.0.1:3128 \
     # OPTIONAL: Emit detailed, verbose logs (off by default)
-    --verbose
+    --verbose \
+    # OPTIONAL: Disable anonymous telemetry that gives the maintainers of this tool basic information about real-world usage.
+    --disable-telemetry
 ```
 
 When the export finishes, you'll have two files written to your current directory:
@@ -137,7 +139,9 @@ gh migrate-project import \
     # OPTIONAL: The title to use for the imported project. Defaults to the title of the source project.
     --project-title "My Imported Project" \
     # OPTIONAL: Emit detailed, verbose logs (off by default)
-    --verbose
+    --verbose \
+    # OPTIONAL: Disable anonymous telemetry that gives the maintainers of this tool basic information about real-world usage.
+    --disable-telemetry
 ```
 
 Near the start of the import, the tool will ask you to manually set up your options for the "Status" field. It will explain exactly what to do, and will validate that you've correctly copied the options from your migration source.
@@ -152,3 +156,13 @@ If you run into SSL connection errors and you are unable to set your proxy setti
 export NODE_TLS_REJECT_UNAUTHORIZED=0 # setting an environment variable in bash
 $Env:NODE_TLS_REJECT_UNAUTHORIZED = 0 # setting an environment variable in PowerShell
 ```
+
+## Telemetry
+
+This extension includes basic, anonymous telemetry to give the maintainers information about real-world usage. This data is limited to:
+
+- The number of exports and imports being run
+- The versions of GitHub Enterprise Server being used
+- The versions of the extension currently in used
+
+You can disable all telemetry by specifying the `--disable-telemetry` argument.
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -20,6 +20,7 @@
     "chalk": "^5.3.0",
     "commander": "^11.1.0",
     "octokit": "^3.1.2",
+    "posthog-node": "^3.2.0",
     "semver": "^7.5.4",
     "undici": "^6.0.1",
     "winston": "^3.11.0"

diff --git a/src/commands/export.ts b/src/commands/export.ts
@@ -1,5 +1,6 @@
 import * as commander from 'commander';
 import { existsSync, writeFileSync } from 'fs';
+import crypto from 'crypto';
 import { type Octokit } from 'octokit';
 import semver from 'semver';
 
@@ -13,6 +14,8 @@ import {
   MINIMUM_SUPPORTED_GITHUB_ENTERPRISE_SERVER_VERSION_FOR_EXPORTS,
   getGitHubProductInformation,
 } from '../github-products.js';
+import { PostHog } from 'posthog-node';
+import { POSTHOG_API_KEY, POSTHOG_HOST } from '../posthog.js';
 
 const command = new commander.Command();
 const { Option } = commander;
@@ -25,6 +28,7 @@ enum ProjectOwnerType {
 interface Arguments {
   accessToken?: string;
   baseUrl: string;
+  disableTelemetry: boolean;
   projectOutputPath: string;
   repositoryMappingsOutputPath: string;
   projectOwner: string;
@@ -394,11 +398,17 @@ command
     process.env.EXPORT_PROXY_URL,
   )
   .option('--verbose', 'Emit detailed, verbose logs', false)
+  .option(
+    '--disable-telemetry',
+    'Disable anonymous telemetry that gives the maintainers of this tool basic information about real-world usage. For more detailed information about the built-in telemetry, see the readme at https://github.com/timrogers/gh-migrate-project.',
+    false,
+  )
   .action(
     actionRunner(async (opts: Arguments) => {
       const {
         accessToken: accessTokenFromArguments,
         baseUrl,
+        disableTelemetry,
         projectNumber,
         projectOutputPath,
         projectOwner,
@@ -408,6 +418,8 @@ command
         verbose,
       } = opts;
 
+      const posthog = new PostHog(POSTHOG_API_KEY, { host: POSTHOG_HOST });
+
       const accessToken = accessTokenFromArguments || process.env.EXPORT_GITHUB_TOKEN;
 
       if (!accessToken) {
@@ -461,6 +473,18 @@ command
         logger.info(`Running export in GitHub.com mode`);
       }
 
+      if (!disableTelemetry) {
+        posthog.capture({
+          distinctId: crypto.randomUUID(),
+          event: 'export_start',
+          properties: {
+            github_enterprise_server_version: gitHubEnterpriseServerVersion,
+            is_github_enterprise_server: isGitHubEnterpriseServer,
+            version: VERSION,
+          },
+        });
+      }
+
       logger.info(
         `Looking up ID for project ${projectNumber} owned by ${projectOwnerType} ${projectOwner}...`,
       );
@@ -507,6 +531,8 @@ command
       logger.info(
         `Successfully wrote repositories mappings CSV to ${repositoryMappingsOutputPath}`,
       );
+
+      await posthog.shutdownAsync();
       process.exit(0);
     }),
   );