Control CoreDocs

👁️ Telemetry Management

This guide explains how to configure and manage telemetry data transmission to Control Core License Server, including connection settings, security options, and troubleshooting.

📌 Overview

Telemetry data is automatically collected from your Control Core deployment and transmitted to the License Server for:

  • Subscription Verification: Verifying your subscription status
  • Usage Tracking: Tracking bouncer pairs and policy decisions
  • License Management: Managing trial periods and feature access
  • Support: Providing usage data for support and troubleshooting

👁️ Accessing Telemetry Settings

  1. Log in to the Control Core admin console
  2. Navigate to Settings → General
  3. Click on the Telemetry tab

📌 Configuring License Server Connection

Step 1: Configure License Admin URL

  1. In the Control Core License Connection section
  2. Enter the License Admin URL (e.g., https://business-admin.controlcore.io)
  3. This is the endpoint where telemetry data will be sent

Note: The URL is provided by Control Core during setup.

Step 2: Configure API Key

  1. Enter your API Key in the API Key field
  2. The API key authenticates your Control Plane with the License Server
  3. Click Show to reveal the API key (if already configured)

Security: The API key is encrypted and stored securely in the database.

Step 3: Test Connection

  1. Click Test License Admin URL Connection button
  2. Wait for connection test to complete
  3. Review the result:
    • Success: Connection is working correctly
    • Failed: Check URL and API key, verify network connectivity

Step 4: Save Configuration

  1. Click Save to store your configuration
  2. Configuration is saved immediately
  3. Telemetry transmission will begin automatically if enabled

📌 Transmission Settings

Transmission Frequency

Configure how often telemetry data is sent to the License Server:

  • Twice Monthly (Default): 1st and 15th of each month at 2 AM UTC
  • Weekly: Every Monday at 2 AM UTC
  • Monthly: 1st of each month at 2 AM UTC
  • Daily: Every day at 2 AM UTC

Recommendation: Twice monthly is sufficient for most deployments and reduces network overhead.

Enable Telemetry

Toggle Enable Telemetry to:

  • ON: Telemetry data is collected and transmitted
  • OFF: Telemetry is disabled (not recommended for production)

Note: Disabling telemetry will prevent License Server connection and disable feature gating.

🔒 Security Settings

Data Encryption

Enable Data Encryption (Recommended: ON)

When enabled:

  • Telemetry payload is encrypted using AES-256 encryption
  • Data is encrypted before transmission
  • License Server decrypts data using shared secret

Security Benefit: Protects sensitive usage data during transmission.

PII Anonymization

Enable PII Anonymization (Recommended: ON)

When enabled:

  • Customer IDs are hashed/anonymized
  • No personally identifiable information is transmitted
  • Complies with GDPR and privacy regulations

Security Benefit: Ensures no PII is exposed in telemetry data.

Local Data Retention

Configure how long telemetry data is retained locally:

  • 7 days: Minimum retention
  • 30 days (Default): Recommended for troubleshooting
  • 90 days: Extended retention for compliance
  • 365 days: Maximum retention

Note: Data older than retention period is automatically purged.

👁️ Viewing Telemetry Data

Current Period Data Preview

The Current Period Data Preview section shows:

  • Total Events: Total audit log events in current period
  • Sandbox Events: Events from sandbox environment
  • Production Events: Events from production environment
  • Active Bouncers: Number of active bouncers reporting
  • Policy Decisions: Number of policy evaluation decisions
  • Health Status: Overall system health indicator

Note: If no bouncers are configured, preview will show zero values.

Transmission History

View past telemetry transmissions:

  1. Scroll to Transmission History section
  2. Review transmission log entries:
    • Date: Transmission date
    • Status: Success or Failed
    • Records Sent: Number of records transmitted
    • Response Code: HTTP response code

Retrying Failed Transmissions

If a transmission fails:

  1. Find the failed entry in Transmission History
  2. Click Retry button on the failed entry
  3. System will retry transmission with stored payload
  4. Check status after retry completes

📌 Manual Transmission

Triggering Manual Transmission

To send telemetry data immediately:

  1. Click Send Now button in Transmission Settings section
  2. System will:
    • Aggregate current period data
    • Apply encryption/anonymization (if enabled)
    • Transmit to License Server
    • Log transmission result

Use Cases:

  • Testing telemetry configuration
  • Sending data before scheduled transmission
  • Troubleshooting transmission issues

👁️ Monitoring Telemetry Health

Health Status Indicators

The telemetry system provides health indicators:

  • Healthy: Connection active, recent successful transmission
  • Warning: Connection active but last transmission > 7 days ago
  • Unhealthy: Connection failed or transmission errors
  • Disabled: Telemetry is disabled
  • Not Configured: License Server connection not configured

Checking Health Status

  1. Navigate to Settings → General → Telemetry
  2. Review Current Period Data Preview for health status
  3. Check Transmission History for recent errors
  4. Use Test Connection to verify connectivity

🛠️ Troubleshooting

Connection Test Fails

Issue: "Test License Admin URL Connection" returns failure

Solutions:

  1. Verify License Admin URL is correct (check for typos)
  2. Verify API key is correct and not expired
  3. Check network connectivity (firewall, proxy settings)
  4. Verify License Server is accessible from your network
  5. Check backend logs for detailed error messages

No Telemetry Data Available

Issue: "Current Period Data Preview" shows zero values

Possible Causes:

  • No bouncers are configured or connected
  • No audit log events in current period
  • Telemetry aggregation service not running

Solutions:

  1. Verify bouncers are registered and active
  2. Check that policies are being evaluated (generates audit logs)
  3. Verify telemetry is enabled
  4. Check backend logs for aggregation errors

Transmission Failures

Issue: Transmissions are failing in history

Solutions:

  1. Check Error Details in transmission history entry
  2. Verify License Server is accessible
  3. Check API key is valid and not expired
  4. Review backend logs for detailed error messages
  5. Try manual transmission to test current configuration

Encryption/Anonymization Errors

Issue: Errors related to encryption or anonymization

Solutions:

  1. Verify encryption keys are configured correctly
  2. Check that encryption/anonymization settings match License Server
  3. Review backend logs for encryption errors
  4. Contact support if issue persists

📌 Best Practices

Security Recommendations

  1. Always Enable Encryption: Protect data in transit
  2. Always Enable Anonymization: Comply with privacy regulations
  3. Use Strong API Keys: Rotate keys periodically
  4. Monitor Transmission History: Review for failures regularly

Performance Recommendations

  1. Use Twice Monthly Frequency: Reduces network overhead
  2. Set Appropriate Retention: Balance storage vs. troubleshooting needs
  3. Monitor Health Status: Address issues promptly

Compliance Recommendations

  1. Enable PII Anonymization: Required for GDPR compliance
  2. Set Retention Policies: Comply with data retention requirements
  3. Audit Transmission Logs: Maintain audit trail