Merge pull request #563 from SquirrelCorporation/feat-telemetry

[FEAT] Add telemetry support for anonymized usage tracking

.env

@@ -1,14 +1,16 @@
-#SECRETS
+# SECRETS
 SECRET=REPLACE_ME
 SALT=1234567890123456
 VAULT_PWD=REPLACE_ME
-#MONGO
+# MONGO
 DB_HOST=mongo
 DB_NAME=ssm
 DB_PORT=27017
-#REDIS
+# REDIS
 REDIS_HOST=redis
 REDIS_PORT=6379
-#SSM CONFIG
+# SSM CONFIG
 #SSM_INSTALL_PATH=/opt/squirrelserversmanager
-#SSM_DATA_PATH=/data
+#SSM_DATA_PATH=/data
+# TELEMETRY
+TELEMETRY_ENABLED=true

.env.dev

@@ -1,14 +1,16 @@
-#SECRETS
+# SECRETS
 SECRET=REPLACE_ME
 SALT=1234567890123456
 VAULT_PWD=REPLACE_ME
-#MONGO
+# MONGO
 DB_HOST=mongo
 DB_NAME=ssm
 DB_PORT=27017
 #REDIS
 REDIS_HOST=redis
 REDIS_PORT=6379
-#SSM CONFIG
+# SSM CONFIG
 #SSM_INSTALL_PATH=/opt/squirrelserversmanager
-#SSM_DATA_PATH=/data
+#SSM_DATA_PATH=/data
+# TELEMETRY
+TELEMETRY_ENABLED=true

README.md

@@ -70,6 +70,13 @@ See [Troubleshoot](https://squirrelserversmanager.io/docs/technical-guide/troubl
 ![Device Info](./site/public/home/device-info.png)
 ![New Device](./site/public/home/new-device.png)
 
+---
+## Disabling Anonymized Telemetry
+
+By default, SSM automatically reports anonymized basic usage statistics. This helps us understand how SSM is used and track its overall usage and growth. This data does not include any sensitive information. To disable anonymized telemetry, follow these steps:
+
+Set `TELEMETRY_ENABLED` to `false` in your `.env` file.
+
 ---
 
 **Note:**

server/package.json

@@ -56,7 +56,8 @@
     "socket.io": "^4.8.1",
     "multer": "^1.4.5-lts.1",
     "js-yaml": "^4.1.0",
-    "passport-mock-strategy": "^2.0.0"
+    "passport-mock-strategy": "^2.0.0",
+    "posthog-node": "^4.3.2"
   },
   "overrides": {
     "minimatch": "5.1.2",

server/src/config.ts

@@ -18,3 +18,4 @@ export const VAULT_PWD = process.env.VAULT_PWD || '';
 export const SESSION_DURATION = parseInt(process.env.SESSION_DURATION || '86400000');
 export const SSM_INSTALL_PATH = process.env.SSM_INSTALL_PATH || '/opt/squirrelserversmanager';
 export const SSM_DATA_PATH = process.env.SSM_DATA_PATH || '/data';
+export const TELEMETRY_ENABLED = process.env.TELEMETRY_ENABLED === 'true';

server/src/controllers/rest/user/login.ts

@@ -4,9 +4,11 @@ import { SECRET, SESSION_DURATION } from '../../../config';
 import UserRepo from '../../../data/database/repository/UserRepo';
 import { AuthFailureError } from '../../../middlewares/api/ApiError';
 import { SuccessResponse } from '../../../middlewares/api/ApiResponse';
+import Telemetry from '../../../modules/telemetry';
 
 export const login = async (req, res, next) => {
   const { password, username } = req.body;
+  Telemetry.capture('user login');
   if (!password || !username) {
     res.status(401).send({
       data: {

server/src/controllers/rest/user/user.ts

@@ -9,6 +9,7 @@ import logger from '../../../logger';
 import { AuthFailureError } from '../../../middlewares/api/ApiError';
 import { SuccessResponse } from '../../../middlewares/api/ApiResponse';
 import { createADefaultLocalUserRepository } from '../../../modules/repository/default-playbooks-repositories';
+import Telemetry from '../../../modules/telemetry';
 import DashboardUseCase from '../../../services/DashboardUseCase';
 import DeviceUseCases from '../../../services/DeviceUseCases';
 
@@ -99,6 +100,7 @@ export const getCurrentUser = async (req, res) => {
 
 export const createFirstUser = async (req, res) => {
   const { email, password, name, avatar } = req.body;
+  Telemetry.capture('user signed up');
   const hasUser = (await UserRepo.count()) > 0;
   if (hasUser) {
     throw new AuthFailureError('Your instance already has a user, you must first connect');

server/src/core/startup/index.ts

@@ -19,6 +19,7 @@ import ContainerCustomStacksRepositoryEngine from '../../modules/repository/Cont
 import { createADefaultLocalUserRepository } from '../../modules/repository/default-playbooks-repositories';
 import PlaybooksRepositoryEngine from '../../modules/repository/PlaybooksRepositoryEngine';
 import sshPrivateKeyFileManager from '../../modules/shell/managers/SshPrivateKeyFileManager';
+import Telemetry from '../../modules/telemetry';
 import UpdateChecker from '../../modules/update/UpdateChecker';
 import ContainerRegistryUseCases from '../../services/ContainerRegistryUseCases';
 import { setAnsibleVersions } from '../system/ansible-versions';
@@ -51,10 +52,21 @@ class Startup {
     void AutomationEngine.init();
     void UpdateChecker.checkVersion();
     void ContainerCustomStacksRepositoryEngine.init();
+    void Telemetry.init();
   }
 
   private async updateScheme() {
     this.logger.warn('updateScheme - Scheme version differed, starting applying updates...');
+
+    try {
+      const installId = await getFromCache(SettingsKeys.GeneralSettingsKeys.INSTALL_ID);
+      if (!installId) {
+        await setToCache(SettingsKeys.GeneralSettingsKeys.INSTALL_ID, uuidv4());
+      }
+    } catch (error: any) {
+      this.logger.error(`Error settings installId: ${error.message}`);
+    }
+
     try {
       await PlaybookModel.syncIndexes();
       this.logger.info('PlaybookModel indexes synchronized successfully.');

server/src/index.ts

@@ -5,6 +5,7 @@ import Startup from './core/startup';
 import './middlewares/Passport';
 import Crons from './modules/crons';
 import app from './App';
+import Telemetry from './modules/telemetry';
 
 const start = () => {
   logger.info(`
@@ -34,6 +35,9 @@ export const restart = async () => {
   app.stopServer(start);
 };
 
+process.on('SIGINT', Telemetry.shutdown);
+process.on('SIGTERM', Telemetry.shutdown);
+
 /*process.on('uncaughtException', (err, origin) => {
   console.error('Unhandled exception. Please handle!', err.stack || err);
   console.error(`Origin: ${JSON.stringify(origin)}`);

server/src/modules/telemetry/index.ts

@@ -0,0 +1,42 @@
+import { PostHog } from 'posthog-node';
+import { SettingsKeys } from 'ssm-shared-lib';
+import { TELEMETRY_ENABLED } from '../../config';
+import { getFromCache } from '../../data/cache';
+import logger from '../../logger';
+
+class Telemetry {
+  private client;
+  private _id!: string;
+
+  constructor() {
+    this.client = new PostHog('phc_wJKUU2ssGzXxFferOrilvhErmTxvx8jZCf77PCW24JG', {
+      host: 'https://us.i.posthog.com',
+    });
+  }
+
+  public capture(eventName: string) {
+    if (TELEMETRY_ENABLED) {
+      this.client?.capture({ distinctId: this._id, event: eventName });
+    }
+  }
+
+  public async init() {
+    const installId = await getFromCache(SettingsKeys.GeneralSettingsKeys.INSTALL_ID);
+    if (!installId) {
+      logger.error('Install ID not found');
+    }
+    if (installId) {
+      this._id = installId;
+      this.client?.identify({ distinctId: this._id });
+    }
+    if (!TELEMETRY_ENABLED) {
+      await this.client?.optOut();
+    }
+  }
+
+  public async shutdown() {
+    await this.client?.shutdown();
+  }
+}
+
+export default new Telemetry();

shared-lib/src/enums/settings.ts

@@ -9,10 +9,11 @@ export enum GeneralSettingsKeys {
   DEVICE_STATS_RETENTION_IN_DAYS = 'device-stats-retention-in-days',
   CONTAINER_STATS_RETENTION_IN_DAYS = 'container-stats-retention-in-days',
   UPDATE_AVAILABLE = 'update-available',
+  INSTALL_ID = 'install-id',
 }
 
 export enum DefaultValue {
-  SCHEME_VERSION = '17',
+  SCHEME_VERSION = '18',
   SERVER_LOG_RETENTION_IN_DAYS = '30',
   CONSIDER_DEVICE_OFFLINE_AFTER_IN_MINUTES = '3',
   CONSIDER_PERFORMANCE_GOOD_MEM_IF_GREATER = '10',

site/docs/install/dockerless.md

@@ -150,6 +150,8 @@ REDIS_PORT=6379
 # SSM CONFIG
 SSM_INSTALL_PATH=/opt/squirrelserversmanager
 SSM_DATA_PATH=/opt/squirrelserversmanager/data
+# TELEMETRY
+TELEMETRY_ENABLED=true
 EOF
 ```
 

site/docs/quickstart.md

@@ -103,6 +103,8 @@ DB_PORT=27017
 #REDIS
 REDIS_HOST=redis
 REDIS_PORT=6379
+#TELEMETRY
+TELEMETRY_ENABLED=true
 ```
 Replace the values of "SECRET", "SALT", and "VAULT_PWD"
 
@@ -125,4 +127,11 @@ docker compose up
 ---
 
 ### Other install methods:
-To manually build the project your self, see this [section](/docs/technical-guide/manual-install-ssm)
+To manually build the project your self, see this [section](/docs/technical-guide/manual-install-ssm)
+
+---
+### Disabling Anonymized Telemetry
+
+By default, SSM automatically reports anonymized basic usage statistics. This helps us understand how SSM is used and track its overall usage and growth. This data does not include any sensitive information. To disable anonymized telemetry, follow these steps:
+
+Set `TELEMETRY_ENABLED` to `false` in your `.env` file.