Traffic Accounting and Billing Cycles

Dash builds traffic statistics from network counters reported by nodes. The system stores raw inbound and outbound counters; the accounting view is determined by direction mode.

Modes

Mode	Value	Behavior
Lite	lite	Stores monthly inbound/outbound totals and estimated peaks from recent raw NIC samples
Billing	billing	Maintains current 5-minute facts, daily summaries, P95, coverage, and monthly snapshots

GET /api/statistics/traffic/daily is available only in billing mode. Otherwise it returns 409 traffic_daily_requires_billing.

Global Settings

Field	Description
guest_access_mode	Anonymous access mode
usage_mode	lite or billing
cycle_mode	Billing cycle mode
billing_start_day	Day from 1 to 31
billing_anchor_date	WHMCS anchor date
billing_timezone	IANA timezone
direction_mode	Accounting direction mode

Billing Cycle Modes

Mode	Behavior
calendar_month	Calendar month, billing_start_day=1
clamp_to_month_end	Starts on configured day; short months clamp to month end
whmcs_compatible	WHMCS-compatible cycle; can use billing_anchor_date

billing_anchor_date accepts YYYY-MM-DD or RFC3339 and is stored as YYYY-MM-DD.

billing_timezone must be an IANA timezone loadable by Go.

Node Override

Nodes can override the global billing cycle and direction mode:

Field	Description
traffic_cycle_mode	default inherits global settings; otherwise one of the cycle modes
traffic_billing_start_day	1 to 31
traffic_billing_anchor_date	WHMCS anchor date
traffic_billing_timezone	Node billing timezone
traffic_direction_mode	default inherits the global direction; otherwise out, both, or max
traffic_p95_enabled	Whether P95 is calculated for the node

Normalization:

• default clears node billing fields and inherits global settings.
• calendar_month stores traffic_billing_start_day=1.
• Non-whmcs_compatible modes store an empty traffic_billing_anchor_date.
• Empty traffic_billing_timezone in non-default mode uses the app timezone on read.
• traffic_direction_mode=default inherits the global direction mode; out, both, and max override that node.

Direction Mode

Mode	Accounting view
out	Outbound only
both	Inbound + outbound
max	Larger value from inbound and outbound for each metric

Global direction_mode is the default accounting view. Nodes with traffic_direction_mode=default inherit it.

Responses keep raw fields and expose selected view fields such as selected_bytes, selected_peak_bytes_per_sec, and selected_p95_bytes_per_sec.

Background Service

The background service turns raw counters reported by nodes into traffic facts and monthly accounting output. Its write path is:

• Upserts derivable 5-minute facts from recent raw samples every 5 minutes.
• Updates recent monthly usage during materialization.
• Refreshes monthly snapshots hourly.
• Runs serially with manual 5-minute fact rebuilds.

traffic_retention_days controls the 5-minute fact retention window and the fact range available to manual rebuilds. traffic_5m stays writable and old rows are removed by rolling retention; historical 95th percentile billing values live in monthly snapshots.

Manual Rebuild

When retained facts need to be generated again, the admin console can start a per-node traffic rebuild. The task rewrites the node's 5-minute facts from retained raw nic_metrics and invalidates overlapping monthly snapshots. Rebuild state is process-local and is not durable across process restarts. If the task fails, affected monthly history is regenerated by later snapshot maintenance, computed from retained facts on reads, or restored by retrying the rebuild; data outside retention is not recovered automatically.