🪢 Langfuse 图解教程Langfuse Visual Guide 第八部分 · 仪表盘·指标·成本Part 8 · Dashboards, Metrics & Cost 43 / 55
第八部分 · 仪表盘·指标·成本Part 8 · Dashboards, Metrics & Cost

云用量计量与花费Cloud usage metering & spend

🧭 读前Before you start
先读 第16课 的成本计算与 第42课 的定价,本课讲云用量计量与花费。
Read Lesson 16 (cost) and Lesson 42 (pricing); this lesson covers cloud usage metering and spend.

前面讲的「成本」(第 16、42 课)是你的 LLM 花了多少。这一课讲另一笔账:你用 Langfuse 这个平台本身,平台怎么向你计量、收费。这是 Langfuse Cloud 特有的一环——自托管(self-host)版本不向你收费,所以这一课你可以当作「看看托管服务背后的计费是怎么搭的」。 重点有三:Langfuse Cloud 按观测数计量、用每小时一次的定时任务把用量上报给 Stripe 开账单,以及一个关乎钱的命门——「计量必须恰好一次」的幂等设计。钱算多了惹客户、算少了亏自己,所以这套计量对「不重不漏」的要求,比前面任何一条链路都严苛。

📋 生活类比
云计量像小区里的「水表 + 抄表员」。你用平台就像用水,平台给你装了一块表,按用量(用量事件)默默地计。抄表员(每小时一次的定时任务)准点来抄一次这一小时的读数,把数字报给收费公司(Stripe),由它汇总成月度账单。 最要命的是:抄表绝不能重复、也绝不能漏。抄两遍,你这个月水费翻倍、客户暴怒;漏一次,平台白送了一小时算力。所以抄表员手里攥着一本「上次抄到几点」的台账(一张带锁的 cron 记录),死死卡住「每个整点小时的用量,不多不少、恰好上报一次」——哪怕他中途打了个盹、网断了重来、或者不小心来了两个抄表员,这本台账都能保证账目分毫不乱。

计量模型:每小时数一次观测,报给 Stripe

Langfuse Cloud 按用量事件计费。计量任务(handleCloudUsageMeteringJob)由一个每小时触发的定时队列驱动:对刚过去的那个整点小时,从 ClickHouse 数出每个项目的 observation/trace/score 数,再按组织(organization)汇总,最后推给 Stripe 的计量 API——它上报两个 meter:tracing_observations(仅观测数,legacy)和 tracing_events(= trace + score + observation 之和,当前计费口径),由 Stripe 出账单。

每小时计量:数观测 → 按组织汇总 → 报 Stripe 每小时 cronCloudUsageMeteringJob 数这一小时的用量getObservationCounts…getTrace / getScore Counts按项目,来自 ClickHouse 按 organization 汇总仅有 Stripe customerId 的∑ 各项目观测数 Stripe 计量 APImeterEvents.createtracing_events + obs(legacy) Stripe 拿到「某客户这一小时用了 N 个观测」的计量事件,月底汇总成发票——平台只管报数,开票交给专业的 上报包在 backOff 重试里:网络抖动也要保证这笔用量最终送达
用量计量 → Stripe 出账:handleCloudUsageMeteringJob 每小时对过去整点区间,用 getObservation/Trace/ScoreCountsByProjectInCreationInterval 从 ClickHouse 数量,按 org 汇总,对有 cloudConfig.stripe.customerId 的组织调 meterEvents.create 上报两个 meter——tracing_observations(legacy) 与 tracing_events(=trace+score+obs)(backOff 重试)。源码:worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts。
示例:用量计量 → 月末 Stripe 账单 用量计量 · per project → per org Jun 1 10:00+1,240 obs Jun 1 11:00+980 obs Jun 1 12:00+1,510 obs …… obs Jun 30 23:00+1,090 obs Σ 6 月1,240,000 obs 月末 Stripe Invoice · 2026 年 6 月 订阅 · Team 套餐$199.00 用量 · 1.24M events$124.00 税 (tax)$25.84 用量 = Σobs × 单价(按套餐阶梯,金额为示例) 合计 Total$348.84 平台只负责「数数」(每项目记 observations、按组织汇总);真正开票、收税、扣款交给 Stripe
平台数数,Stripe 开票(结构取自 billing 的 getInvoices:subscription / usage / tax 分解;金额为示例):用量按 tracing_events(trace+score+observation 之和)计费——每个项目按小时累计、再按组织汇总(图左以 obs 累计示意,整月 1.24M)。月末 Stripe 出一张账单,拆成订阅(固定套餐费)、用量(Σevents × 阶梯单价)、税三类行项目,合计扣款。这条「计量与计费分离」的边界很关键:平台专心准确地数数,发票、税务、支付这些又重又合规的事全甩给 Stripe。
worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts数量 + 上报 Stripe
// 1) 对刚过去的整点小时,从 ClickHouse 数各项目用量
const observationCounts = await getObservationCountsByProjectInCreationInterval({ start, end });

for (const org of organizations) {                  // 仅含有 stripe.customerId 的组织
  const countObservations = observationCounts/* …该 org 各项目 */.reduce((s, p) => s + p.count, 0);
  if (countObservations > 0) {
    await backOff(() =>                              // 重试:保证最终送达
      stripe.billing.meterEvents.create({
        event_name: "tracing_observations",
        timestamp: meterIntervalEnd.getTime() / 1000,
        payload: { stripe_customer_id, value: countObservations.toString() } }));  // legacy meter
  }
  // 当前计费口径:events = traces + scores + observations
  const 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() } }));
}
这一小时数了什么来源是否用于计费
观测数(observations)getObservationCountsByProjectInCreationInterval是——单独上报 tracing_observations(legacy),并计入 tracing_events
trace 数getTraceCounts…是——计入 tracing_events
score 数getScoreCounts…是——计入 tracing_events

三种量都数,且都进账:计量上报两个 meter——tracing_observations(仅观测数,legacy、向后兼容)与 tracing_events(trace + score + observation 之和,当前计费口径)。也就是说 trace、score 同样计入计费(汇入 tracing_events),并非只是内部统计。计费单位从「纯观测数」演进为「用量事件之和」,仍保持按可观测操作的细颗粒度。

命门:计量必须「恰好一次」

定时任务最怕重复执行和中途崩溃——但对计费来说,这两样都是灾难:重复上报,客户被双倍收费;漏报,平台白送算力。所以计量任务用一张 cronJobs 表当分布式锁 + 进度台账,把「恰好一次」焊死。它做三件事:对齐整点(区间严格按小时切,lastRun 记到哪个整点)、互斥锁(state=Processing 期间别的实例不许进)、兜底解锁(锁超过 20 分钟没释放,判定上个任务崩了、强制接管)。

cronJobs 表:把「恰好一次」焊死的三道闸 cronJobs 表:lastRun(已计到哪个整点)· state(Processing?)· jobStartedAt(何时开工) 闸1 · 对齐整点区间 = [lastRun, +1h)严格小时边界对齐同一小时不会算两遍 闸2 · 互斥锁state=Processing 期间别的实例不许进防并发重复上报 闸3 · 兜底解锁锁 > 20 分钟未释放判定上个任务崩了强制接管,不会永久卡死 重复执行被锁挡、崩溃被兜底接管、区间按整点对齐——三道闸合力,让每个小时的用量「不重不漏,恰好一次」
「恰好一次」靠数据库锁兜底:handleCloudUsageMeteringJob 用 prisma.cronJobs.upsert 维护 lastRun/state/jobStartedAt:区间严格对齐整点(lastRun % 3600000 === 0)、state=Processing 互斥、jobStartedAt 超 1200000ms(20 分钟)判定崩溃强制接管。重复或崩溃都不会让某小时多算或漏算。
worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.tscronJobs 幂等锁
// 取/建 cron 记录(分布式锁 + 进度台账)
const cron = await prisma.cronJobs.upsert({ … });

// 闸1:区间严格对齐整点小时(避免错位重叠/漏算)
if (cron.lastRun.getTime() % 3600000 !== 0) { /* 异常,不处理 */ }
const meterIntervalStart = cron.lastRun;
const meterIntervalEnd = new Date(cron.lastRun.getTime() + 3600000);  // 正好 1 小时

// 闸2+3:Processing 互斥;但 jobStartedAt 超 20 分钟视为上个任务崩了,强制接管
if (cron.state === Processing &&
    cron.jobStartedAt >= new Date(Date.now() - 1200000)) { /* 别人在跑,退出 */ }
威胁会造成这道闸怎么挡
同一区间被算两遍客户被双倍收费区间严格对齐整点(lastRun%3600000===0),同一小时只处理一次
两个实例并发跑重复上报state=Processing 互斥锁,后来者直接退出
任务中途崩溃锁永久卡死、之后全漏算jobStartedAt 超 20 分钟视为崩溃,强制接管续算

三道闸各防一种现实威胁,合起来把抽象的「精确一次」落成了三个具体、可测的不变量。这比空谈「我们保证 exactly-once」靠谱得多——把保证拆成能写进测试的具体条件,正是计费这种零容错系统该有的工程姿态。

两本不同的账:平台计费 vs 你的花费告警

容易混淆的是:Part 8 里出现了两种「钱」,方向正好相反。一种是平台向你收费(本课的计量,按用量事件报 Stripe);另一种是你自己的 LLM 花费(第 16、42 课算出的成本)。后者还配了一个 花费告警(cloudSpendAlert)队列:盯着你这个月在各家 provider 上的 LLM 开销,越过你设的阈值就提醒你——这是帮你管好你的钱,和平台怎么收你的费是两码事。

① 平台计费(平台 → 收你的费) 方向:平台 → 收你的费 按用量事件 / 每小时报 Stripe cloudUsageMeteringQueue 讲究「恰好一次」 ↔ 方向相反 ② 花费告警(帮你 → 管你的钱) 方向:帮你 → 管你的 LLM 花费 盯你在 OpenAI/Anthropic 的成本 cloudSpendAlertQueue 越过阈值就告警(L16/42 成本) 自托管:没有 ①(不收平台费),但 ② 那样的成本观测照用

① 平台计量(本课主线)

方向:平台 → 收你的费。按用量事件每小时报 Stripe,Cloud 专属。cloudUsageMeteringQueue。讲究「恰好一次」。

② 花费告警(cloudSpendAlert)

方向:帮你 → 管你的 LLM 花费。盯你在 OpenAI/Anthropic 等的成本,越阈值就告警。cloudSpendAlertQueue(CloudSpendAlertJob)。

③ 自托管(self-host)

没有①——自己部署 Langfuse 不向你收平台费。但②那样的成本观测、第 16/42 课的成本计算照样能用,你的 LLM 花了多少一样看得清。

把这条线收个尾:Part 8 从第 40 课「把数据聚合成图」一路走到这里,本质是回答「看清并管住数字」这件事——仪表盘看趋势、查询引擎统一口径、定价模型算清成本,而这一课,是把其中一类数字(用量)变成真金白银的账单。它也顺势揭开了 Langfuse 作为一门云生意的内里:开源可自托管(不收费),云托管按用量计费(这套 Stripe 计量)——技术与商业,在这台 worker 上严丝合缝地咬合。

🎯 设计取舍
为什么计量任务要为「恰好一次」下这么大功夫——对齐整点、加锁、还要兜底解锁? 因为这是钱,而钱对错误的容忍度是零。前面所有链路,偶尔多算一条 trace、漏掉一个 score,大多无伤大雅、下次自愈。但计费不一样:多上报一小时用量,客户的信用卡就被多刷一次,是会上投诉、上推特的事故;少报,则是平台实打实的亏损。普通后台任务追求「最终一致」就够了,计量任务却必须做到「精确一次」(exactly-once)——这是分布式系统里出了名难啃的保证。Langfuse 的解法很务实:不去追求理论上完美的精确一次,而是用一张数据库行当锁,把三种现实威胁逐一堵死——重复执行(互斥锁挡)、任务崩溃(20 分钟兜底接管)、区间错位(严格对齐整点)。把「精确一次」拆解成几个可落地的具体防护,而非空谈理论保证,这是工程的智慧。

为什么按「用量事件」而不是 token 数计费? 这是个有意思的产品取舍。按 token 计费会和你用的模型强绑定(贵模型 token 多),且和 Langfuse 提供的价值不直接相关——Langfuse 的价值是记录和分析,不是替你跑模型。按 trace 又太粗:一个 trace 可能含一步、也可能含上百步观测。所以 Langfuse 选了细颗粒度的「可观测操作」作单位:早期只数 observation(tracing_observations,至今保留为 legacy),现已演进为 tracing_events=trace + score + observation 之和。无论哪种,复杂应用产生的事件多、付得也多,简单的少付,计费颗粒度与平台提供的价值对齐。
🎯 本课要点 · 第八部分收官
  • 这是 Cloud 专属的平台计费:和你的 LLM 成本(第 16/42 课)是两笔反向的账;自托管不收平台费,可只看作「托管计费如何搭建」。
  • 按用量事件计量:每小时定时任务从 ClickHouse 数各 org 的 obs/trace/score 数,对有 Stripe customerId 的组织调 meterEvents.create 上报两个 meter(tracing_observations legacy + tracing_events=三者之和,backOff 重试),由 Stripe 出账。
  • 「恰好一次」是命门:用 cronJobs 表当分布式锁+台账——区间严格对齐整点、Processing 互斥、20 分钟兜底接管,让每小时用量不重不漏。
  • 计费要精确一次:钱对错误零容忍,普通任务的「最终一致」不够;把 exactly-once 拆成「防重复+防崩溃+防错位」三道可落地的具体防护。
  • 用量事件是对齐价值的计费单位(tracing_events=trace+score+observation,tracing_observations 为 legacy):比 token(绑模型)更贴合「Langfuse 帮你记录分析了多少」——客户付的钱正比于得到的价值。另有 cloudSpendAlert 帮你管自己的 LLM 花费。

🧪 自测 · 想一想为什么这么设计

1. Langfuse Cloud 的用量计量任务用一张 cronJobs 表,做整点对齐 + Processing 互斥 + 20分钟兜底接管。这套设计要解决的核心问题是?
  1. 计费的「恰好一次」:重复上报会双倍收费、漏报则平台亏损;用数据库行锁堵死重复执行(互斥)、任务崩溃(20分钟兜底)、区间错位(整点对齐),让每小时用量不重不漏
  2. 支持多种货币
  3. 压缩 ClickHouse 存储
  4. 加快计量速度
看答案与解析 点击展开
答案:A。前面链路偶尔多算一条 trace 大多无伤、下次自愈,但计费对错误零容忍:多报一小时用量,客户信用卡被多刷、上投诉;少报是平台亏损。普通任务「最终一致」不够,计量须「精确一次」(exactly-once,分布式难题)。Langfuse 务实地用 cronJobs 行锁把三种威胁逐一堵死:重复执行(Processing 互斥)、崩溃(jobStartedAt>20分钟强制接管)、错位(lastRun%3600000===0 整点对齐)。
2. Langfuse Cloud 按「用量事件」(可观测操作的细颗粒度)计费,而不是按 token 数。为什么这种细颗粒度单位比 token 更合适?
  1. 观测数最容易统计
  2. 观测数最小,收费最低
  3. 它最对齐平台提供的价值:token 绑模型(贵模型token多,与记录分析的价值无关)、trace 太粗(一个trace可能1步也可能上百步观测);观测是「一次可观测操作」的原子单位,让客户付的钱正比于「Langfuse帮你记录分析了多少」
  4. Stripe 只支持观测计费
看答案与解析 点击展开
答案:C。按 token 计费和你用的模型强绑定(贵模型 token 多),且和 Langfuse 的价值(记录与分析,不是替你跑模型)不直接相关。按 trace 太粗:一个 trace 可能含一步或上百步观测,复杂 agent 和简单问答同价不公平。观测恰好是「一次可观测操作」的原子计量单位,最对得上「Langfuse 帮你存了、分析了多少」——复杂应用观测多付得多、简单少付。好的计费单位让客户付的钱正比于得到的价值。(计量上报两个 meter:tracing_observations 为 legacy、tracing_events=trace+score+observation 之和,为当前口径。)
3. Part 8 里出现了两种「钱」:cloudUsageMetering 和 cloudSpendAlert。它们的区别是?
  1. 完全一样,只是名字不同
  2. 都是平台向你收费
  3. 都只在自托管版生效
  4. 方向相反:计量是「平台向你收费」(按用量事件报Stripe,Cloud专属);花费告警是「帮你管你自己的LLM花费」(盯你在各provider的成本越阈值就提醒)——一个收你的钱、一个帮你看你的钱
看答案与解析 点击展开
答案:D。两笔账方向相反。cloudUsageMetering:平台→收你的费,按观测数每小时报 Stripe,是 Cloud 商业层、自托管不收费。cloudSpendAlert:帮你→管你自己在 OpenAI/Anthropic 等的 LLM 开销,越过你设的阈值就提醒——和第16/42课算你的成本一脉相承。前者是「Langfuse 怎么收你钱」,后者是「帮你看你花了多少钱」,别混淆。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 「计费必须恰好一次」是分布式系统里出了名难的 exactly-once 问题,而 Langfuse 没有追求理论完美,而是用一张数据库行锁把「防重复+防崩溃+防错位」三种现实威胁逐一堵死。回想你做过或设想的系统:哪些场景对「不重不漏」有类似的硬要求(支付、库存、发券)?你会怎么权衡「理论上的精确一次」与「工程上够用的几道具体防护」?后者有什么风险?

The "cost" discussed earlier (Lessons 16, 42) is how much your LLM spent. This lesson is about a different ledger: how the Langfuse platform itself meters 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.

hourly metering: count observations → aggregate by org → report to Stripe hourly cronCloudUsageMeteringJob count this hour's usagegetObservationCounts…getTrace / getScore Countsper project, from ClickHouse aggregate by organizationonly those with a Stripe customerId∑ each project's observations Stripe metering APImeterEvents.createtracing_events + obs(legacy) Stripe receives "N observations this hour" metering events → invoice at month end; the platform reports counts, invoicing left to the specialist the report is wrapped in backOff retry: even network blips must let this usage eventually arrive
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.
Example: usage metering → month-end Stripe invoice usage metering · per project → per org Jun 1 10:00+1,240 obs Jun 1 11:00+980 obs Jun 1 12:00+1,510 obs …… obs Jun 30 23:00+1,090 obs Σ June1,240,000 obs month end Stripe Invoice · June 2026 subscription · Team plan$199.00 usage · 1.24M events$124.00 tax$25.84 usage = Σevents × unit price (per plan tier; illustrative) Total due$348.84 the platform only counts (observations per project, aggregated per org); Stripe does the actual invoicing, tax and charging
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 ClickHouse
const observationCounts = await getObservationCountsByProjectInCreationInterval({ start, end });

for (const org of organizations) {                  // only orgs with a stripe.customerId
  const 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 + observations
  const 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 hoursourceused for billing?
observation countgetObservationCountsByProjectInCreationIntervalyes — reported alone as tracing_observations(legacy), and summed into tracing_events
trace countgetTraceCounts…yes — summed into tracing_events
score countgetScoreCounts…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).

cronJobs table: three gates welding "exactly once" shut cronJobs table: lastRun (metered up to which hour) · state (Processing?) · jobStartedAt (when started) gate1 · align to hourinterval = [lastRun, +1h)strict hour-boundary alignedno hour counted twice gate2 · mutexwhile state=Processingother instances may not enterprevents concurrent duplicate reports gate3 · fallback unlocklock held > 20 minutesdeem prior job crashedforcibly take over, never stuck forever duplicates blocked by the lock, crashes recovered by fallback, intervals aligned to the hour—three gates together make each hour's usage "no dup, no miss, exactly once"
"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.
worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.tscronJobs idempotency lock
// 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 over
if (cron.state === Processing &&
    cron.jobStartedAt >= new Date(Date.now() - 1200000)) { /* someone's running, exit */ }
threatwould causehow this gate blocks it
the same interval counted twicecustomer double-chargedintervals strictly hour-aligned (lastRun%3600000===0), each hour processed once
two instances running concurrentlyduplicate reportsstate=Processing mutex, the latecomer exits
the job crashing mid-waylock stuck forever, all later missesjobStartedAt 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.

1 platform billing (platform → charges you) direction: platform → charges you by usage events / hourly → Stripe cloudUsageMeteringQueue cares about "exactly once" ↔ opposite 2 spend alerts (helps you → manage) direction: helps you → your LLM spend watches your OpenAI/Anthropic cost cloudSpendAlertQueue alerts over a threshold (L16/42 cost) self-host: no 1 (no platform fee), but still uses 2-style cost observation

① 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?
  1. 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
  2. supporting multiple currencies
  3. compressing ClickHouse storage
  4. 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?
  1. observation count is easiest to count
  2. observation count is smallest, lowest charge
  3. 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'
  4. 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?
  1. identical, just different names
  2. both are the platform charging you
  3. both only work in self-host
  4. 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?