cockroachdb / cockroachdb/cockroach

obs/ash: add resource group to Active Session History

Open
#172,861 0 comments 0 reactions 0 assignees View on GitHub
A-sql-observability C-enhancement O-agent T-observability
Dominant language
Go
Stars
32.5k
Forks
4.1k
PR merge metrics
PR metrics pending

Description

**Is your feature request related to a problem? Please describe.**

Resource groups were introduced as a SQL-level construct in v26.3 (`CREATE/ALTER/DROP/SHOW RESOURCE GROUP`, backed by `system.resource_groups`, gated behind `sql.experimental_resource_groups.enabled` + admin role). A resource group is bound to a session via `SET resource_group = ''` and stamped onto every transaction for admission control.

ASH samples in-flight work and enriches each sample with per-execution session attributes — `user`, `app_name`, `plan_gist`, `canary_stats`, `txn_id`, `session_id` — but has no notion of resource group. Operators running workload management can't answer "what fraction of active session time belongs to resource group X" or "which work events (CPU, lock waits, network) dominate for group Y".

This is complementary to CRDB-64731 / #171607, which adds resource group to SQL Stats: SQL Stats gives per-fingerprint aggregates, ASH gives the time-sampled view of what sessions in a group were actually blocked on.

**Describe the solution you'd like**

Add a resource group dimension to ASH's enrichment data, mirroring how `user` is handled today:

- Add the field to [`enrichment.Attributes`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/obs/ash/enrichment/attributes.go#L31) and [`ASHSample`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/obs/ash/types.go#L76).
- Populate it at [`conn_executor_exec.go:3667`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/sql/conn_executor_exec.go#L3667), where `enrichment.PutExecution` already reads `planner.SessionData()` — `ResourceGroupID` is in scope, so no new plumbing.
- Wire through resolution: [`applyAttributes`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/obs/ash/enrichment_queue.go#L177), [`EnrichmentAttributes`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/server/serverpb/status.proto#L1319) (next free tag 9) and [`ASHSample`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/server/serverpb/status.proto#L1221) (next free tag 15) protos, and the remote handler at [`status.go:3587`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/server/status.go#L3587).
- Surface it as a column on [`crdb_internal.node_active_session_history`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/sql/crdb_internal.go#L10057) / `cluster_active_session_history`, on [`system.active_session_history`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/sql/catalog/systemschema/system.go#L1533), in the [flusher's `insertColumns`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/obs/ash/ashflush/flusher.go#L378), and in `pkg/cli/zip_table_registry.go`.

Design notes:
- **Store the id, not the name.** `Attributes` is deliberately memory-tight (default 65K-entry cache; the struct comment explains why query text and database are excluded). A `uint64` id is cheaper than a name string, matches admission control, and can be resolved to a name at display time.
- **No PK change.** Unlike `statement_statistics`, ASH's PK is `(sample_time, node_id, goroutine_id)`. Resource group is a plain value column here — no hash-shard expression, no PK migration.
- Need a defined meaning for `0` (no group set) — likely `NULL` in the surfaced column.
- **Migration cost depends on timing.** `system.active_session_history` is added by `V26_3_AddActiveSessionHistoryTable` (`26.2-20`), unreleased on master as of filing. If this lands before 26.3 is finalized, the column can be folded into the initial schema (new column id, family list, bootstrap hash + golden files). Otherwise it becomes a real system-table migration — see the `system-table-change` checklist.
- **Sequencing.** [`resourcegroupcache`](https://github.com/cockroachdb/cockroach/blob/7bb503b8691bbb5c4d2e6eabe10411f52e743120/pkg/sql/resourcegroupcache/cache.go#L50) currently resolves only the two built-in groups; user-defined groups can be created but not yet `SET`. Until the rangefeed-backed cache lands, nearly all rows would be `0` or a built-in id. Same caveat as CRDB-64731.

**Describe alternatives you've considered**

- *Store the resource group name string instead of the id* — simpler at display time and no cache dependency, but costs per-entry memory in an explicitly budgeted cache.
- *JOIN at query time from somewhere else* — there is no other per-execution record of the resource group, so there's nothing to join against.
- *Rely on SQL Stats alone (CRDB-64731)* — that gives aggregated per-fingerprint cost, not the sampled "what was this group waiting on, when" view that ASH provides.

**Additional context**

Filed via agent. Related: CRDB-64731 / #171607 (resource groups in SQL Stats).

Epic CRDB-65731

Jira issue: CRDB-66131

Contributor guide

Open the contributing guide

Research direction

Start with pkg/obs/ash/enrichment/attributes.go and types.go, then trace the existing user field through conn_executor_exec.go, enrichment_queue.go, status.proto, and status.go. Follow the ASH surfaces in crdb_internal.go, systemschema/system.go, ashflush/flusher.go, and pkg/cli/zip_table_registry.go. Done means the resource-group ID is propagated and exposed consistently, with the required schema or migration updates and NULL semantics for no group.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, sql
Domain
databases, observability-sre
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.