## Summary Provide a "Download CSV" option on the CDot GitLab Credits Usage Dashboard that lets a Billing Manager download all available usage data for the subscription and selected date range, in a single, consistent CSV format. * For the MVC, the selected date range is the current billing month only (because that is the only range the UI supports). * In future, when the dashboard adds month switching and custom date ranges, the download will automatically expand to return all data in that range. The CSV is not a screenshot of the current view. It is a complete dataset for the subscription and date range, with a fixed set of columns, so Billing Managers can do their own filtering and analysis in Excel, Sheets, or BI tools. ## Problem Billing Managers and admins need to: * Pull a dataset for GitLab Credits usage. * Determine who and what is using credits across users, groups, projects, products, and features. * Longer term, analyze usage over custom time frames beyond the current billing month (future UI iterations). Today, the CDot Usage Dashboard: * Shows subscription-level credit usage (commitment, waiver, on-demand) and daily usage trends. * Is initially limited to current month only in the UI. * Has no built-in export. Finance and ops teams are forced to either: * Manually reconstruct usage from screenshots and ad‑hoc queries, or * Ask Support / Data for custom reports. Need for CSV export that: * Returns a dataset for the subscription and date range. * Uses a stable set of columns. * Scales as we add more detail to the underlying usage data (users, groups, projects, features, trials, etc.). ## Proposal ### 1. Behavior 1. **Download CSV** = download all available usage rows for `this subscription` and `this date range`, in the standard CSV format.” 2. **Rows included** * Constrained by: * `subscription_id` (the subscription for the current dashboard) * `start_date` / `end_date` (the date range the dashboard currently supports/uses) * Not dependent on which tab or chart is active (Usage trends vs Usage by user, etc.). * As we add richer data (user/group/project/feature), those show up as additional rows in the CSV. 3. **Columns included** * Always the same set of documented columns (see below). * Some columns may be blank for a given row when that detail does not exist or is not yet available in the backend. * The UI can show any subset of this information; the CSV remains the comprehensive source. This keeps the "mental model" simple: * UI: explore and understand usage. * CSV: download everything we know about usage for this subscription in that time window. ### 2. CSV format One CSV format with: * Row-based records: each row is a usage summary record. * For MVC (aggregate Usage tab), each row represents a unique **date + action** within the subscription (multiple rows per day, one per action type such as Agentic Chat, Code Suggestions, or Duo Code Review). * In a future iteration (Usage by user tab), we can reuse the same CSV format with one row per date + user, without changing the column set. * Comprehensive columns: a consistent set of identifier and metric columns that we can reasonably expose. * Identifiers like `date`, `subscription_id`, `subscription_name`. * Action fields: - `flow_type` user-friendly category (for example: `Code Suggestions`, `Agent Platform`, `Duo Code Review`). - `action_code` raw event type (for example: `CODE_SUGGESTION_SHOWN_IN_IDE`, `AGENT_PLATFORM_SESSION_STARTED`, `FIND_NOTHING_TO_REVIEW_DUO_CODE_REVIEW_ON_MR`). * Usage and credit metrics like `usage_events`, `total_credits_used`, and wallet breakdown columns (described in the Columns section). * Forward-compatible: when we add new usage dimensions (user, group, project, feature, additional actions), we: * Add more rows (for example, additional actions or users on a given date), and/or * Populate additional columns that are already part of the shared format, but we do not change or remove existing columns or define separate CSV formats per tab/view. #### 2.1 Level of detail For the MVC (aggregate Usage tab): * we support **daily, action-level rows** within the subscription (one row per distinct action per day, such as Agentic Chat, Code Suggestions, Agent Platform sessions, or Duo Code Review events). * `flow_type` groups actions into feature areas (for example, `Code Suggestions`, `Agent Platform`, `Duo Code Review`). * `action_code` captures the specific event, such as: * `CODE_SUGGESTION_SHOWN_IN_IDE`, `CODE_SUGGESTION_ACCEPTED_IN_IDE`, `CODE_SUGGESTION_REJECTED_IN_IDE` * `AGENT_PLATFORM_SESSION_STARTED`, `AGENT_PLATFORM_SESSION_STOPPED` * `ENCOUNTER_DUO_CODE_REVIEW_ERROR_DURING_REVIEW`, `EXCLUDED_FILES_FROM_DUO_CODE_REVIEW`, `FIND_NOTHING_TO_REVIEW_DUO_CODE_REVIEW_ON_MR` * `usage_events` represents the **count of events** for that `action_code` on that `date` for the subscription. * Credit-related columns (for example, `total_credits_used`, `commitment_credits_used`, `waiver_credits_used`, `on_demand_credits_used`) represent the credits attributed to those events for that `date + action` combination. In a future **Usage by user** export, we can extend this to **daily, user‑level rows** (one row per `date + user`) using the same columns. ### 3. Columns #### 3.1 Identifier columns These columns identify what each row refers to. They are shared across both exports, but different subsets are populated depending on which report is being downloaded: - **Aggregate Usage export (from “Usage” tab):** - Rows are grouped by **date + action**. - Action-related identifiers (`flow_type`, `action_code`) are populated. - User identifiers remain blank (or are omitted from the grouping). - **Usage by user export (future, from “Usage by user” tab):** - Rows are grouped by **date + user** or **date + user + action** (depending on final design). - User identifiers (`user_id`, `username`, `user_email`) are populated (subject to privacy settings). - Action-related identifiers are also available so we can show per-user breakdown by flow/action if desired. **Core identifiers (Defined for the CSV. Note that some are only populated in non‑MVC (future) versions):** - `date` – ISO 8601 date (`YYYY-MM-DD`) for the usage summarized in this row. - `subscription_id` - `subscription_name` **Action / feature identifiers:** - `flow_type` – user-friendly feature area for the event flow. Examples: - `Code Suggestions` - `Agent Platform` - `Duo Code Review` - `Duo Chat` - `action_code` – raw event/action type used for aggregation. Examples: - Code Suggestions: - `CODE_SUGGESTIONS_REQUESTED` (legacy) - `CODE_SUGGESTION_SHOWN_IN_IDE` - `CODE_SUGGESTION_ACCEPTED_IN_IDE` - `CODE_SUGGESTION_REJECTED_IN_IDE` - `CODE_SUGGESTION_DIRECT_ACCESS_TOKEN_REFRESH` (legacy) - Agent Platform: - `AGENT_PLATFORM_SESSION_STARTED` - `AGENT_PLATFORM_SESSION_STOPPED` - Duo Code Review: - `ENCOUNTER_DUO_CODE_REVIEW_ERROR_DURING_REVIEW` - `EXCLUDED_FILES_FROM_DUO_CODE_REVIEW` - `FIND_NOTHING_TO_REVIEW_DUO_CODE_REVIEW_ON_MR` **NOT FOR MVC: User identifiers (populated only when user data visibility is enabled, and primarily in the Usage by user export):** - `user_id` – internal user identifier in GitLab. - `username` – GitLab username, when allowed by the **Display GitLab Credits user data** setting. - `user_email` – user email, only when allowed by the same setting and when appropriate for the environment. * NOT FOR MVC: When Display GitLab Credits user data is disabled: * The aggregate export still returns **date + action** rows, but all `user_*` fields are left blank. * The future Usage by user export is either disabled, or returns only aggregated data without user attribution (implementation decision). **Context identifiers (nice-to-have, may be blank in MVC):** - `customer_id` – customer/account identifier in CustomersDot or Zuora (if available). - `instance_type` – `gitlab.com`, `self-managed`, or `dedicated`. - `namespace_id`, `namespace_path` - `group_id`, `group_path` - `project_id`, `project_path` These context fields allow future iterations to attribute usage to namespaces/groups/projects without changing the CSV format. **Product / meter identifiers (nice-to-have):** - `product_name` – for example, `Duo Agent Platform`. - `feature_name` – finer-grained label for the feature (for example, `Duo Chat`, `Duo Code Review`). - `meter_name` – internal meter key (for example, `duo_agent_sessions`, `duo_code_suggestions_events`), if different from `flow_type` / `action_code`. #### 3.2 Metric columns These columns quantify usage and credits for each row’s identifier combination. For the aggregate Usage export (date + action): - Each row summarizes all events of a given `action_code` on a given `date` for the subscription. - Metrics represent totals for that date + action combination. NOT FOR MVC: For the Usage by user export (date + user \[+ action\]): - Each row summarizes all events for a given user on a given date, optionally split by `action_code`. - Metrics represent totals for that date + user (+ action) combination. **Event volume:** - `usage_events` – count of raw events represented by this row. - Aggregate export: number of events for this `action_code` on this `date` for the subscription. - Usage by user export: number of events for this `user` (and optionally `action_code`) on this `date`. **Credits and wallets:** - `total_credits_used` – total GitLab Credits consumed by the events in this row. - `included_credits_used` – portion of credits that came from per-user included/free monthly allocation. - `commitment_credits_used` – portion of credits drawn from the Monthly Commitment Pool. - `waiver_credits_used` – portion of credits offset by Monthly Waivers. - `trial_credits_used` – portion of credits covered by trial credit buckets, if applicable. - `on_demand_credits_used` – portion of credits billed as on-demand usage. - `free_monthly_allocation_used` – explicit field for included/free monthly allocation when we want to call this out by name (can mirror `included_credits_used` where appropriate). - `credits_charged_usd` – monetary amount charged for the usage in this row in USD, when we can safely map usage to billing at this level. This can remain blank in MVC and be populated in a later “billing reconciliation” iteration. **Context / audit metrics:** - `usage_period_start` – start of the billing period shown in the dashboard (for example, `2025-10-01`). - `usage_period_end` – end of the billing period (for example, `2025-10-31`). - `data_freshness_timestamp` – timestamp of the most recent usage data included in this export. Example: ``` date,subscription_id,subscription_name,customer_id,instance_type,flow_type,action_code,usage_events,total_credits_used,included_credits_used,commitment_credits_used,waiver_credits_used,trial_credits_used,on_demand_credits_used,free_monthly_allocation_used,credits_charged_usd,usage_period_start,usage_period_end,data_freshness_timestamp 2025-10-13,sub_12345,"Acme Corp – GitLab Ultimate",cust_98765,gitlab.com,"Code Suggestions","CODE_SUGGESTION_SHOWN_IN_IDE",1200,18,8,6,2,0,2,8,2.00,2025-10-01,2025-10-31,2025-10-14T03:00:00Z 2025-10-13,sub_12345,"Acme Corp – GitLab Ultimate",cust_98765,gitlab.com,"Code Suggestions","CODE_SUGGESTION_ACCEPTED_IN_IDE",300,12,5,5,1,0,1,5,1.20,2025-10-01,2025-10-31,2025-10-14T03:00:00Z 2025-10-13,sub_12345,"Acme Corp – GitLab Ultimate",cust_98765,gitlab.com,"Agent Platform","AGENT_PLATFORM_SESSION_STARTED",80,40,10,20,5,0,5,10,4.00,2025-10-01,2025-10-31,2025-10-14T03:00:00Z ``` ## 4. UX/UI ### 4.1 Entry point * Add a **“Download CSV”** button to the usage section of the CDot GitLab Credits dashboard. * The button should be visually associated with the primary usage visualization, but its behavior is clearly documented as: “Download all available GitLab Credits usage data for this subscription and date range as a CSV.” ### 4.2 Date range behavior * The export always uses the same date range as the dashboard: * **MVC:** current billing month only. * **Later:** whatever month/custom range is selected once we add month navigation/custom range pickers. * If a user changes the date range in the UI (in future), the CSV automatically returns all data for that new range. ### 4.3 Views and filters * The CSV ignores the current tab/view (“Usage trends”, “Usage by user”, etc.) and most presentation filters. * The only required filters that affect which rows appear are: * Subscription (implicitly the current subscription). * Date range (`start_date`, `end_date`). If we introduce additional **hard filters** in the dashboard that truly restrict the underlying dataset (for example, a “Product” or “Feature” filter that limits the chart to only DAP vs some future product), we can optionally reuse those as query parameters for the CSV. Even then, the CSV still returns **all rows** that match those filters, not just whatever is visible in a single chart. ## 5. MVC vs future iterations ### 5.1 MVC (first iteration) **Scope:** - **Date range:** current billing month only (matching the dashboard UI). - **Tab / report:** aggregate Usage tab. - **Rows:** one row per **date + action** within the subscription\ (multiple rows per date, one for each `action_code` that occurred). **Columns (MVC minimum):** - Identifiers: - `date` - `subscription_id` - `subscription_name` - `flow_type` (for example: `Code Suggestions`, `Agent Platform`, `Duo Code Review`) - `action_code` (for example: `CODE_SUGGESTION_SHOWN_IN_IDE`, `AGENT_PLATFORM_SESSION_STARTED`, `FIND_NOTHING_TO_REVIEW_DUO_CODE_REVIEW_ON_MR`) - Usage volume: - `usage_events` – number of events for this `action_code` on this `date` for this subscription. - Credit metrics (populated where available): - `total_credits_used` - `commitment_credits_used` - `waiver_credits_used` - `trial_credits_used` - `on_demand_credits_used` - `included_credits_used` - `free_monthly_allocation_used` - Context: - `usage_period_start` - `usage_period_end` - `data_freshness_timestamp` Other identifier columns (user, group, project, meter) can remain blank in MVC and be populated later as the underlying data model is enriched, without changing this format. This MVC gives Billing Managers a per‑day, per‑action breakdown of usage and credits for the current month from the aggregate Usage tab. ### 5.2 Future iterations Without changing the CSV format, we can add: - **Usage by user export (Usage by user tab)** - New export grouped by date + user or date + user + action. - Populates `user_id`, `username`, and optionally `user_email` (subject to Display GitLab Credits user data). - Reuses `flow_type`, `action_code`, and all existing metric columns. - **Custom date ranges and month navigation** - UI supports selecting historical months and custom ranges. - Exports return all rows for the selected range (same columns, more/less rows). - **Richer attribution** - Start populating: - Namespace / group / project fields (`namespace_*`, `group_*`, `project_*`). - `product_name`, `feature_name`, `meter_name`. - Potentially add more granular rows (for example, per project per date+action), using the same column set. - **More finance-friendly fields** - Populate `credits_charged_usd` and any additional finance context (for example, `billing_country`, `sales_region`) when billing alignment is ready. - Keep these as additive columns so existing consumers are not broken.