Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

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.tsx
index 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.ts
new file mode 100644
index 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.md
index 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 Management
Implemented 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.tsx
index 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/isCl
import { 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 && (
<BillingDiscountView
diff --git a/web/src/features/organization-usage/components/OrganizationUsageBreakdown.tsx b/web/src/features/organization-usage/components/OrganizationUsageBreakdown.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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,