Skip to content

TELEMETRY-JS-EXAMPLE.md

Latest commit

 

History

History
278 lines (227 loc) · 5.7 KB

TELEMETRY-JS-EXAMPLE.md

File metadata and controls

278 lines (227 loc) · 5.7 KB

JavaScript/TypeScript SDK Telemetry - Complete Implementation

✅ What Was Implemented

The JavaScript/TypeScript SDK now automatically sends telemetry data to your backend endpoint after every encrypt/decrypt operation.

📡 Telemetry Endpoint

POST http://192.168.18.96:3000/api/sdk/telemetry

📊 Data Sent

{
  "sdkId": "e81276c4-740f-46cf-b35f-8cc25ec05642",
  "operation": "encrypt",
  "algorithm": "aes-256-gcm",
  "duration": 12,
  "success": true,
  "inputSize": 1024,
  "outputSize": 1088,
  "metadata": {
    "platform": "nodejs",
    "deviceInfo": {
      "os": "linux",
      "arch": "x64",
      "nodeVersion": "v18.17.0"
    },
    "networkInfo": {
      "endpoint": "http://192.168.18.96:3000/api/sdk/telemetry"
    }
  }
}

🔧 How It Works

1. TelemetryClient Initialization

When the SDK loads, it automatically creates a telemetry client:

const telemetryClient = new TelemetryClient();

The client reads configuration from hardcoded SDK metadata:

  • sdkId - From database
  • telemetryEnabled - true/false
  • telemetryEndpoint - Your backend URL

2. Automatic Tracking

Every encrypt/decrypt operation is automatically tracked:

// User code
const crypto = new AveroxCrypto(masterKey);
const envelope = await crypto.encrypt(plaintext, aad);

// Behind the scenes:
// 1. Start timer
// 2. Perform encryption
// 3. Send telemetry (non-blocking)
// 4. Return result

3. Non-Blocking Execution

Telemetry is sent asynchronously and never blocks crypto operations:

// Send asynchronously without blocking
this.sendAsync(telemetryData).catch(() => {
  // Silent failure - telemetry should never break crypto operations
});

📝 Example Telemetry Events

Successful Encryption

{
  "sdkId": "e81276c4-740f-46cf-b35f-8cc25ec05642",
  "operation": "encrypt",
  "algorithm": "aes-256-gcm",
  "duration": 12,
  "success": true,
  "inputSize": 1024,
  "outputSize": 1088,
  "metadata": {
    "platform": "nodejs",
    "deviceInfo": {
      "os": "win32",
      "arch": "x64",
      "nodeVersion": "v20.10.0"
    },
    "networkInfo": {
      "endpoint": "http://192.168.18.96:3000/api/sdk/telemetry"
    }
  }
}

Successful Decryption

{
  "sdkId": "e81276c4-740f-46cf-b35f-8cc25ec05642",
  "operation": "decrypt",
  "algorithm": "aes-256-gcm",
  "duration": 8,
  "success": true,
  "inputSize": 1088,
  "outputSize": 1024,
  "metadata": {
    "platform": "nodejs",
    "deviceInfo": {
      "os": "darwin",
      "arch": "arm64",
      "nodeVersion": "v18.17.0"
    },
    "networkInfo": {
      "endpoint": "http://192.168.18.96:3000/api/sdk/telemetry"
    }
  }
}

Failed Operation

{
  "sdkId": "e81276c4-740f-46cf-b35f-8cc25ec05642",
  "operation": "decrypt",
  "algorithm": "aes-256-gcm",
  "duration": 5,
  "success": false,
  "inputSize": 1088,
  "outputSize": 0,
  "metadata": {
    "platform": "nodejs",
    "deviceInfo": {
      "os": "linux",
      "arch": "x64",
      "nodeVersion": "v18.17.0"
    },
    "networkInfo": {
      "endpoint": "http://192.168.18.96:3000/api/sdk/telemetry"
    }
  }
}

🚀 Testing

1. Generate a New SDK

# In your backend, create SDK with telemetry enabled
POST /api/sdks
{
  "name": "Test SDK",
  "version": "2.0.0",
  "languages": ["javascript"],
  "telemetryEnabled": true,
  "telemetryEndpoint": "http://192.168.18.96:3000/api/sdk/telemetry"
}

2. Download and Extract SDK

GET /api/sdks/{sdk-id}/download

3. Use the SDK

import { AveroxCrypto } from './src/index';

const masterKey = AveroxCrypto.generateMasterKey();
const crypto = new AveroxCrypto(masterKey);

// Encrypt - telemetry sent automatically
const envelope = await crypto.encrypt(
  Buffer.from('Secret data'),
  Buffer.from('user-123')
);

// Decrypt - telemetry sent automatically
const plaintext = await crypto.decrypt(
  envelope,
  Buffer.from('user-123')
);

4. Check Backend Logs

Your backend should receive telemetry events:

POST /api/sdk/telemetry
{
  "sdkId": "e81276c4-740f-46cf-b35f-8cc25ec05642",
  "operation": "encrypt",
  "duration": 12,
  "success": true,
  ...
}

🔒 Privacy & Security

What is NOT Sent

  • ❌ Plaintext data
  • ❌ Ciphertext data
  • ❌ Encryption keys
  • ❌ AAD (Additional Authenticated Data)
  • ❌ IVs or authentication tags

What IS Sent

  • ✅ SDK ID (links to database)
  • ✅ Operation type (encrypt/decrypt)
  • ✅ Algorithm used
  • ✅ Duration (milliseconds)
  • ✅ Success/failure status
  • ✅ Data sizes (bytes)
  • ✅ Platform info (OS, architecture, Node version)

⚙️ Configuration

Enable/Disable Telemetry

At SDK Generation Time:

const sdk = {
  sdkId: "e81276c4-740f-46cf-b35f-8cc25ec05642",
  name: "My SDK",
  version: "2.0.0",
  telemetryEnabled: true,  // ← Enable/disable
  telemetryEndpoint: "http://192.168.18.96:3000/api/sdk/telemetry"
};

Hardcoded in Generated SDK:

const SDK_METADATA: SDKMetadata = {
  sdkId: "e81276c4-740f-46cf-b35f-8cc25ec05642",
  telemetryEnabled: true,  // ← Baked into code
  telemetryEndpoint: "http://192.168.18.96:3000/api/sdk/telemetry",
  // ...
};

✅ Summary

Implemented Features:

  • ✅ Automatic telemetry tracking
  • ✅ Non-blocking async execution
  • ✅ Silent failure handling
  • ✅ Performance timing
  • ✅ Success/failure tracking
  • ✅ Input/output size tracking
  • ✅ Platform/device info collection
  • ✅ 5-second timeout
  • ✅ Privacy-preserving (no sensitive data)

Next Steps:

  1. Generate a new SDK to test telemetry
  2. Verify telemetry events arrive at your backend
  3. Implement similar telemetry in Python/Go SDKs

The JavaScript/TypeScript SDK telemetry is production-ready! 🎉