Inside Atlassian's Forge Billing Architecture for Distributed Usage Tracking at Scale

Why Usage Tracking Is an Engineering Problem

Consumption pricing is easy to announce and hard to build. When Atlassian moved to bill Forge usage based on what apps actually consume, it took on a metering challenge that looks deceptively simple from the outside and turns out to be a serious distributed systems problem underneath. The company has now detailed the architecture behind Forge Billing, and it reads as a blueprint for any platform contemplating the same shift.

The signals being tracked are varied: function invocations, storage consumption and operational telemetry, all generated across a distributed estate of developer apps. Each of those has different volume, timing and accuracy characteristics, and turning that heterogeneous stream into a number a customer can be billed for, and trust, is where the real engineering lives. For technology leaders, the lesson is that usage-based pricing is an infrastructure commitment, not a billing configuration.

The Usage Tracking Service as Nervous System

At the center of the design sits the Usage Tracking Service, which Atlassian describes as "UTS (Usage Tracking Service), which acts as the nervous system for Forge Billing." The metaphor is apt. UTS is responsible for validation, normalization, enrichment and event preparation, taking raw and inconsistent signals from across the platform and turning them into a clean, consistent stream that downstream billing logic can rely on.

Centralizing these responsibilities is a deliberate architectural choice. By concentrating validation and normalization in one service, Atlassian avoids scattering fragile metering logic across every component that emits usage, which is how billing systems become inconsistent and untrustworthy. A single authoritative path for usage data is what lets the rest of the system reason about consumption with confidence, and it gives the organization one place to evolve the rules.

Streaming and Schema Validation

Forge Billing is built on Kafka-based streaming with schema validation. The streaming foundation is the natural fit for usage data, which arrives continuously and at high volume from many sources, and schema validation at ingestion is what keeps malformed or unexpected events from corrupting the billing pipeline downstream. Catching bad data early is far cheaper than reconciling incorrect invoices later.

A stream-processing engine then converts raw events into aggregated billing metrics. The aggregation is windowed and time-based, grouping events into intervals that map to how usage is actually billed. This is a well-trodden pattern in stream processing, but applying it to billing raises the stakes considerably, because errors here translate directly into money charged or revenue lost. The choice of streaming over batch reflects the need to keep usage data current rather than reconciling it after the fact.

The Attribution Challenge

The hardest part, by Atlassian's own account, is not moving the data but making sense of it. The company notes that the "key complexity here is attribution and shape: every event must be attributed to the right entitlement/subscription context." Attribution is the unglamorous core of any metering system, and it is where consumption billing most often goes wrong in practice.

Getting attribution right means every function invocation and byte of storage must be tied back to the correct app, customer and subscription, and the shape of each event has to be consistent enough to aggregate reliably. In a distributed platform with many apps and many billing contexts, this is genuinely difficult, and it is precisely the kind of detail that determines whether customers trust their invoices. We see attribution as the make-or-break property of the entire architecture.

Layered Storage for Speed and Auditability

Atlassian's storage design reflects two competing requirements that a single store cannot satisfy well. The system uses immutable long-term storage for auditability alongside a low-latency analytical layer for near-real-time developer visibility. The immutable layer provides the durable, tamper-resistant record needed to defend any charge, while the analytical layer gives developers timely insight into their own consumption.

Separating these concerns is a smart pattern that other platforms should note. Auditability demands durability and immutability, while developer-facing dashboards demand speed and queryability, and trying to serve both from one store usually compromises both. By layering storage, Atlassian can guarantee an authoritative billing record without sacrificing the responsiveness that makes usage data actionable for the developers being billed.

Lessons for Any Consumption-Priced Platform

The architecture also supports per-app tracking and consolidated billing across developer spaces, which matters because real customers rarely use a single app in isolation. The ability to meter granularly while presenting a coherent, consolidated bill is what makes consumption pricing workable for enterprise buyers who need both detail and a single number to reconcile.

For any organization weighing a move to consumption pricing, Forge Billing is a cautionary and instructive example in equal measure. It shows that accurate metering at scale requires streaming infrastructure, disciplined schema validation, rigorous attribution and a thoughtfully layered storage strategy. The takeaway for executives is that the pricing model is the easy decision; the metering platform that makes it accurate, auditable and trustworthy is the hard, and far more consequential, engineering investment.