Skip to main content

Manage Telemetry

BillManager can send aggregate usage data for self-hosted instances. Each submission includes a persistent instance UUID.

This page lists the payload and the controls that stop transmission.

The TELEMETRY_ENABLED environment variable defaults to true. This setting enables the telemetry service.

A new instance keeps telemetry consent in the pending state. It sends no telemetry until an account owner selects Accept & Continue.

An account owner can select Opt Out instead. This choice keeps the instance consent in the disabled state.

Set TELEMETRY_ENABLED=false to disable telemetry for the full instance, regardless of the saved consent state.

TELEMETRY_ENABLED=false

When telemetry is enabled, BillManager creates the instance UUID before you accept or decline the notice. It sends nothing while consent is pending.

An account owner can change the saved consent state with an authenticated API request.

  • Send POST /api/v2/telemetry/accept to enable submissions.
  • Send POST /api/v2/telemetry/opt-out to disable submissions.

The web notice only appears while consent is pending. The environment switch overrides the saved consent state.

Data That BillManager Sends​

For a self-hosted instance, each submission contains:

  • A persistent instance UUID, the BillManager version, and the deployment mode.
  • The first user creation time and the submission time.
  • Counts of users, regular users, administrators, account owners, and users active during the last 30 days.
  • Counts of Bill Groups, bills, active bills, archived bills, and payments.
  • Counts for auto-pay, variable bills, deposits, expenses, and registered mobile devices.
  • Auto-pay and variable-bill percentages when the instance has bills.
  • Mobile-device counts by platform.
  • The average bills per nonempty Bill Group and the number of Bill Groups with bills.
  • The Python version, operating system, operating-system release, architecture, database version, and deployment method.

The self-hosted JSON payload excludes the server URL and public-IP fields. It also excludes:

  • Names, email addresses, or postal addresses.
  • Bill names, descriptions, amounts, or other financial values.
  • Payment history or payment dates.
  • Individual login times.

Telemetry is separate from the optional crash reporting and product analytics settings.

Send Schedule​

BillManager schedules the first attempt five minutes after startup. It schedules later attempts each day at 02:00 UTC.

By default, a successful send blocks scheduled duplicates for 20 hours. A retryable failure allows three total attempts with bounded delays.

Use TELEMETRY_MIN_SEND_INTERVAL_HOURS to change the duplicate-send interval. Use TELEMETRY_SEND_ATTEMPTS to change the total attempts.

Review Local Records​

BillManager records each final send result in the telemetry_log table.

After BillManager logs a submission, cleanup removes records older than 90 days by default. Cleanup always preserves the latest record.

Each server process runs cleanup at most once each day. Disabling telemetry does not delete existing records.

Set TELEMETRY_LOCAL_LOG_RETENTION_DAYS to change the retention period.

Use this query to review recent results:

SELECT
  instance_id,
  version,
  deployment_mode,
  last_sent_at,
  send_successful,
  error_message
FROM telemetry_log
ORDER BY last_sent_at DESC;

Use this query to review the last saved payload:

SELECT metrics_snapshot
FROM telemetry_log
ORDER BY last_sent_at DESC
LIMIT 1;

Change the Destination​

Set TELEMETRY_URL to send telemetry to an endpoint that you control.

TELEMETRY_URL=https://example.com/telemetry

You can also set TELEMETRY_INSTANCE_ID to a stable UUID. BillManager ignores a value that is not a valid UUID and logs a warning. Use TELEMETRY_INSTANCE_ID_FILE to select the UUID file path.