Documentation
¶
Overview ¶
Package boundaryusage tracks workspace boundary usage for telemetry reporting. The design intent is to track trends and rough usage patterns.
Each replica does in-memory usage tracking. Boundary usage is inferred at the control plane when workspace agents call the ReportBoundaryLogs RPC. Accumulated stats are periodically flushed to a database table keyed by replica ID. Telemetry aggregates are computed across all replicas when generating snapshots.
Aggregate Precision:
The aggregated stats represent approximate usage over roughly the telemetry snapshot interval, not a precise time window. This imprecision arises because:
- Each replica flushes independently, so their data covers slightly different time ranges (varying by up to the flush interval)
- Unflushed in-memory data at snapshot time rolls into the next period
- The snapshot captures "data flushed since last reset" rather than "usage during exactly the last N minutes"
We accept this imprecision to keep the architecture simple. Each replica operates independently and flushes to the database on their own schedule. This approach also minimizes database load. The table contains at most one row per replica, so flushes are just upserts, and resets only delete N rows. There's no accumulation of historical data to clean up. The only synchronization is a database lock that ensures exactly one replica reports telemetry per period.
Known Shortcomings:
- Unique workspace/user counts may be inflated when the same workspace or user connects through multiple replicas, as each replica tracks its own unique set
- Ad-hoc boundary usage in a workspace may not be accounted for e.g. if the boundary command is invoked directly with the --log-proxy-socket-path flag set to something other than the Workspace agent server.
Implementation:
The Tracker maintains sets of unique workspace IDs and user IDs, plus request counters. When boundary logs are reported, Track() adds the IDs to the sets and increments request counters.
FlushToDB() writes stats to the database only when there's been new activity since the last flush. This prevents stale data from being written after a telemetry reset when no new usage occurred. Stats accumulate in memory throughout the telemetry period.
A new period is detected when the upsert results in an INSERT (meaning telemetry deleted the replica's row). At that point, all in-memory stats are reset so they only count usage within the new period.
Below is a sequence diagram showing the flow of boundary usage tracking.
┌───────┐ ┌───────────────┐ ┌──────────┐ ┌────┐ ┌───────────┐
│ Agent │ │BoundaryLogsAPI│ │ Tracker │ │ DB │ │ Telemetry │
└───┬───┘ └───────┬───────┘ └────┬─────┘ └──┬─┘ └─────┬─────┘
│ │ │ │ │
│ ReportBoundaryLogs│ │ │ │
├──────────────────►│ │ │ │
│ │ Track(...) │ │ │
│ ├────────────────►│ │ │
│ : │ │ │ │
│ : │ │ │ │
│ ReportBoundaryLogs│ │ │ │
├──────────────────►│ │ │ │
│ │ Track(...) │ │ │
│ ├────────────────►│ │ │
│ │ │ │ │
│ │ │ FlushToDB │ │
│ │ ├────────────►│ │
│ │ │ : │ │
│ │ │ : │ │
│ │ │ FlushToDB │ │
│ │ ├────────────►│ │
│ │ │ │ │
│ │ │ │ Snapshot │
│ │ │ │ interval │
│ │ │ │◄───────────┤
│ │ │ │ Aggregate │
│ │ │ │ & Reset │
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker tracks boundary usage for telemetry reporting.
Unique user/workspace counts are tracked both cumulatively and as deltas since the last flush. The delta is needed because when a new telemetry period starts (the DB row is deleted), we must only insert data accumulated since the last flush. If we used cumulative values, stale data from the previous period would be written to the new row and then lost when subsequent updates overwrite it.
Request counts are tracked as deltas and accumulated in the database.
func (*Tracker) FlushToDB ¶
FlushToDB writes stats to the database. For unique counts, cumulative values are used on UPDATE (replacing the DB value) while delta values are used on INSERT (starting fresh). Request counts are always deltas, accumulated in DB. All deltas are reset immediately after snapshot so Track() calls during the DB operation are preserved for the next flush.
func (*Tracker) StartFlushLoop ¶
func (t *Tracker) StartFlushLoop(ctx context.Context, log slog.Logger, db database.Store, replicaID uuid.UUID)
StartFlushLoop begins the periodic flush loop that writes accumulated stats to the database. It blocks until the context is canceled. Flushes every minute to keep stats reasonably fresh for telemetry collection (which runs every 30 minutes by default) without excessive DB writes.
Source Files