Control CoreDocs

Telemetry Management

Audience: Control Core administrators, security & privacy reviewers Time: ~10 min read

This guide explains what telemetry Control Core collects, how it is transmitted to the License Server, and why each field is needed. It also covers configuration and troubleshooting.

Overview

Telemetry is the heartbeat between your Control Plane and the Control Core License Server. It is intentionally minimal: counts and license posture only — no policy content, no rule logic, no identifiable user data.

It is used for:

  • Subscription verification — confirming your trial / paid window is current
  • Bouncer-pair billing — pricing is per bouncer pair (sandbox + production)
  • License management — tracking remaining trial / paid days and renewals
  • Support — health signal so Control Core can spot stalled deployments early

What is collected (the only fields we send)

Important: the telemetry payload is locked at the schema level (extra='forbid'). Anything outside this list is rejected before the network call is made — see the Control Plane telemetry payload purity tests in your installation's source bundle.

FieldPurpose
customer_idStripe customer identifier (mapped from your installation)
instance_idControl Plane installation id (random UUID, no IP)
dateReporting day
bouncer_countActive bouncers reporting traffic
deployed_bouncer_countBouncers registered with the Control Plane
active_reporting_bouncer_countBouncers that emitted decisions in the window
policy_decision_countTotal decisions across all bouncers
total_eventsAudit events recorded (counts only)
successful_decisions, sandbox_events, production_eventsDecision splits (counts only)
health_status, deployment_version, tierOperational posture
days_remaining, license_status, telemetry_availabilityLicense window
bouncer_pairs.{total_pairs, sandbox_only_count, production_only_count, paired_count}Pair counts for billing
license_metrics.*License token connect / expiry / refresh booleans + ages
redeemed_extension_codescode_id values redeemed since last tick (single-use IDs only)
transmitted_atWallclock at send time

The License Server URL is not customer-configurable. It is baked into the Control Plane at deploy time and treated as an implementation detail. The UI shows only a License Server: connected badge.

What is NOT collected (and never will be)

  • Policy IDs, names, content, Rego source, or rule descriptions
  • Action names, action configurations, or webhook URLs
  • User identifiers, emails, IP addresses, or session tokens
  • Resource paths, request bodies, or response bodies
  • Any field not in the table above (rejected by extra='forbid')

How it is transmitted

  1. Aggregator scheduler builds a payload from your local DB (no audit log content)
  2. Payload is validated against the strict Pydantic schema (TelemetryAggregatePayload)
  3. The validated payload is HMAC-signed with your API key (X-Telemetry-Signature header)
  4. POST to the License Server over TLS 1.2+
  5. Result is recorded in telemetry_transmission_logs (success / failure / response code)

If transmission fails the next tick replays the same data — including any redeemed_extension_codes — until it succeeds.

Why we collect this

WhyWhich fields
Verify subscription is paid / in-trialtier, license_status, days_remaining, license_metrics.*
Charge per bouncer pairbouncer_count, bouncer_pairs.*
Spot stalled / unhealthy installs earlyhealth_status, telemetry_availability, license_metrics.telemetry_last_*
Confirm extension codes are redeemedredeemed_extension_codes
Decision-volume sanity check (no content)policy_decision_count, total_events, *_events counts

Accessing Telemetry Settings

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

Configuring the License Server connection

There is exactly one field you can configure: the API key. The URL is server-managed and not displayed.

Step 1: 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 at rest using the Control Plane's ENCRYPTION_KEY. Production deployments must set ENCRYPTION_KEY (and CREDENTIAL_ENCRYPTION_KEY) explicitly — the service refuses to start with ephemeral keys outside DEMO_MODE=true.

Step 2: Test Connection

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

Step 3: Save Configuration

  1. Click Save to store your configuration
  2. Configuration is saved immediately
  3. Telemetry transmission begins 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 Connection" returns failure

Solutions:

  1. Verify API key is correct and not expired
  2. Check outbound network connectivity (firewall, proxy settings)
  3. Verify the License Server is reachable from your network (the URL is server-managed and consistent across deployments)
  4. 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