🪢 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(web): show the organization usage breakdown on every deployment (#18154)
Steffen Reuther6ed192a58912
diff --git a/web/src/__tests__/organization-settings-pages.clienttest.tsx b/web/src/__tests__/organization-settings-pages.clienttest.tsxindex abacaf25ff..679f5398c4 100644--- a/web/src/__tests__/organization-settings-pages.clienttest.tsx+++ b/web/src/__tests__/organization-settings-pages.clienttest.tsx@@ -51,6 +51,10 @@ vi.mock("@/src/ee/features/billing/components/BillingSettings", () => ({BillingSettings: () => null,}));+vi.mock("@/src/features/organization-usage", () => ({+ OrganizationUsageBreakdown: () => null,+}));+vi.mock("@/src/features/entitlements/hooks", () => ({useHasEntitlement: vi.fn(),usePlan: vi.fn(),@@ -227,4 +231,46 @@ describe("useOrganizationSettingsPages", () => {]);expect(gatewayPages.every((page) => page.show === true)).toBe(true);});++ it("shows the usage page instead of the billing page without cloud billing", () => {+ vi.mocked(useHasOrganizationAccess).mockImplementation(+ ({ scope }) => scope === "organizationUsage:read",+ );++ const { result } = renderHook(() => useOrganizationSettingsPages());+ const show = (slug: string) =>+ result.current.find((page) => page.slug === slug)?.show;++ expect(show("usage")).toBe(true);+ expect(show("billing")).toBe(false);+ });++ it("hides the usage page on cloud, where the billing page embeds the breakdown", () => {+ vi.mocked(useHasOrganizationAccess).mockImplementation(+ ({ scope }) => scope === "organizationUsage:read",+ );+ vi.mocked(useHasEntitlement).mockImplementation(+ (entitlement) => entitlement === "cloud-billing",+ );+ vi.mocked(useIsCloudBillingAvailable).mockReturnValue(true);++ const { result } = renderHook(() => useOrganizationSettingsPages());+ const show = (slug: string) =>+ result.current.find((page) => page.slug === slug)?.show;++ expect(show("usage")).toBe(false);+ expect(show("billing")).toBe(true);+ });++ it("hides the usage page without usage access", () => {+ const { result } = renderHook(() => useOrganizationSettingsPages());++ expect(useHasOrganizationAccess).toHaveBeenCalledWith({+ organizationId: "org-1",+ scope: "organizationUsage:read",+ });+ expect(result.current.find((page) => page.slug === "usage")?.show).toBe(+ false,+ );+ });});diff --git a/web/src/__tests__/server/organization-usage-breakdown.servertest.ts b/web/src/__tests__/server/organization-usage-breakdown.servertest.tsnew file mode 100644index 0000000000..3c4b22a549--- /dev/null+++ b/web/src/__tests__/server/organization-usage-breakdown.servertest.ts@@ -0,0 +1,228 @@+import { randomUUID } from "crypto";+import { prisma, type Role } from "@langfuse/shared/src/db";+import {+ createObservation,+ createObservationsCh,+ createScoresCh,+ createTrace,+ createTraceScore,+ createTracesCh,+} from "@langfuse/shared/src/server";+import type { Session } from "next-auth";+import { testFeatureFlags } from "@/src/__tests__/fixtures/feature-flags";+import { getOrgUsageBreakdown } from "@/src/features/organization-usage/server/usageBreakdown";+import { appRouter } from "@/src/server/api/root";+import { createInnerTRPCContext } from "@/src/server/api/trpc";++const createOrgWithProjects = async (+ projects: { name: string; deleted?: boolean }[],+) => {+ const org = await prisma.organization.create({+ data: { id: randomUUID(), name: randomUUID() },+ });+ const created = await Promise.all(+ projects.map((project) =>+ prisma.project.create({+ data: {+ id: randomUUID(),+ name: project.name,+ orgId: org.id,+ deletedAt: project.deleted ? new Date() : null,+ },+ }),+ ),+ );+ return { orgId: org.id, projectIds: created.map((project) => project.id) };+};++const callerWithOrgRole = (orgId: string, role: Role) => {+ const session: Session = {+ expires: "1",+ user: {+ id: "user-1",+ canCreateOrganizations: false,+ name: "Demo User",+ admin: false,+ organizations: [+ {+ id: orgId,+ name: "Org",+ role,+ plan: "oss",+ cloudConfig: undefined,+ metadata: {},+ aiFeaturesEnabled: false,+ aiTelemetryEnabled: false,+ projects: [],+ },+ ],+ featureFlags: testFeatureFlags(),+ },+ environment: {+ enableExperimentalFeatures: false,+ selfHostedInstancePlan: "oss",+ },+ };+ const ctx = createInnerTRPCContext({ session, headers: {} });+ return appRouter.createCaller({ ...ctx, prisma });+};++const sortRows = <T extends { bucket: string; projectId: string }>(rows: T[]) =>+ [...rows].sort(+ (a, b) =>+ a.bucket.localeCompare(b.bucket) ||+ a.projectId.localeCompare(b.projectId),+ );++describe("getOrgUsageBreakdown", () => {+ it("counts billable units of the org's live projects by created_at", async () => {+ const {+ orgId,+ projectIds: [alpha, beta, deleted],+ } = await createOrgWithProjects([+ { name: "alpha" },+ { name: "beta" },+ { name: "gone", deleted: true },+ ]);+ const {+ projectIds: [otherOrgProject],+ } = await createOrgWithProjects([{ name: "other" }]);++ await createTracesCh([+ // Billed when ingested, not when the trace happened+ createTrace({+ project_id: alpha,+ timestamp: new Date("2026-07-01T10:00:00Z"),+ created_at: new Date("2026-08-03T10:00:00Z"),+ }),+ // `to` is exclusive+ createTrace({+ project_id: alpha,+ created_at: new Date("2026-08-06T00:00:00Z"),+ }),+ createTrace({+ project_id: deleted,+ created_at: new Date("2026-08-03T10:00:00Z"),+ }),+ createTrace({+ project_id: otherOrgProject,+ created_at: new Date("2026-08-03T10:00:00Z"),+ }),+ ]);+ await createObservationsCh([+ createObservation({+ project_id: alpha,+ created_at: new Date("2026-08-04T01:00:00Z"),+ }),+ createObservation({+ project_id: alpha,+ created_at: new Date("2026-08-04T23:59:00Z"),+ }),+ ]);+ await createScoresCh([+ createTraceScore({+ project_id: beta,+ created_at: new Date("2026-08-04T12:00:00Z"),+ }),+ createTraceScore({+ project_id: beta,+ data_type: "CORRECTION",+ created_at: new Date("2026-08-04T12:00:00Z"),+ }),+ ]);++ const result = await getOrgUsageBreakdown({+ prisma,+ orgId,+ from: new Date("2026-08-03T00:00:00Z"),+ to: new Date("2026-08-06T00:00:00Z"),+ });++ expect(result.granularity).toBe("day");+ expect(result.buckets).toEqual([+ "2026-08-03T00:00:00.000Z",+ "2026-08-04T00:00:00.000Z",+ "2026-08-05T00:00:00.000Z",+ ]);+ expect(result.projects).toEqual([+ { id: alpha, name: "alpha" },+ { id: beta, name: "beta" },+ ]);+ expect(sortRows(result.rows)).toEqual(+ sortRows([+ {+ bucket: "2026-08-03T00:00:00.000Z",+ projectId: alpha,+ unitType: "traces",+ count: 1,+ },+ {+ bucket: "2026-08-04T00:00:00.000Z",+ projectId: alpha,+ unitType: "observations",+ count: 2,+ },+ {+ bucket: "2026-08-04T00:00:00.000Z",+ projectId: beta,+ unitType: "scores",+ count: 1,+ },+ ]),+ );+ });++ it("puts ClickHouse week buckets on the generated Monday axis", async () => {+ const {+ orgId,+ projectIds: [projectId],+ } = await createOrgWithProjects([{ name: "weekly" }]);++ await createTracesCh([+ // Wednesday+ createTrace({+ project_id: projectId,+ created_at: new Date("2026-06-10T15:00:00Z"),+ }),+ ]);++ const result = await getOrgUsageBreakdown({+ prisma,+ orgId,+ from: new Date("2026-05-01T00:00:00Z"),+ to: new Date("2026-07-15T00:00:00Z"),+ });++ expect(result.granularity).toBe("week");+ expect(result.buckets[0]).toBe("2026-04-27T00:00:00.000Z");+ expect(result.rows).toEqual([+ {+ bucket: "2026-06-08T00:00:00.000Z",+ projectId,+ unitType: "traces",+ count: 1,+ },+ ]);+ expect(result.buckets).toContain(result.rows[0].bucket);+ });+});++describe("organizationUsage.breakdown", () => {+ // No entitlement gates this endpoint, so the org role is the only thing+ // keeping members from seeing usage of projects they cannot access.+ it("is readable by org admins but not by members", async () => {+ const { orgId } = await createOrgWithProjects([{ name: "admin-check" }]);+ const input = {+ orgId,+ from: new Date("2026-08-01T00:00:00Z"),+ to: new Date("2026-08-02T00:00:00Z"),+ };++ await expect(+ callerWithOrgRole(orgId, "ADMIN").organizationUsage.breakdown(input),+ ).resolves.toMatchObject({ granularity: "hour" });+ await expect(+ callerWithOrgRole(orgId, "MEMBER").organizationUsage.breakdown(input),+ ).rejects.toMatchObject({ code: "FORBIDDEN" });+ });+});diff --git a/web/src/ee/features/billing/README.md b/web/src/ee/features/billing/README.mdindex 35ee0850ec..bb383e0645 100644--- a/web/src/ee/features/billing/README.md+++ b/web/src/ee/features/billing/README.md@@ -24,6 +24,8 @@ See `web/src/ee/features/billing/server/cloudBillingRouter.ts`.- `getStripeCustomerPortalUrl` — portal for payment methods, tax IDs, invoices (not for plan switches).- `getInvoices` — paginated invoice list with subscription/usage/tax breakdown and preview row.+The billing page also embeds the usage breakdown chart from `web/src/features/organization-usage` (MIT, `organizationUsage.breakdown`). It counts units with the same `created_at` definition as metering. Self-hosted deployments show the same chart on the organization's Usage settings page instead.+### Checkout and Subscription ManagementImplemented in `web/src/ee/features/billing/server/stripe/stripeBillingService.ts`.diff --git a/web/src/ee/features/billing/components/BillingSettings.tsx b/web/src/ee/features/billing/components/BillingSettings.tsxindex ca4a182b12..8123bd96c6 100644--- a/web/src/ee/features/billing/components/BillingSettings.tsx+++ b/web/src/ee/features/billing/components/BillingSettings.tsx@@ -17,6 +17,7 @@ import { useIsCloudBillingAvailable } from "@/src/ee/features/billing/utils/isClimport { SpendAlertsSection } from "./SpendAlerts/SpendAlertsSection";import { useBillingInformation } from "./useBillingInformation";import { api } from "@/src/utils/api";+import { OrganizationUsageBreakdown } from "@/src/features/organization-usage";import { MAX_EVENTS_FREE_PLAN } from "@/src/ee/features/billing/constants";export const BillingSettings = () => {@@ -99,6 +100,7 @@ export const BillingSettings = () => {plan={organization?.plan ?? "cloud:hobby"}/>)}+ {organization && <OrganizationUsageBreakdown orgId={organization.id} />}<BillingPlanPeriodView />{showBillingDiscount && organization && (<BillingDiscountViewdiff --git a/web/src/features/organization-usage/components/OrganizationUsageBreakdown.tsx b/web/src/features/organization-usage/components/OrganizationUsageBreakdown.tsxnew file mode 100644index 0000000000..a22d3cb966--- /dev/null+++ b/web/src/features/organization-usage/components/OrganizationUsageBreakdown.tsx@@ -0,0 +1,230 @@+/* eslint-disable no-nested-ternary */+import { useMemo, useState } from "react";+import { DownloadIcon } from "lucide-react";++import { Card } from "@/src/components/ui/card";+import { IconButton } from "@/src/components/design-system/IconButton/IconButton";+import { Tabs } from "@/src/components/design-system/Tabs/Tabs";+import { Tooltip } from "@/src/components/design-system/Tooltip/Tooltip";+import { TimeRangePicker } from "@/src/components/date-picker";+import { NoDataOrLoading } from "@/src/components/NoDataOrLoading";+import {+ downloadChartDataCsv,+ VerticalBarChartTimeSeries,+ type DataPoint,+} from "@/src/features/widgets";+import { USAGE_BREAKDOWN_MAX_RANGE_MS } from "@/src/features/organization-usage/constants/usageBreakdown";+import { api } from "@/src/utils/api";+import { numberFormatter } from "@/src/utils/numbers";+import {+ toAbsoluteTimeRange,+ type TimeRange,+} from "@/src/utils/date-range-utils";+import type { RouterOutput } from "@/src/utils/types";++type UsageBreakdown = RouterOutput["organizationUsage"]["breakdown"];+type GroupBy = "project" | "type";++const TIME_RANGE_PRESETS = [+ "last1Day",+ "last7Days",+ "last30Days",+ "last90Days",+ "last1Year",+] as const;++const UNIT_TYPE_LABELS: Record<+ UsageBreakdown["rows"][number]["unitType"],+ string+> = {+ traces: "Traces",+ observations: "Observations",+ scores: "Scores",+};++const GRANULARITY_LABELS: Record<UsageBreakdown["granularity"], string> = {+ hour: "hourly",+ day: "daily",+ week: "weekly",+ month: "monthly",+};++/**+ * Turns the breakdown rows into one series per project or unit type. Every+ * (bucket, series) cell is explicit — a count with no rows is a real `0` — so+ * empty periods keep their slot on the axis. Series are ordered by total,+ * largest first, so the top consumers get the leading palette colors.+ */+const toChartData = (breakdown: UsageBreakdown, groupBy: GroupBy) => {+ const totalsBySeries = new Map<string, number>();+ const counts = new Map<string, Map<string, number>>();++ for (const row of breakdown.rows) {+ const series = groupBy === "project" ? row.projectId : row.unitType;+ totalsBySeries.set(series, (totalsBySeries.get(series) ?? 0) + row.count);+ const bySeries = counts.get(row.bucket) ?? new Map<string, number>();+ bySeries.set(series, (bySeries.get(series) ?? 0) + row.count);+ counts.set(row.bucket, bySeries);+ }++ const seriesOrder = [...totalsBySeries.entries()]+ .sort(([, a], [, b]) => b - a)+ .map(([series]) => series);++ const data: DataPoint[] = breakdown.buckets.flatMap((bucket) =>+ seriesOrder.map((series) => ({+ time_dimension: bucket,+ dimension: series,+ metric: counts.get(bucket)?.get(series) ?? 0,+ })),+ );++ const projectNames = new Map(+ breakdown.projects.map((project) => [project.id, project.name]),+ );+ const config = Object.fromEntries(+ seriesOrder.map((series) => [+ series,+ {+ label:+ groupBy === "project"+ ? (projectNames.get(series) ?? series)+ : UNIT_TYPE_LABELS[series as keyof typeof UNIT_TYPE_LABELS],+ },+ ]),+ );++ const total = [...totalsBySeries.values()].reduce((sum, n) => sum + n, 0);++ return { data, config, total };+};++/**+ * One row per bucket, project and unit type, independent of the chart's+ * grouping, so either view can be rebuilt offline with a pivot. Cells without+ * usage are left out.+ */+const toCsvRows = (breakdown: UsageBreakdown) => {+ const projectNames = new Map(+ breakdown.projects.map((project) => [project.id, project.name]),+ );+ return breakdown.rows+ .map((row) => ({+ bucket_start_utc: row.bucket,+ project_id: row.projectId,+ project_name: projectNames.get(row.projectId) ?? "",+ unit_type: row.unitType,+ units: row.count,+ }))+ .sort(+ (a, b) =>+ a.bucket_start_utc.localeCompare(b.bucket_start_utc) ||+ a.project_name.localeCompare(b.project_name) ||+ a.unit_type.localeCompare(b.unit_type),+ );+};++const toCsvFileName = (breakdown: UsageBreakdown, from: Date, to: Date) => {+ const day = (date: Date) => date.toISOString().slice(0, 10);+ return `usage-breakdown-${GRANULARITY_LABELS[breakdown.granularity]}-${day(from)}-to-${day(to)}`;+};++export const OrganizationUsageBreakdown = ({ orgId }: { orgId: string }) => {+ const [timeRange, setTimeRange] = useState<TimeRange>({+ range: "last30Days",+ });+ const [groupBy, setGroupBy] = useState<GroupBy>("project");++ const absoluteTimeRange = useMemo(+ () => toAbsoluteTimeRange(timeRange),+ [timeRange],+ );++ const breakdown = api.organizationUsage.breakdown.useQuery(+ {+ orgId,+ from: absoluteTimeRange?.from ?? new Date(),+ to: absoluteTimeRange?.to ?? new Date(),+ },+ {+ enabled: Boolean(absoluteTimeRange),+ trpc: { context: { skipBatch: true } },+ },+ );++ const chart = useMemo(+ () => (breakdown.data ? toChartData(breakdown.data, groupBy) : null),+ [breakdown.data, groupBy],+ );++ return (+ <Card className="flex flex-col gap-3 p-3">+ <div className="flex flex-wrap items-start justify-between gap-2">+ <div>+ <h3 className="font-bold">Usage breakdown</h3>+ <p className="text-muted-foreground text-sm">+ {chart && breakdown.data+ ? `${numberFormatter(chart.total, 0)} units, ${GRANULARITY_LABELS[breakdown.data.granularity]} buckets (UTC)`+ : "Units (traces, observations, scores)"}+ </p>+ </div>+ <div className="flex flex-wrap items-center gap-2">+ <Tabs+ value={groupBy}+ onValueChange={(value) => setGroupBy(value as GroupBy)}+ >+ <Tabs.List aria-label="Group usage by">+ <Tabs.Trigger value="project" label="By project" />+ <Tabs.Trigger value="type" label="By type" />+ </Tabs.List>+ </Tabs>+ <TimeRangePicker+ timeRange={timeRange}+ onTimeRangeChange={setTimeRange}+ timeRangePresets={TIME_RANGE_PRESETS}+ maxRangeMs={USAGE_BREAKDOWN_MAX_RANGE_MS}+ />+ <Tooltip label="Download as CSV">+ {({ getTriggerProps }) => (+ <IconButton+ {...getTriggerProps()}+ icon={DownloadIcon}+ label="Download usage breakdown as CSV"+ variant="outline"+ disabled={!chart || chart.total === 0}+ onClick={() => {+ if (!breakdown.data || !absoluteTimeRange) return;+ downloadChartDataCsv(+ toCsvRows(breakdown.data),+ toCsvFileName(+ breakdown.data,+ absoluteTimeRange.from,+ absoluteTimeRange.to,+ ),+ );+ }}+ />+ )}+ </Tooltip>+ </div>+ </div>+ <div className="h-80">+ {breakdown.isError ? (+ <div className="text-muted-foreground flex h-full items-center justify-center rounded-md border border-dashed text-sm">+ Failed to load usage breakdown+ </div>+ ) : chart && chart.total > 0 ? (+ <VerticalBarChartTimeSeries+ data={chart.data}+ config={chart.config}+ legendPosition="below"+ legendSummary="sum"+ legendInteraction="toggle"+ />+ ) : (+ <NoDataOrLoading isLoading={breakdown.isLoading} className="h-full" />+ )}+ </div>+ </Card>+ );+};diff --git a/web/src/features/organization-usage/constants/usageBreakdown.ts b/web/src/features/organization-usage/constants/usageBreakdown.tsnew file mode 100644index 0000000000..ec1952985f--- /dev/null+++ b/web/src/features/organization-usage/constants/usageBreakdown.ts@@ -0,0 +1,6 @@+/**+ * Longest window the usage breakdown accepts. Units are counted by+ * `created_at`, which a minmax skip index covers rather than the sort key, so+ * the bound keeps one request from scanning an org's full history.+ */+export const USAGE_BREAKDOWN_MAX_RANGE_MS = 366 * 24 * 60 * 60 * 1000;diff --git a/web/src/features/organization-usage/index.ts b/web/src/features/organization-usage/index.tsnew file mode 100644index 0000000000..71c47d55a0--- /dev/null+++ b/web/src/features/organization-usage/index.ts@@ -0,0 +1,3 @@+// The organization-usage feature's public client surface (RFC rule 8).+// organizationUsageRouter stays a direct import from the tRPC root.+export { OrganizationUsageBreakdown } from "@/src/features/organization-usage/components/OrganizationUsageBreakdown";diff --git a/web/src/features/organization-usage/server/organizationUsageRouter.ts b/web/src/features/organization-usage/server/organizationUsageRouter.tsnew file mode 100644index 0000000000..34b63c2e07--- /dev/null+++ b/web/src/features/organization-usage/server/organizationUsageRouter.ts@@ -0,0 +1,44 @@+import * as z from "zod";++import { throwIfNoOrganizationAccess } from "@/src/features/rbac";+import {+ createTRPCRouter,+ protectedOrganizationProcedure,+} from "@/src/server/api/trpc";+import { USAGE_BREAKDOWN_MAX_RANGE_MS } from "@/src/features/organization-usage/constants/usageBreakdown";+import { getOrgUsageBreakdown } from "@/src/features/organization-usage/server/usageBreakdown";++export const organizationUsageRouter = createTRPCRouter({+ breakdown: protectedOrganizationProcedure+ .input(+ z+ .object({+ orgId: z.string(),+ from: z.date(),+ to: z.date(),+ })+ .refine((input) => input.from < input.to, {+ message: "from must be before to",+ })+ .refine(+ (input) =>+ input.to.getTime() - input.from.getTime() <=+ USAGE_BREAKDOWN_MAX_RANGE_MS,+ { message: "Time range must not exceed one year" },+ ),+ )+ .query(async ({ input, ctx }) => {+ throwIfNoOrganizationAccess({+ organizationId: input.orgId,+ scope: "organizationUsage:read",+ session: ctx.session,+ });++ return await getOrgUsageBreakdown({+ prisma: ctx.prisma,+ orgId: input.orgId,+ from: input.from,+ to: input.to,+ });+ }),+});diff --git a/web/src/features/organization-usage/server/usageBreakdown.ts b/web/src/features/organization-usage/server/usageBreakdown.tsnew file mode 100644index 0000000000..15c1077df8--- /dev/null+++ b/web/src/features/organization-usage/server/usageBreakdown.ts@@ -0,0 +1,203 @@+import { type PrismaClient } from "@langfuse/shared/src/db";+import { LISTABLE_SCORE_TYPES } from "@langfuse/shared";+import {+ convertDateToClickhouseDateTime,+ queryClickhouse,+} from "@langfuse/shared/src/server";++type BillableUnitType = "traces" | "observations" | "scores";++type UsageBreakdownGranularity = "hour" | "day" | "week" | "month";++const HOUR_MS = 60 * 60 * 1000;+const DAY_MS = 24 * HOUR_MS;++/**+ * Picks calendar-aligned bars for the requested window: hourly up to two days,+ * daily up to two months, weekly up to half a year, monthly beyond.+ */+const getUsageBreakdownGranularity = (+ from: Date,+ to: Date,+): UsageBreakdownGranularity => {+ const spanMs = to.getTime() - from.getTime();+ if (spanMs <= 2 * DAY_MS) return "hour";+ if (spanMs <= 62 * DAY_MS) return "day";+ if (spanMs <= 183 * DAY_MS) return "week";+ return "month";+};++/** UTC bucket expression; weeks start on Monday. Must match `startOfBucket`. */+const BUCKET_SQL: Record<UsageBreakdownGranularity, string> = {+ hour: "toStartOfHour(created_at, 'UTC')",+ day: "toStartOfDay(created_at, 'UTC')",+ week: "toDateTime(toStartOfWeek(created_at, 1, 'UTC'), 'UTC')",+ month: "toDateTime(toStartOfMonth(created_at, 'UTC'), 'UTC')",+};++const startOfBucket = (+ date: Date,+ granularity: UsageBreakdownGranularity,+): Date => {+ const d = new Date(date);+ switch (granularity) {+ case "hour":+ d.setUTCMinutes(0, 0, 0);+ return d;+ case "day":+ d.setUTCHours(0, 0, 0, 0);+ return d;+ case "week":+ d.setUTCHours(0, 0, 0, 0);+ d.setUTCDate(d.getUTCDate() - ((d.getUTCDay() + 6) % 7));+ return d;+ case "month":+ d.setUTCHours(0, 0, 0, 0);+ d.setUTCDate(1);+ return d;+ }+};++const nextBucket = (+ bucket: Date,+ granularity: UsageBreakdownGranularity,+): Date => {+ const d = new Date(bucket);+ switch (granularity) {+ case "hour":+ d.setUTCHours(d.getUTCHours() + 1);+ return d;+ case "day":+ d.setUTCDate(d.getUTCDate() + 1);+ return d;+ case "week":+ d.setUTCDate(d.getUTCDate() + 7);+ return d;+ case "month":+ d.setUTCMonth(d.getUTCMonth() + 1);+ return d;+ }+};++/** Every bucket start overlapping [from, to), so empty periods still get a bar. */+const getBucketStarts = (+ from: Date,+ to: Date,+ granularity: UsageBreakdownGranularity,+): Date[] => {+ const buckets: Date[] = [];+ for (+ let bucket = startOfBucket(from, granularity);+ bucket < to;+ bucket = nextBucket(bucket, granularity)+ ) {+ buckets.push(bucket);+ }+ return buckets;+};++/**+ * Billable units per bucket, project and unit type. Mirrors the metering+ * definition used for Stripe and ClickHouse Billing: rows counted by+ * `created_at` in a half-open window, scores limited to listable data types,+ * no FINAL.+ */+const getBillableUnitsByBucket = async ({+ projectIds,+ start,+ end,+ granularity,+}: {+ projectIds: string[];+ start: Date;+ end: Date;+ granularity: UsageBreakdownGranularity;+}) => {+ const bucket = `toUnixTimestamp(${BUCKET_SQL[granularity]})`;+ const where = `+ project_id IN {projectIds: Array(String)}+ AND created_at >= {start: DateTime64(3)}+ AND created_at < {end: DateTime64(3)}`;++ const query = `+ SELECT ${bucket} AS bucket, project_id, 'traces' AS unit_type, count() AS count+ FROM traces+ WHERE ${where}+ GROUP BY bucket, project_id+ UNION ALL+ SELECT ${bucket} AS bucket, project_id, 'observations' AS unit_type, count() AS count+ FROM observations+ WHERE ${where}+ GROUP BY bucket, project_id+ UNION ALL+ SELECT ${bucket} AS bucket, project_id, 'scores' AS unit_type, count() AS count+ FROM scores+ WHERE ${where}+ AND data_type IN ({dataTypes: Array(String)})+ GROUP BY bucket, project_id+ `;++ const rows = await queryClickhouse<{+ bucket: string | number;+ project_id: string;+ unit_type: BillableUnitType;+ count: string | number;+ }>({+ query,+ params: {+ projectIds,+ start: convertDateToClickhouseDateTime(start),+ end: convertDateToClickhouseDateTime(end),+ dataTypes: LISTABLE_SCORE_TYPES,+ },+ clickhouseConfigs: { request_timeout: 120_000 },+ });++ return rows.map((row) => ({+ bucket: new Date(Number(row.bucket) * 1000).toISOString(),+ projectId: row.project_id,+ unitType: row.unit_type,+ count: Number(row.count),+ }));+};++/**+ * Billable units of an organization's live projects over [from, to), bucketed+ * by an automatically chosen UTC granularity. Soft-deleted projects are left+ * out, as they are when usage is metered.+ */+export const getOrgUsageBreakdown = async ({+ prisma,+ orgId,+ from,+ to,+}: {+ prisma: PrismaClient;+ orgId: string;+ from: Date;+ to: Date;+}) => {+ const end = new Date(Math.min(to.getTime(), Date.now()));+ const granularity = getUsageBreakdownGranularity(from, end);+ const buckets = getBucketStarts(from, end, granularity).map((bucket) =>+ bucket.toISOString(),+ );++ const projects = await prisma.project.findMany({+ where: { orgId, deletedAt: null },+ select: { id: true, name: true },+ orderBy: { name: "asc" },+ });++ const rows =+ projects.length > 0 && from < end+ ? await getBillableUnitsByBucket({+ projectIds: projects.map((project) => project.id),+ start: from,+ end,+ granularity,+ })+ : [];++ return { granularity, buckets, projects, rows };+};diff --git a/web/src/features/organizations/OrganizationSettingsPage.tsx b/web/src/features/organizations/OrganizationSettingsPage.tsxindex 2623e00169..c262150d21 100644--- a/web/src/features/organizations/OrganizationSettingsPage.tsx+++ b/web/src/features/organizations/OrganizationSettingsPage.tsx@@ -11,6 +11,7 @@ import { useQueryOrganization } from "@/src/features/organizations/hooks";import { useRouter } from "next/router";import { SettingsDangerZone } from "@/src/components/SettingsDangerZone";import { BillingSettings } from "@/src/ee/features/billing/components/BillingSettings";+import { OrganizationUsageBreakdown } from "@/src/features/organization-usage";import { useHasEntitlement, usePlan } from "@/src/features/entitlements";import ContainerPage from "@/src/components/layouts/container-page";import { NoDataOrLoading } from "@/src/components/NoDataOrLoading";@@ -60,6 +61,10 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {organizationId: organization?.id,scope: "gateway:manage",});+ const canReadUsage = useHasOrganizationAccess({+ organizationId: organization?.id,+ scope: "organizationUsage:read",+ });const plan = usePlan();const isLangfuseCloud = isCloudPlan(plan) ?? false;const isCloudBillingAvailable = useIsCloudBillingAvailable();@@ -71,9 +76,14 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {if (!organization) return [];+ const showBillingPage = showBillingSettings && isCloudBillingAvailable;+return getOrganizationSettingsPages({organization,- showBillingSettings: showBillingSettings && isCloudBillingAvailable,+ showBillingSettings: showBillingPage,+ // The billing page embeds the usage breakdown, so the usage page only+ // covers deployments without one (self-hosted).+ showUsageSettings: canReadUsage && !showBillingPage,showOrgApiKeySettings,showAuditLogs,isLangfuseCloud,@@ -87,6 +97,7 @@ export function useOrganizationSettingsPages(): OrganizationSettingsPage[] {export const getOrganizationSettingsPages = ({organization,showBillingSettings,+ showUsageSettings,showOrgApiKeySettings,showAuditLogs,isLangfuseCloud,@@ -105,6 +116,7 @@ export const getOrganizationSettingsPages = ({}>;};showBillingSettings: boolean;+ showUsageSettings: boolean;showOrgApiKeySettings: boolean;showAuditLogs: boolean;isLangfuseCloud: boolean;@@ -194,6 +206,19 @@ export const getOrganizationSettingsPages = ({content: <OrgAuditLogsSettingsPage orgId={organization.id} />,show: showAuditLogs,},+ {+ title: "Usage",+ slug: "usage",+ section: "Organization",+ cmdKKeywords: ["usage", "units", "traces", "observations", "scores"],+ content: (+ <div>+ <Header title="Usage" />+ <OrganizationUsageBreakdown orgId={organization.id} />+ </div>+ ),+ show: showUsageSettings,+ },{title: "Billing",slug: "billing",diff --git a/web/src/features/rbac/constants/organizationAccessRights.ts b/web/src/features/rbac/constants/organizationAccessRights.tsindex 3b96945b1f..e46ee651e6 100644--- a/web/src/features/rbac/constants/organizationAccessRights.ts+++ b/web/src/features/rbac/constants/organizationAccessRights.ts@@ -12,6 +12,7 @@ export const organizationScopes = ["organizationMembers:read","organizationMembers:CUD","langfuseCloudBilling:CRUD",+ "organizationUsage:read","orgAuditLogs:read",] as const;@@ -30,6 +31,7 @@ export const organizationRoleAccessRights: Record<Role, OrganizationScope[]> = {"organizationMembers:CUD","organizationMembers:read","langfuseCloudBilling:CRUD",+ "organizationUsage:read","orgAuditLogs:read",],ADMIN: [@@ -40,6 +42,7 @@ export const organizationRoleAccessRights: Record<Role, OrganizationScope[]> = {"gateway:invoke","organizationMembers:CUD","organizationMembers:read",+ "organizationUsage:read","orgAuditLogs:read",],MEMBER: ["gateway:invoke", "organizationMembers:read"],diff --git a/web/src/features/widgets/index.ts b/web/src/features/widgets/index.tsindex 5621defcc5..f212e6425f 100644--- a/web/src/features/widgets/index.ts+++ b/web/src/features/widgets/index.ts@@ -7,6 +7,8 @@// would close runtime cycles between widgets and those features.export { Chart } from "@/src/features/widgets/chart-library/Chart";export { ChartLoadingState } from "@/src/features/widgets/chart-library/ChartLoadingState";+export { VerticalBarChartTimeSeries } from "@/src/features/widgets/chart-library/VerticalBarChartTimeSeries";+export { downloadChartDataCsv } from "@/src/features/widgets/chart-library/downloadChartDataCsv";export type {DataPoint,LegendSummaryMode,diff --git a/web/src/server/api/root.ts b/web/src/server/api/root.tsindex a8722501a7..cd9463d69e 100644--- a/web/src/server/api/root.ts+++ b/web/src/server/api/root.ts@@ -26,6 +26,7 @@ import { llmApiKeyRouter } from "@/src/features/llm-api-key/server/router";import { llmSchemaRouter } from "@/src/features/llm-schemas/server/router";import { llmToolRouter } from "@/src/features/llm-tools/server/router";import { organizationsRouter } from "@/src/features/organizations/server/organizationRouter";+import { organizationUsageRouter } from "@/src/features/organization-usage/server/organizationUsageRouter";import { organizationApiKeysRouter } from "@/src/features/public-api/server/organizationApiKeyRouter";import { verifiedDomainRouter } from "@/src/ee/features/verified-domains/server/verifiedDomainRouter";import { ssoConfigRouter } from "@/src/ee/features/multi-tenant-sso/server/ssoConfigRouter";@@ -83,6 +84,7 @@ export const appRouter = createTRPCRouter({scoreConfigs: scoreConfigsRouter,dashboard: dashboardRouter,organizations: organizationsRouter,+ organizationUsage: organizationUsageRouter,organizationApiKeys: organizationApiKeysRouter,verifiedDomain: verifiedDomainRouter,ssoConfig: ssoConfigRouter,