## Why are we doing this work The **Total usage** card now counts billable plus non-billable usage, but the **Usage by user** and **Usage by product** tabs, the user drill-down, and the **Active users** card still count billable usage only. The rows in the tabs do not add up to the card above them. <details><summary>Background</summary> - https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260725 (merged 2026-10-09) made the **Total usage**, **Daily average**, and **Peak day usage** cards count billable plus non-billable usage. Before that, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260225 added non-billable usage to the daily chart as one series per reason next to **Billable usage**, with a "Billable: X credits" header next to "Non-billable: X credits". - In the review thread (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260725#note_3984213170, https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260725#note_3985241545), @timnoah said the chart header split is not enough context. Admins and owners will expect **Usage by user** and **Usage by product** to show total usage. He proposed either a total with a billable and non-billable split, or a filter between them. He also asked whether a user's usage log shows both kinds of usage. - The dashboard description says "This dashboard displays usage of all GitLab Duo Agent Platform features, including non-billable beta and experiment features" ([app.vue#L305-319](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/wallet_agnostic_credits_dashboard/index/components/app.vue#L305-319)). The tabs contradict that today. - Epic https://gitlab.com/groups/gitlab-org/-/work_items/23876 requires that "Non-billed usage appears in both the group and instance dashboard and the end-user view" (requirement 2) and that "Billed and non-billed usage are labeled so the subscription total and the per-user totals still reconcile" (requirement 3). The Customers Portal dashboard stays billable-only. - History: https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/16965 (merged 2026-09-02) removed all skipped usage from every CustomersDot dashboard read, to fix the totals mismatch in https://gitlab.com/gitlab-org/gitlab/-/work_items/616203 (still open). Non-billable usage then came back only as the subscription-level `nonBillableUsage` field (https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17365). Now that the **Total usage** card adds it back, the same kind of mismatch is visible again. GitLab code links below point at `master` right after merge request 260725 merged. CustomersDot links point at `main`. Both as of 2026-10-09. </details> ## Answer: does the user usage log show non-billable usage? No. The user drill-down shows billable usage only, in both its total card and its usage event log. The drill-down is consistent with the tabs, but both are inconsistent with the **Total usage** card. <details><summary>Evidence</summary> - CustomersDot `EventsResolver` ([events_resolver.rb#L19-32](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/graphql/resolvers/subscriptions/gitlab_credits/users_usage/events_resolver.rb#L19-32)) calls `EnrichedEventsQueryBuilder#for_subscription_and_user`. Its shared `base_query` joins `usage_billing_consumed` and filters `SkipConsumption != TRUE` ([enriched_events_query_builder.rb#L80-94](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/query_builders/billing/usage/enriched_events_query_builder.rb#L80-94)). - This is intentional and documented in CustomersDot: "a skipped event is never billed, so it must not appear in a usage listing" ([usage-billing-and-credits.md#L309-317](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/doc/agents/usage-billing-and-credits.md?plain=1#L309-317)). Showing non-billable events in the log needs CustomersDot to revisit that decision. - The GitLab GraphQL description of the user's `events` field already says "Billable events from the user." ([user_type.rb#L24-32](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/graphql/types/gitlab_subscriptions/subscription_usage/user_type.rb#L24-32)). </details> ## How each number is populated today Non-billable usage only reaches the subscription-level summary cards and the chart. Every per-user and per-product number is billable-only. <details><summary>Data source for each dashboard element</summary> | Dashboard element | Where the number comes from | Includes non-billable? | |---|---|---| | **Total usage** card | Frontend adds billable `creditsUsed` and the totals from `nonBillableUsage` ([app.vue#L176-185](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/wallet_agnostic_credits_dashboard/index/components/app.vue#L176-185)). `creditsUsed` comes from CustomersDot `total_gitlab_credits_for_subscription` with `SkipConsumption != TRUE` ([enriched.rb#L474-497](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/models/billing/usage/enriched.rb#L474-497)). `nonBillableUsage` comes from `non_billable_daily_credits_by_product` with `SkipConsumption = TRUE` ([enriched.rb#L536-568](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/models/billing/usage/enriched.rb#L536-568)). | Yes | | **Daily average** and **Peak day usage** cards | Frontend adds non-billable usage to the billable `dailyAverage` and `dailyUsage` ([app.vue#L186-217](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/wallet_agnostic_credits_dashboard/index/components/app.vue#L186-217)). | Yes | | **Active users** card | `usersUsage.totalActiveUsers`: distinct users with `SkipConsumption != TRUE AND GitlabCredits > 0` ([enriched.rb#L570-594](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/models/billing/usage/enriched.rb#L570-594)). The summary table's `ActiveUsersState` uses the same condition ([105_filter_skip_consumption_in_subscription_daily_mv.sql](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/db/clickhouse/105_filter_skip_consumption_in_subscription_daily_mv.sql)). | No. Users with only non-billable usage are not counted. | | Chart | Billable `dailyUsage` plus one series per non-billable reason. | Yes, split | | **Usage by user**, default sort (total credits used) | GitLab asks CustomersDot for `usersUsage.consumers`. The order comes from Postgres `wallet_transactions` debits in `ConsumersFinder` ([consumers_finder.rb#L30-39](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/finders/gitlab_credits/consumers_finder.rb#L30-39)). The value shown comes from ClickHouse `total_credits_used_for_subscription_users`, which only counts events in `usage_billing_consumed` with `SkipConsumption != TRUE` ([enriched.rb#L204-229](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/models/billing/usage/enriched.rb#L204-229), [users_usage_helper.rb#L9-16](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/helpers/graphql/users_usage_helper.rb#L9-16)). GitLab then drops users whose value is 0 ([user_usage.rb#L137-167](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/lib/gitlab_subscriptions/subscriptions_usage/user_usage.rb#L137-167)). | No. Users with only non-billable usage are not listed. | | **Usage by user**, sorted by name | GitLab lists group members (or instance users) from its own database, then reads each user's value from CustomersDot `usersUsage.users(userIds:)`, which uses the same ClickHouse query as the row above. | No | | **Usage by product** | `products[].creditsUsed` from CustomersDot `total_gitlab_credits_by_product` with `SkipConsumption != TRUE` ([enriched.rb#L499-534](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/models/billing/usage/enriched.rb#L499-534), [product_type.rb#L25-34](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/graphql/types/subscriptions/gitlab_credits/product_type.rb#L25-34)). The **Share** column divides each product by the billable `creditsUsed` ([products_list.vue#L23-26](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/wallet_agnostic_credits_dashboard/index/components/products_list.vue#L23-26), [app.vue#L431](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/wallet_agnostic_credits_dashboard/index/components/app.vue#L431)). | No | | User drill-down, **total credits used** card | `usersUsage.users(username:).usage.totalCreditsUsed`, same ClickHouse query as **Usage by user**. | No | | User drill-down, usage event log | See the answer above ([enriched_events_query_builder.rb#L80-94](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/query_builders/billing/usage/enriched_events_query_builder.rb#L80-94)). | No, on purpose | | User drill-down, flow type filter options | `usedFlowTypes`, built on the same base query as the event log. | No | | Personal dashboard (**User settings > GitLab Credits**) | `currentUser.creditsUsage`: the user's `totalCreditsUsed` and daily usage from the same per-user CustomersDot queries ([credits_usage.rb#L36-51](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/lib/gitlab_subscriptions/subscriptions_usage/user/credits_usage.rb#L36-51)). | No | Why non-billable usage never shows up per user: the consumption pipeline only takes billable rows (`SkipConsumption != TRUE AND GitlabCredits > 0`; [enrichment_service.rb#L330-336](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/services/billing/usage/enrichment_service.rb#L330-336), [enriched.rb#L596-658](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/models/billing/usage/enriched.rb#L596-658)). Skipped events never reach `usage_billing_consumed` (ClickHouse) or `wallet_transactions` (Postgres), and every per-user read uses one of those two. </details> ## Pre-existing issues found while tracing the data These are not caused by merge request 260725, but they affect the same tabs and the same reconciliation. 1. **Usage by product** ignores the **Products** filter, but its **Share** column divides by the filtered `creditsUsed`. With a filter applied, shares can add up to more than 100%. This also blocks a correct non-billable column for products, because `nonBillableUsage` does follow the filter. <details><summary>Evidence</summary> GitLab's products query sends no `flowTypes` ([subscription_usage_client.rb#L520-542](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/lib/gitlab/subscription_portal/subscription_usage_client.rb#L520-542)), `SubscriptionUsage#products` is memoized without flow types ([subscription_usage.rb#L202-209](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/lib/gitlab_subscriptions/subscription_usage.rb#L202-209)), and CustomersDot `ProductType#credits_used` takes no flow types ([product_type.rb#L25-34](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/graphql/types/subscriptions/gitlab_credits/product_type.rb#L25-34)). </details> 1. The default **Usage by user** sort ignores the **Products** filter. With a filter, rows can be out of order, and pages can come back short. <details><summary>Evidence</summary> CustomersDot orders consumers by unfiltered wallet debits: `consumers` passes no flow types to `ConsumersFinder` ([users_usage_type.rb#L62-67](https://gitlab.com/gitlab-org/customers-gitlab-com/-/blob/8dc3c8365114f89f64675d7703ab402ea4b161c9/app/graphql/types/subscriptions/gitlab_credits/users_usage_type.rb#L62-67)), but the value shown is filtered. GitLab then drops rows whose filtered value is 0 ([user_usage.rb#L137-167](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/lib/gitlab_subscriptions/subscriptions_usage/user_usage.rb#L137-167)). </details> 1. The user drill-down ignores the dashboard's date range. With **Last month** selected, a user's row and their drill-down show different periods. <details><summary>Evidence</summary> The link only carries the username ([users_list.vue#L53-56](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/wallet_agnostic_credits_dashboard/index/components/users_list.vue#L53-56)). Both drill-down queries call `subscriptionUsage(namespacePath:)` without `startDate` or `endDate` ([get_user_subscription_usage.query.graphql#L3-4](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/usage_billing/users/show/graphql/get_user_subscription_usage.query.graphql#L3-4), [get_user_subscription_usage_events.query.graphql#L13](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/assets/javascripts/usage_quotas/usage_billing/users/show/graphql/get_user_subscription_usage_events.query.graphql#L13)). The resolver then defaults to the current month ([subscription_usage_resolver.rb#L30-31](https://gitlab.com/gitlab-org/gitlab/-/blob/68916036b7c78060c7fc627dcdd7ecf000a36673/ee/app/graphql/resolvers/gitlab_subscriptions/subscription_usage_resolver.rb#L30-31)). </details> ## Decisions Agreed in Slack on 2026-10-27 and written up in https://gitlab.com/gitlab-org/gitlab/-/work_items/633154#note_4099142904. 1. **API contract.** CustomersDot keeps `totalCreditsUsed` and `creditsUsed` billable-only and exposes non-billable usage in separate, additive fields. GitLab adds the two, the way the **Total usage** card already does. This keeps the billable numbers matching Customers Portal (epic requirement 3) and avoids a transient mislabel on the personal dashboard, whose chart header says "Billable". 1. **Split columns or filter?** Deferred. For Orbit GA, **Usage by user** shows a single **Total credits used** column with billable plus non-billable. The billable / non-billable split (or a "Usage Type" filter) comes with the customer-friendly usage labels that @timnoah and @brothwell are designing, which is not blocking for GA. 1. **Default sort of Usage by user.** Unchanged: CustomersDot still orders by wallet debits. Users with only non-billable usage are now listed, but sort last. A sort by total is iteration 2 (pre-existing issue 2). 1. **Usage event log and flow type filter.** Follow-up, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/636698 (G1–G3 here for the full picture), additive: an opt-in `includeNonBillable` argument on CustomersDot (default false, so older GitLab versions see no change) plus `billable` / `skipReason` per event; the drill-down labels non-billable rows with the chart's skip-reason labels. Not blocking Orbit GA. 1. **Active users card.** Out of scope here; stays billable-only. 1. **Usage by product and the Products filter.** Pre-existing issue 1 stays open; A only adds the filtered non-billable part to each row. 1. **Personal dashboard.** In scope (B and C), tracked under https://gitlab.com/groups/gitlab-org/-/work_items/24080 (https://gitlab.com/gitlab-org/gitlab/-/work_items/634215, https://gitlab.com/gitlab-org/gitlab/-/work_items/634216, docs https://gitlab.com/gitlab-org/gitlab/-/work_items/634217). It needs no further CustomersDot work: the per-user `nonBillableUsage` field from https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17539 is deployed. ## Implementation plan | \# | Change | Repo | Depends on | MR | |----|--------|------|------------|----| | A | **Usage by product includes non-billable usage** | GitLab | Nothing | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265171 — :white_check_mark: merged 2026-10-28; review follow-ups in https://gitlab.com/gitlab-org/gitlab/-/work_items/636643 | | B | **Personal dashboard backend: expose the user's `nonBillableUsage`** — tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/634215 (https://gitlab.com/groups/gitlab-org/-/work_items/24080) | GitLab | Per-user `nonBillableUsage` in CustomersDot (https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17539, deployed) | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265505 — :white_check_mark: merged 2026-10-28 | | C | **Personal dashboard frontend: show non-billable usage** — tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/634216 (https://gitlab.com/groups/gitlab-org/-/work_items/24080) | GitLab | B merged | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265530 — :white_check_mark: merged 2026-10-28 | | D | **Additive per-user non-billable total for multi-user reads** | CustomersDot | Nothing | https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17683 — :white_check_mark: merged 2026-10-28 | | E1 | **Usage by user backend: expose the user's `nonBillableCreditsUsed`** | GitLab | D merged and deployed | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265548 — :white_check_mark: merged 2026-10-28 | | E2 | **Usage by user frontend: rows and drill-down total add non-billable usage** | GitLab | E1 merged and rolled out | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265553 — :white_check_mark: merged 2026-10-28 | | F | **Docs** — one MR covering every change here, including G1–G3; personal dashboard part tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/634217; **Usage by product** docs shipped in A | GitLab | G3 merged (the events paragraph describes G3) | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266180 — :white_check_mark: merged 2026-10-30 | | G1 | **CustomersDot: `includeNonBillable` on `events` and `usedFlowTypes`, `billable`/`skipReason` per event** — follow-up, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/636698 | CustomersDot | D merged; retargeted to `main` | https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17693 — :white_check_mark: merged 2026-10-29 | | G2 | **Drill-down backend: mirror the argument and the event fields** — follow-up, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/636698 | GitLab | G1 deployed for the rows to show; until then G2 retries with the billable-only query | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265819 — :white_check_mark: merged 2026-10-29 | | G3 | **Drill-down frontend: list non-billable events with a skip-reason badge, filter includes their flows** — follow-up, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/636698 | GitLab | G2 merged and fully rolled out on GitLab.com (sends a new argument; stacked on G2's branch) | https://gitlab.com/gitlab-org/gitlab/-/merge_requests/265821 — :white_check_mark: merged 2026-10-29 | **Status (2026-10-30):** everything is merged. A, B, C, D, E1 and E2 on 2026-10-28; G1, G2 and G3 on 2026-10-29; F (docs) on 2026-10-30, plus https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266559, which capitalises the drill-down **Total credits used** card label to match the docs. Non-blocking review follow-ups from A stay open in https://gitlab.com/gitlab-org/gitlab/-/work_items/636643. ``` A ──────────────────────────────────────────────┐ B ──► C ────────────────────────────────────────┤ D ──► E1 ──► E2 (figures show once D deploys) ──┴──► F D ──► G1 ──► G2 ──► G3 (rows show once G1 deploys) ``` A, B, D and E1 have no merge-order dependencies. C waits for B, G1 waits for D, G2 can merge any time, and E2 and G3 wait for E1 and G2 respectively to be fully rolled out on GitLab.com: deploys are rolling, so a frontend that selects a new field in the same release can reach a node that doesn't serve it yet. `@gl_introduced` only covers self-managed version skew, which is why backend and frontend are separate MRs everywhere (B/C, E1/E2). <details><summary>What each change contains</summary> **A. Usage by product** (GitLab, frontend). Adds each product's non-billable usage, from the `nonBillableUsage` the dashboard already loads, to its row, and computes **Share** against the **Total usage** card. Updates the docs for that tab. No new API. **B. Personal dashboard backend** (GitLab). `SubscriptionUsageClient#get_non_billable_usage_for_user_id` reads the per-user `nonBillableUsage` in its own request with the existing `NON_BILLABLE_USAGE_UNAVAILABLE` handling and ClickHouse read timeout. `CreditsUsage#non_billable_usage` returns `nil` (not `[]`) when CustomersDot can't read it. New `GitlabSubscriptionUserCreditsUsageNonBillableUsage` type authorizing `read_user`, and a nullable `nonBillableUsage` field on `GitlabSubscriptionUserCreditsUsage`. **C. Personal dashboard frontend** (GitLab). **Credits used in this billing period**, **Total usage**, **Daily average usage** and **Peak day usage** count billable plus non-billable; the chart keeps its Billable / Non-billable header and stacked bars. Non-billable usage is read in its own query (`@gl_introduced(version: "19.6.0")`, `no-cache`), twice: once for the billing-period card and once with the filters. A failure there falls back to billable usage only. Hidden products are left out, as on the group dashboard. **D. CustomersDot: additive per-user non-billable total.** `nonBillableCreditsUsed: Float` on `GitlabCreditsUser` and `GitlabCreditsConsumer`, returned for any number of users. Resolved with a `BatchLoader` under its own key: one `usage_billing_enriched` scan per subscription grouped by `Subject`, limited to displayable products and the `flowTypes` filter, cached until the next consumption run. A ClickHouse, Faraday or timeout error resolves every user to `null` with a warning, no GraphQL error, and is not cached. No existing field changes meaning. Supersedes https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17665. **E1. GitLab backend: Usage by user.** `GET_USERS_USAGE_QUERY` and `GET_CONSUMERS_QUERY` select `nonBillableCreditsUsed`, retrying without it while CustomersDot doesn't know the field (the same fallback as `entityType`). New nullable `nonBillableCreditsUsed` on `GitlabSubscriptionUsageUserUsage`. The credits sort keeps users whose only usage is non-billable. **E2. GitLab frontend: Usage by user.** The **Usage by user** row and the drill-down **total credits used** card show billable plus non-billable. Both queries select the field with `@gl_introduced(version: "19.6.0")`. Stacked on E1; merge only after E1 is fully rolled out on GitLab.com. **F. Docs.** `doc/subscriptions/gitlab_credits_dashboard.md`: **Usage by user**, the drill-down total and the personal dashboard include non-billable usage; the chart splits billable from non-billable. (A updates the **Usage by product** section itself.) **G1. CustomersDot: non-billable events** (details and verification in https://gitlab.com/gitlab-org/gitlab/-/work_items/636698). `events` and `usedFlowTypes` take `includeNonBillable: Boolean = false`. When true, the query `UNION ALL`s the billable branch with the skipped rows of displayable products (the `nonBillableCreditsUsed` rule), aliased `events` and ordered by `Timestamp` so the existing cursor pagination applies; skipped rows keep only the latest ingestion per `EventId`. Every event carries `billable` and `skipReason` (null for billable events and for skipped events without a recorded reason). Query lifted from https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17665. Stacked on D for `Product.displayable_flow_type_ids`. **G2. GitLab backend: non-billable events.** Mirrors `includeNonBillable` on `GitlabSubscriptionUsageUser.events` / `.usedFlowTypes` and adds `billable` / `skipReason` to `GitlabSubscriptionUsageUserEvent`, all defaulting to the billable-only behaviour. While CustomersDot hasn't deployed the argument, the client retries with the billable-only query. The opt-in query drops the deprecated `eventType` to stay under CustomersDot's self-managed complexity cap (200): GitLab's events query was at 171 and the two fields over a 20-row page cost 40; `eventType` is documented as null in that mode. **G3. GitLab frontend: non-billable events.** The drill-down event log queries `events(includeNonBillable: true)` and shows a neutral badge with the skip reason on non-billable rows, reusing the chart's labels (Promotional / Beta / Other); the flow type filter queries `usedFlowTypes(includeNonBillable: true)`. Stacked on G2; merge only after G2 is fully rolled out on GitLab.com, because a new argument has no `@gl_introduced` fallback. </details> ### Trade-offs - **Older self-managed versions** keep seeing billable-only in **Usage by user** and the drill-down until they upgrade to a release with E2, because the addition happens in GitLab. Accepted: a stable API contract is worth more than a CustomersDot-only fix, and the personal dashboard is GitLab.com only. - **Sort order:** users with only non-billable usage sort last on the default sort (decision 3). - **Rounding:** each row is rounded on its own, so a page's rows can differ from the card by a rounding unit. ### Out of scope (track separately) - **Active users** card (decision 5). - CSV export of promotional usage (open question from @cmeddaugh in Slack). - Pre-existing issues 1 to 3 above, and the iteration-2 sort by total. - Customer-friendly "Usage Type" labels and filter (@timnoah, @brothwell). - **Daily average** dividing by elapsed days: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260725#note_3985132680 ## Relevant links - Plan discussion: https://gitlab.com/gitlab-org/gitlab/-/work_items/633154#note_4099142904 (supersedes https://gitlab.com/gitlab-org/gitlab/-/work_items/633154#note_4096935294) - Review thread: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260725#note_3984213170 - Merge request that changed the summary cards: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260725 - Chart merge request: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260225 - Follow-up issue for that merge request: https://gitlab.com/gitlab-org/gitlab/-/work_items/632862 - Epics: https://gitlab.com/groups/gitlab-org/-/work_items/23876 (dashboard), https://gitlab.com/groups/gitlab-org/-/work_items/24080 (personal dashboard) - Earlier totals mismatch: https://gitlab.com/gitlab-org/gitlab/-/work_items/616203 - CustomersDot: skipped usage removed from reads: https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/16965 - CustomersDot: subscription-level `nonBillableUsage`: https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17365 - CustomersDot: per-user `nonBillableUsage`: https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17539 - CustomersDot: superseded approach that changed `totalCreditsUsed`: https://gitlab.com/gitlab-org/customers-gitlab-com/-/merge_requests/17665 ## Non-functional requirements - [x] **Documentation (F):** https://gitlab.com/gitlab-org/gitlab/-/merge_requests/266180 updates https://docs.gitlab.com/subscriptions/gitlab_credits_dashboard/ (source `doc/subscriptions/gitlab_credits_dashboard.md`) for **Usage by user**, the user drill-down (including the non-billable events of G) and the personal dashboard. A covered **Usage by product**. GraphQL reference regenerated in B, E1 and G2. - [x] **Feature flag:** none. Every new field is additive and nullable, and the frontend falls back to billable usage when a field is missing or null. No CustomersDot kill switch: the new ClickHouse read in D is one bounded scan per subscription per cache window, and a failure nulls only the new field. - [x] **Performance:** the new reads hit `usage_billing_enriched`, bounded by `with_query_timeout` and the ingestion-timestamp window, and cached until the next consumption run (D, and B through the existing per-user `nonBillableUsage`). D is not measured on production-sized data; after deploy, watch `Unexpected error in ClickHouse querying` entries tagged `usage_error_monitoring` from `Billing::Usage::Enriched`. - [x] **Failure isolation:** B and C read non-billable usage in separate requests and queries so a failure never blanks the billable dashboard. D resolves to `null` without a GraphQL error. E2's row and card fall back to billable-only when the field is null. - [x] **Compatibility:** no existing field changes meaning on either side. Backend and frontend ship in separate MRs (B/C, E1/E2) so every GitLab.com node serves a field before any client selects it. New frontend fields also use `@gl_introduced(version: "19.6.0")` for self-managed; E1's client retries without `nonBillableCreditsUsed` until CustomersDot deploys D. - [x] **Testing:** request and unit specs for every new field and for the unavailable path; Jest specs that the cards and rows add billable plus non-billable and fall back to billable-only. ## Verification steps 1. Run GDK in SaaS mode with a local CustomersDot on D, as described in "How to set up and validate locally" in https://gitlab.com/gitlab-org/gitlab/-/merge_requests/260725. 1. In CustomersDot, seed two users: one with billable and non-billable Orbit usage, one with non-billable usage only (`bin/populate_usage_data ... --team-member --skip-reason promo`), then enrich and consume. 1. Visit `/groups/<group>/-/settings/gitlab_credits_dashboard` and check: - **Usage by product:** the rows add up to the **Total usage** card and the shares add up to 100% (A). - **Usage by user:** both users are listed, each row is billable plus non-billable, and the rows add up to the card (E1, E2). - The user drill-down **total credits used** card matches the user's row (E2). The event log lists the non-billable events with a **Non-billable usage (Promotional)** badge and adds up to the card; the flow type filter offers the Orbit flows (G1–G3). 1. As the first user, visit `/-/profile/gitlab_credits_dashboard`: the cards count billable plus non-billable, and the chart header splits them with a **Promotional** series stacked on **Billable usage** (B, C). 1. Make the non-billable read fail (for example, stop ClickHouse responses for `SkipConsumption = TRUE` queries). Every card and row shows billable usage only, with no error. Per-user billable totals only count events that consumption has already processed, while the subscription total counts them right away. Right after new usage, the per-user sum can trail the card until the next consumption run. That is expected.