The "cost" discussed earlier (Lessons 16, 42) is how much your LLM spent. This lesson is about a different ledger: how the Langfuse platform itselfmeters and charges you for using it. This is Langfuse Cloud-specific—the self-hosted version does not charge you, so you can read this lesson as "a look at how a managed service's billing is built".
Three focuses: Langfuse Cloud meters by observation count, uses an hourly scheduled job to report usage to Stripe for invoicing, and a money-critical concern—the "meter exactly once" idempotency design. Over-count and you anger customers, under-count and you lose money, so this metering's demand for "no duplicates, no misses" is stricter than any chain before it.
📋 Analogy
Cloud metering is like a residential "water meter + meter reader". Using the platform is like using water; the platform installs a meter that quietly counts by usage (usage events). The meter reader (an hourly scheduled job) shows up on time to read that hour's figure, reporting it to the billing company (Stripe), which rolls it into a monthly invoice.
The critical part: a reading must never duplicate, never miss. Read twice and your water bill doubles this month—an enraged customer; miss one and the platform gives away an hour of compute for free. So the reader clutches a "where did I read up to" ledger (a locked cron record), rigidly enforcing "each whole hour's usage is reported exactly once, no more, no less"—even if he dozes off mid-read, the network drops and he restarts, or two readers accidentally show up, this ledger keeps the books flawless.
The metering model: count observations hourly, report to Stripe
Langfuse Cloud bills by usage events. The metering job (handleCloudUsageMeteringJob) is driven by an hourly-triggered scheduled queue: for the just-passed whole hour, it counts each project's observation/trace/score counts from ClickHouse, aggregates by organization, and pushes them to Stripe's metering API — reporting two meters: tracing_observations (observation count only, legacy) and tracing_events (= trace + score + observation, the current billing unit), leaving Stripe to invoice.
usage metering → Stripe invoicing: handleCloudUsageMeteringJob hourly counts the past whole-hour interval via getObservation/Trace/ScoreCountsByProjectInCreationInterval from ClickHouse, aggregates by org, and for orgs with a cloudConfig.stripe.customerId calls meterEvents.create reporting two meters — tracing_observations(legacy) and tracing_events(=trace+score+obs) (backOff retry). Source: worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts.
The platform counts, Stripe invoices (structure from billing's getInvoices: subscription / usage / tax breakdown; amounts illustrative): usage is billed via tracing_events (trace+score+observation) — each project accumulates them hourly, then they aggregate per organization into a monthly total (1.24M obs illustrative on the left). At month end Stripe issues one invoice split into subscription (fixed plan fee), usage (Σevents × tiered unit price) and tax line items, charged as a total. This "metering separate from billing" boundary matters: the platform focuses on counting accurately, and hands the heavy, compliance-laden invoicing, tax and payments entirely to Stripe.
worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.tscount + report to Stripe
// 1) for the just-passed whole hour, count each project's usage from ClickHouseconst observationCounts = await getObservationCountsByProjectInCreationInterval({ start, end });
for (const org of organizations) { // only orgs with a stripe.customerIdconst countObservations = observationCounts/* …this org's projects */.reduce((s, p) => s + p.count, 0);
if (countObservations > 0) {
await backOff(() => // retry: guarantee eventual delivery
stripe.billing.meterEvents.create({
event_name: "tracing_observations",
timestamp: meterIntervalEnd.getTime() / 1000,
payload: { stripe_customer_id, value: countObservations.toString() } })); // legacy meter
}
// current billing unit: events = traces + scores + observationsconst countEvents = countScores + countTraces + countObservations;
if (countEvents > 0) await backOff(() =>
stripe.billing.meterEvents.create({ event_name: "tracing_events",
timestamp: meterIntervalEnd.getTime() / 1000,
payload: { stripe_customer_id, value: countEvents.toString() } }));
}
what's counted this hour
source
used for billing?
observation count
getObservationCountsByProjectInCreationInterval
yes — reported alone as tracing_observations(legacy), and summed into tracing_events
trace count
getTraceCounts…
yes — summed into tracing_events
score count
getScoreCounts…
yes — summed into tracing_events
All three are counted, and all three are billed: metering reports two meters — tracing_observations (observation count only, legacy, kept for backward compat) and tracing_events (trace + score + observation, the current billing unit). So trace and score counts do count toward billing (folded into tracing_events), not just internal stats. The billing unit evolved from "observations only" to "the sum of usage events," still at the fine granularity of one observable operation.
The crux: metering must be "exactly once"
A scheduled job most fears duplicate execution and crashing mid-way—but for billing, both are disasters: a duplicate report double-charges the customer; a miss gives away compute. So the metering job uses a cronJobs table as a distributed lock + progress ledger, welding "exactly once" shut. It does three things: align to the hour (intervals strictly cut by hour, lastRun records which hour), mutual exclusion (during state=Processing, another instance may not enter), and fallback unlock (if the lock is held over 20 minutes, deem the prior job crashed and forcibly take over).
"exactly once" backstopped by a DB lock: handleCloudUsageMeteringJob maintains lastRun/state/jobStartedAt via prisma.cronJobs.upsert: intervals strictly hour-aligned (lastRun % 3600000 === 0), state=Processing mutex, jobStartedAt over 1200000ms (20 min) deemed crashed and forcibly taken over. Neither a duplicate nor a crash makes an hour over- or under-counted.
// get/create the cron record (distributed lock + progress ledger)const cron = await prisma.cronJobs.upsert({ … });
// gate1: interval strictly aligned to a whole hour (avoid misaligned overlap/gaps)if (cron.lastRun.getTime() % 3600000 !== 0) { /* anomaly, don't process */ }
const meterIntervalStart = cron.lastRun;
const meterIntervalEnd = new Date(cron.lastRun.getTime() + 3600000); // exactly 1 hour// gate2+3: Processing mutex; but jobStartedAt over 20 min = prior job crashed, take overif (cron.state === Processing &&
cron.jobStartedAt >= new Date(Date.now() - 1200000)) { /* someone's running, exit */ }
threat
would cause
how this gate blocks it
the same interval counted twice
customer double-charged
intervals strictly hour-aligned (lastRun%3600000===0), each hour processed once
two instances running concurrently
duplicate reports
state=Processing mutex, the latecomer exits
the job crashing mid-way
lock stuck forever, all later misses
jobStartedAt over 20 min deemed a crash, forcibly taken over to resume
Each gate guards one real threat; together they ground abstract "exactly once" into three concrete, testable invariants. That's far more reliable than vaguely claiming "we guarantee exactly-once"—decomposing the guarantee into conditions you can write tests for is exactly the engineering posture a zero-tolerance billing system deserves.
Two different ledgers: platform billing vs your spend alerts
Easily confused: Part 8 features two kinds of "money", in opposite directions. One is the platform charging you (this lesson's metering, reporting usage events to Stripe); the other is your own LLM spend (the cost computed in Lessons 16, 42). The latter has a spend-alert (cloudSpendAlert) queue: it watches your monthly LLM spend across providers and pings you when it crosses a threshold you set—helping you manage your money, a separate matter from how the platform bills you.
① platform metering (this lesson)
direction: platform → charges you. Reports usage events to Stripe hourly, Cloud-exclusive. cloudUsageMeteringQueue. Insists on "exactly once".
② spend alerts (cloudSpendAlert)
direction: helps you → manage your LLM spend. Watches your cost on OpenAI/Anthropic etc., alerts on threshold crossing. cloudSpendAlertQueue (CloudSpendAlertJob).
③ self-host
no ①—self-deploying Langfuse charges you no platform fee. But cost observation like ② and the cost computation of Lessons 16/42 still work—you see your LLM spend just the same.
To wrap this thread: Part 8 ran from Lesson 40's "aggregate data into charts" all the way here, essentially answering "see clearly and govern the numbers"—dashboards show trends, the query engine unifies definitions, the pricing model computes cost clearly, and this lesson turns one kind of number (usage) into a real-money invoice. It also pulls back the curtain on Langfuse as a cloud business: open source and self-hostable (no charge), cloud-managed and usage-billed (this Stripe metering)—technology and commerce meshing tightly on this one worker.
🎯 Design trade-off
Why does the metering job go to such lengths for "exactly once"—hour alignment, locking, plus fallback unlock? Because this is money, and money's tolerance for error is zero. All earlier chains can occasionally over-count a trace or miss a score with little harm, self-healing next time. Billing is different: over-report one hour and a customer's credit card gets charged once more—a complaint-and-Twitter incident; under-report and the platform takes a real loss. A normal background job seeking "eventual consistency" is enough, but the metering job must achieve "exactly once"—a notoriously hard guarantee in distributed systems. Langfuse's solution is pragmatic: rather than chase theoretically perfect exactly-once, it uses a database row as a lock to plug three real threats one by one—duplicate execution (mutex blocks), task crash (20-minute fallback takeover), interval misalignment (strict hour alignment). Decomposing "exactly once" into a few implementable concrete defenses, rather than theorizing about guarantees—that's engineering wisdom.
Why bill by "usage events" rather than token count? An interesting product trade-off. Billing by token would tightly couple to the model you use (pricey models burn more tokens) and isn't directly tied to Langfuse's value—Langfuse's value is recording and analysis, not running the model for you. Billing by trace is too coarse: one trace may hold one step or hundreds of observations. So Langfuse picked a fine-grained "observable operation" unit: early on it counted only observations (tracing_observations, kept to this day as legacy), and has since evolved to tracing_events = trace + score + observation. Either way, complex apps produce more events and pay more, simple ones pay less, billing granularity aligned with the value the platform provides.
🎯 Key points · Part 8 wrap-up
This is Cloud-exclusive platform billing: a separate, opposite ledger from your LLM cost (Lessons 16/42); self-host charges no platform fee, so read it as "how managed billing is built".
Meter by usage events: an hourly job counts each org's obs/trace/score from ClickHouse, and for orgs with a Stripe customerId calls meterEvents.create to report two meters (tracing_observations legacy + tracing_events = the sum; backOff retry), Stripe invoicing.
"Exactly once" is the crux: a cronJobs table as distributed lock + ledger—strict hour-aligned intervals, Processing mutex, 20-minute fallback takeover—so each hour's usage is no-dup, no-miss.
Billing must be exactly-once: money tolerates no error, normal jobs' "eventual consistency" isn't enough; decompose exactly-once into "anti-duplicate + anti-crash + anti-misalignment" implementable defenses.
Usage events = a value-aligned billing unit (tracing_events=trace+score+observation; tracing_observations legacy): better than token (model-bound) at matching "how much Langfuse recorded/analyzed for you"—what the customer pays is proportional to value received. A separate cloudSpendAlert helps you manage your own LLM spend.
🧪 Self-test - think about the design
1. Langfuse Cloud's usage-metering job uses a cronJobs table for hour alignment + Processing mutex + 20-minute fallback takeover. What core problem does this design solve?
billing's 'exactly once': a duplicate report double-charges, a miss loses money for the platform; a DB row lock plugs duplicate execution (mutex), task crash (20-min fallback), and interval misalignment (hour alignment), so each hour's usage is no-dup, no-miss
supporting multiple currencies
compressing ClickHouse storage
speeding up metering
Show answer & explanation click to expand
Answer: A. Earlier chains can over-count a trace harmlessly and self-heal, but billing tolerates no error: over-report an hour and a customer's card is overcharged with a complaint; under-report is a platform loss. Normal 'eventual consistency' isn't enough; metering must be 'exactly once' (a hard distributed problem). Langfuse pragmatically uses a cronJobs row lock to plug three threats: duplicate execution (Processing mutex), crash (jobStartedAt>20min forced takeover), misalignment (lastRun%3600000===0 hour alignment).
2. Langfuse Cloud bills by 'usage events' (a fine-grained per-observable-operation unit) rather than token count. Why is this fine-grained unit more suitable than token?
observation count is easiest to count
observation count is smallest, lowest charge
it best aligns with the platform's value: token is model-bound (pricey models burn more, unrelated to record/analysis value), trace is too coarse (one trace may be 1 step or hundreds of observations); the observation is the atomic unit of 'one observable operation', making what the customer pays proportional to 'how much Langfuse recorded/analyzed'
Stripe only supports observation billing
Show answer & explanation click to expand
Answer: C. Billing by token couples tightly to your model (pricey models burn more) and isn't directly tied to Langfuse's value (record and analysis, not running the model). Billing by trace is too coarse: one trace may hold one step or hundreds of observations, charging complex agents and simple Q&A the same is unfair. The observation is exactly the atomic metering unit of 'one observable operation', best matching 'how much Langfuse stored and analyzed'—complex apps pay more, simple less. A good billing unit makes what the customer pays proportional to value received. (Metering reports two meters: tracing_observations legacy, and tracing_events = trace+score+observation, the current unit.)
3. Part 8 features two kinds of 'money': cloudUsageMetering and cloudSpendAlert. What's the difference?
identical, just different names
both are the platform charging you
both only work in self-host
opposite directions: metering is 'the platform charging you' (reports usage events to Stripe, Cloud-exclusive); spend alert is 'helping you manage your own LLM spend' (watches your cost across providers, alerts on threshold)—one charges you, one helps you watch your money
Show answer & explanation click to expand
Answer: D. Two opposite ledgers. cloudUsageMetering: platform → charges you, reporting observation count to Stripe hourly, the Cloud commercial layer, self-host charges nothing. cloudSpendAlert: helps you → manage your own LLM spend on OpenAI/Anthropic etc., alerting when crossing your threshold—in the lineage of Lessons 16/42 computing your cost. The former is 'how Langfuse charges you', the latter 'helping you watch what you spent'; don't conflate them.
💭 Open questions (no single right answer - just think or try)
'Billing must be exactly once' is the notoriously hard exactly-once problem in distributed systems, yet Langfuse doesn't chase theoretical perfection but uses a DB row lock to plug three real threats: anti-duplicate + anti-crash + anti-misalignment. Recall systems you've built or imagined: which scenarios have a similar hard 'no-dup-no-miss' requirement (payments, inventory, coupon issuance)? How would you weigh 'theoretical exactly-once' against 'a few good-enough concrete engineering defenses'? What are the latter's risks?