🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(billing): opt individual organizations into ClickHouse Billing (#18742)
Steffen Reuther5cb0a3d37172
diff --git a/.env.dev.example b/.env.dev.exampleindex 09af7f157f..134890d95e 100644--- a/.env.dev.example+++ b/.env.dev.example@@ -396,6 +396,9 @@ CLICKHOUSE_ENABLE_SKIP_INDEXES_ON_DATA_READ=auto# ClickHouse Billing (CHB) integration (Langfuse Cloud only). First-time# upgrades on/after this UTC date (YYYY-MM-DD) route to CHB; unset = off.# LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE=+# Comma-separated organization ids whose first-time upgrade routes to CHB+# regardless of the cutoff (single-org rollout testing).+# LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS=# Bearer secret for GET /api/billing/metrics; unset = endpoint disabled.# CLICKHOUSE_BILLING_METRICS_API_KEY=# CHB's EventBridge bus for project lifecycle events, authenticated by IAM fromdiff --git a/.env.prod.example b/.env.prod.exampleindex 0dcb934a71..aec0121cf6 100644--- a/.env.prod.example+++ b/.env.prod.example@@ -538,6 +538,9 @@ LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG=true# ClickHouse Billing (CHB) integration (Langfuse Cloud only). First-time# upgrades on/after this UTC date (YYYY-MM-DD) route to CHB; unset = off.# LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE=+# Comma-separated organization ids whose first-time upgrade routes to CHB+# regardless of the cutoff (single-org rollout testing).+# LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS=# Bearer secret for GET /api/billing/metrics; unset = endpoint disabled.# CLICKHOUSE_BILLING_METRICS_API_KEY=# CHB's EventBridge bus for project lifecycle events, authenticated by IAM fromdiff --git a/packages/shared/src/interfaces/billingProvider.test.ts b/packages/shared/src/interfaces/billingProvider.test.tsindex 92a5157de7..bd10b1cf5d 100644--- a/packages/shared/src/interfaces/billingProvider.test.ts+++ b/packages/shared/src/interfaces/billingProvider.test.ts@@ -4,8 +4,10 @@ import { getBillingProvider, hasPaidBillingState } from "./billingProvider";import { CloudConfigSchema } from "./cloudConfigSchema";const CHB_ORG_ID = "0d5e6f7a-1b2c-4d3e-8f9a-0b1c2d3e4f5a";+const ORG_ID = "org-1";const orgWith = (cloudConfig: unknown) => ({+ id: ORG_ID,cloudConfig:cloudConfig === null ? null : CloudConfigSchema.parse(cloudConfig),});@@ -80,6 +82,28 @@ describe("getBillingProvider", () => {).toBe("stripe");});});++ describe("opted-in orgs resolve to clickhouse without a cutoff", () => {+ it("a never-billed org on the opt-in list resolves to clickhouse", () => {+ expect(getBillingProvider(orgWith({}), { optInOrgIds: [ORG_ID] })).toBe(+ "clickhouse",+ );+ });++ it("an org missing from the opt-in list stays on stripe", () => {+ expect(+ getBillingProvider(orgWith({}), { optInOrgIds: ["org-other"] }),+ ).toBe("stripe");+ });++ it("the opt-in does not move an org with Stripe state", () => {+ expect(+ getBillingProvider(orgWith({ stripe: { customerId: "cus_123" } }), {+ optInOrgIds: [ORG_ID],+ }),+ ).toBe("stripe");+ });+ });});describe("hasPaidBillingState", () => {diff --git a/packages/shared/src/interfaces/billingProvider.ts b/packages/shared/src/interfaces/billingProvider.tsindex c0ef1fec4b..b2e5b31ae1 100644--- a/packages/shared/src/interfaces/billingProvider.ts+++ b/packages/shared/src/interfaces/billingProvider.ts@@ -12,24 +12,28 @@ type OrgWithCloudConfig = {* Decision order:* 1. Explicit CHB state always wins — the org is already on CHB. Sticky from* the first checkout (which persists `clickhouse.organizationId`), so- * later cutoff changes cannot strand an org mid-flow.+ * later cutoff or opt-in changes cannot strand an org mid-flow.* 2. Any existing Stripe billing state pins the org to Stripe (legacy). An* existing billed customer can never flip providers via config.- * 3. Otherwise the org has never been billed: the cutoff decides at upgrade- * time — first checkouts on/after the cutoff go to CHB, regardless of when- * the org was created. Until a checkout writes CHB state, resolving to- * "clickhouse" has no side effects.+ * 3. Otherwise the org has never been billed: an org on the opt-in list goes+ * to CHB, independent of the cutoff, so a single org can run the CHB flow+ * end to end before the global rollout.+ * 4. For every other never-billed org the cutoff decides at upgrade time —+ * first checkouts on/after the cutoff go to CHB, regardless of when the org+ * was created. Until a checkout writes CHB state, resolving to "clickhouse"+ * has no side effects.*- * The cutoff is injected rather than read from the environment: this module is- * exported from the client-safe barrel, so it must not reach for the server env- * schema. Each app passes the value from its own validated env.+ * The cutoff and opt-in list are injected rather than read from the+ * environment: this module is exported from the client-safe barrel, so it must+ * not reach for the server env schema. Each app passes the values from its own+ * validated env.*- * Absent cutoff ⇒ zero behavior change: nothing resolves to "clickhouse"- * unless it already carries a `clickhouse` block.+ * Absent cutoff and opt-in list ⇒ zero behavior change: nothing resolves to+ * "clickhouse" unless it already carries a `clickhouse` block.*/export function getBillingProvider(- org: OrgWithCloudConfig,- opts?: { cutoff?: Date | null; now?: Date },+ org: OrgWithCloudConfig & { id: string },+ opts?: { cutoff?: Date | null; optInOrgIds?: string[]; now?: Date },): BillingProvider {if (org.cloudConfig?.clickhouse?.organizationId) return "clickhouse";if (@@ -37,6 +41,7 @@ export function getBillingProvider(org.cloudConfig?.stripe?.activeSubscriptionId)return "stripe";+ if (opts?.optInOrgIds?.includes(org.id)) return "clickhouse";const cutoff = opts?.cutoff;if (cutoff && (opts?.now ?? new Date()).getTime() >= cutoff.getTime())return "clickhouse";diff --git a/web/src/__tests__/server/unit/resolveBillingService.servertest.ts b/web/src/__tests__/server/unit/resolveBillingService.servertest.tsindex 96be74688f..fda77b7db7 100644--- a/web/src/__tests__/server/unit/resolveBillingService.servertest.ts+++ b/web/src/__tests__/server/unit/resolveBillingService.servertest.ts@@ -3,6 +3,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";const mocks = vi.hoisted(() => ({env: {LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE: null as Date | null,+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS: [] as string[],},getChbApiClient: vi.fn(),createBillingServiceFromContext: vi.fn(),@@ -41,6 +42,7 @@ describe("resolveBillingService", () => {beforeEach(() => {vi.clearAllMocks();mocks.env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE = null;+ mocks.env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS = [];mocks.createBillingServiceFromContext.mockReturnValue(STRIPE_SERVICE);mocks.getChbApiClient.mockReturnValue({ client: true });mocks.findOrg.mockResolvedValue({@@ -98,6 +100,19 @@ describe("resolveBillingService", () => {expect(billingProvider).toBe("clickhouse");});+ it("routes an opted-in never-billed org to CHB without a cutoff", async () => {+ // Same plumbing guard as the cutoff: the opt-in list is injected too.+ mocks.env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS = [ORG_ID];++ const { billingProvider, service } = await resolveBillingService(+ ctxWithOrg({}),+ ORG_ID,+ );++ expect(billingProvider).toBe("clickhouse");+ expect(service).toBeInstanceOf(ChbBillingService);+ });+it("fails closed to Stripe when the cutoff is set but the CHB env is incomplete", async () => {mocks.env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE = new Date("2020-01-01T00:00:00Z",diff --git a/web/src/ee/features/billing/server/resolveBillingService.ts b/web/src/ee/features/billing/server/resolveBillingService.tsindex 55215403f2..71a5fcb67e 100644--- a/web/src/ee/features/billing/server/resolveBillingService.ts+++ b/web/src/ee/features/billing/server/resolveBillingService.ts@@ -26,10 +26,10 @@ export type CloudBillingService =* `cloudBillingRouter` procedures keep their names, inputs, and output* shapes, so the tRPC contract does not change.*- * Fail-closed guard: when the CHB cutoff is set but the CHB REST env is- * incomplete, cutoff-routed orgs (no CHB state yet) fall back to Stripe —- * never a half-configured CHB flow. Orgs already carrying CHB state cannot be- * served by Stripe and error instead.+ * Fail-closed guard: when the CHB cutoff or opt-in list is set but the CHB+ * REST env is incomplete, orgs routed by them (no CHB state yet) fall back to+ * Stripe — never a half-configured CHB flow. Orgs already carrying CHB state+ * cannot be served by Stripe and error instead.** This dispatch is also the structural interlock that keeps Stripe checkout* unreachable for any org holding a `cloudConfig.clickhouse` block: such@@ -52,11 +52,13 @@ export const resolveBillingService = async (});}const parsedOrg = parseDbOrg(org);- // The cutoff is injected rather than read inside the resolver: the shared- // module is exported from the client-safe barrel, so web passes the value from- // its own validated env schema.- const cutoff = env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE;- const billingProvider = getBillingProvider(parsedOrg, { cutoff });+ // The cutoff and opt-in list are injected rather than read inside the+ // resolver: the shared module is exported from the client-safe barrel, so web+ // passes the values from its own validated env schema.+ const billingProvider = getBillingProvider(parsedOrg, {+ cutoff: env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,+ optInOrgIds: env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,+ });if (billingProvider === "clickhouse") {// Shared process-wide, so every billing request reuses one Auth0 token@@ -73,12 +75,10 @@ export const resolveBillingService = async (message: "ClickHouse Billing is not configured on this deployment",});}- // Cutoff-routed org without CHB state: fail closed to Stripe- if (cutoff) {- logger.error(- "resolveBillingService: LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE is set but the CHB REST env is incomplete — treating the cutoff as unset (fail closed to Stripe)",- );- }+ // Cutoff- or opt-in-routed org without CHB state: fail closed to Stripe+ logger.error(+ `resolveBillingService: org ${orgId} routes to CHB by cutoff or opt-in but the CHB REST env is incomplete — falling back to Stripe`,+ );return {billingProvider: "stripe",service: createBillingServiceFromContext(ctx),diff --git a/web/src/env.mjs b/web/src/env.mjsindex 2c93097310..2ed8dbc6c0 100644--- a/web/src/env.mjs+++ b/web/src/env.mjs@@ -469,6 +469,19 @@ export const env = createEnv({.date().optional().transform((date) => (date ? new Date(date) : null)),+ // Comma-separated Langfuse organization ids whose first-time upgrade routes+ // to CHB regardless of the cutoff, for testing the CHB flow on a single org+ // before the global rollout. Orgs already billed by Stripe stay on Stripe.+ // Keep in sync with worker/src/env.ts.+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS: z+ .string()+ .default("")+ .transform((value) =>+ value+ .split(",")+ .map((id) => id.trim())+ .filter(Boolean),+ ),// Bearer secret CHB's metering pipeline presents to GET /api/billing/metrics.// Unset disables the endpoint (it 500s) rather than leaving it open.CLICKHOUSE_BILLING_METRICS_API_KEY: z.string().optional(),@@ -1146,6 +1159,8 @@ export const env = createEnv({STRIPE_WEBHOOK_SIGNING_SECRET: process.env.STRIPE_WEBHOOK_SIGNING_SECRET,LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE:process.env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS:+ process.env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,CLICKHOUSE_BILLING_METRICS_API_KEY:process.env.CLICKHOUSE_BILLING_METRICS_API_KEY,CLICKHOUSE_BILLING_EVENT_BUS_ARN:diff --git a/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.ts b/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.tsindex 89a406fb47..27354c8e17 100644--- a/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.ts+++ b/worker/src/ee/cloudSpendAlerts/handleCloudSpendAlertJob.ts@@ -285,6 +285,7 @@ export const handleCloudSpendAlertJob = async (job: Job<{ orgId: string }>) => {// unknown to CHB, so this is a hard fork rather than a fallback chain.const billingProvider = getBillingProvider(org, {cutoff: env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,+ optInOrgIds: env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,});try {diff --git a/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts b/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.tsindex 2b7a282ae0..9f0b8cceb1 100644--- a/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts+++ b/worker/src/ee/cloudUsageMetering/handleCloudUsageMeteringJob.ts@@ -236,6 +236,7 @@ export const handleCloudUsageMeteringJob = async (job: Job) => {if (getBillingProvider(org, {cutoff: env.LANGFUSE_CLOUD_BILLING_CHB_CUTOFF_DATE,+ optInOrgIds: env.LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS,}) !== "stripe") {traceException(diff --git a/worker/src/env.ts b/worker/src/env.tsindex b4965cf315..e2dc1fb014 100644--- a/worker/src/env.ts+++ b/worker/src/env.ts@@ -43,6 +43,17 @@ const EnvSchema = z.object({.date().optional().transform((date) => (date ? new Date(date) : null)),+ // Comma-separated Langfuse organization ids routed to CHB regardless of the+ // cutoff; keep in sync with web/src/env.mjs.+ LANGFUSE_CLOUD_BILLING_CHB_OPT_IN_ORG_IDS: z+ .string()+ .default("")+ .transform((value) =>+ value+ .split(",")+ .map((id) => id.trim())+ .filter(Boolean),+ ),// CHB REST credentials, mirroring web/src/env.mjs. The worker needs them for// one read: the spend-alert job asks for the open period's accrued usage.