Skip to content

feat: add experimental CockroachDB diagnostics - #27

Closed
srosenberg wants to merge 1 commit into
pgrundev:mainfrom
srosenberg:cockroachdb
Closed

feat: add experimental CockroachDB diagnostics#27
srosenberg wants to merge 1 commit into
pgrundev:mainfrom
srosenberg:cockroachdb

Conversation

@srosenberg

Copy link
Copy Markdown

What and why

Add experimental, native CockroachDB diagnostics to pgbot while preserving the existing PostgreSQL behavior and graceful-degradation model.

The integration detects CockroachDB over pgwire and adds engine-aware collection for:

  • cluster and workload health, including separate health scores
  • live activity, persisted statement statistics, execution insights, retries, and contention attribution
  • indexes, tables, optimizer statistics, background jobs, range distribution, and hotspots
  • store capacity, MVCC footprint, replication recovery, Raft queues, and disk/write-stall signals
  • CockroachDB-specific health, distribution, storage, jobs, activity, and contention screens

Comprehensive cluster health combines read-only SQL with the CockroachDB Admin API and Prometheus load endpoint. Collectors remain bounded and explicitly mark unavailable or partial data.

The optional AI layer now receives a compact, CockroachDB-aware diagnostic summary without raw SQL, localities, users, application names, or job descriptions. OpenAI requests also handle models such as gpt-5.6-sol that reject non-default temperature values.

Public contract and safety

  • The Context JSON contract advances additively from 1.2.0 to 1.3.0; the generated schema is included.
  • New SQL is read-only and contains no EXPLAIN ANALYZE.
  • Contention keys and query text are normalized/redacted before entering the Context.
  • Every new finding has a catalog entry and a generated documentation page.
  • PostgreSQL collection and rendering continue to use the existing paths.

Validation

  • scripts/gate.sh passes: clean-HEAD build, vet, tests, and builds for four architectures
  • go test -race ./... passes
  • gofmt -l . is clean
  • JSON schema and findings index regenerated with go run ./tools/schemagen
  • Credential scan found no test-cluster URL, certificate path, or secret
  • Manually smoke-tested against local and remote CockroachDB clusters

Checklist

  • scripts/gate.sh passes (builds HEAD, not just the working tree)
  • New SQL is read-only; no EXPLAIN ANALYZE; findings stay deterministic (computed in Go)
  • No PII enters a model.Context / --json / the store
  • --json change is additive, model.SchemaVersion is bumped, and the schema is regenerated
  • Every new finding has a docs/findings/<id>.md page and catalog entry

@srosenberg srosenberg closed this Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant