Contributor onboarding: Grafana dashboard and Claude Code tracing plugin

[caohy1988]

Goal

Give a new contributor everything needed to independently develop, test,
document, and provide completion evidence for:

1. The BQAA Grafana dashboard.
2. The BQAA Claude Code tracing plugin.

Use only synthetic data and an approved non-production GCP project. Production
data, production credentials, repository administration, and release secrets
are out of scope for the contributor.

Current state (2026-09-04)

Grafana

• Core implementation landed in PR #373.
• Local one-command setup landed in PR #422.
• Query and public-demo hardening landed in PR #433.
• Issue #339 remains open.
• The remaining assignment should focus on clean-environment validation,
  documentation corrections, defects found during testing, evidence, and
  tracker closure—not rebuilding the dashboard.

Claude Code plugin

• The hook implementation, plugin build, and in-repository marketplace exist.
• plugins/claude_code/
  is the plugin wrapper and documentation.
• The canonical Python implementation is under
  producers/src/bigquery_agent_analytics_tracing/.
  Do not implement Python behavior in a generated plugin copy.
• The producer source version is 0.2.0, while the checked-in marketplace
  distribution is still 0.1.0.
• PyPI and release prerequisites remain tracked by
  #349
  and the canonical operator checklist in
  #353.

Maintainer: complete before assigning work

• Record contributor GitHub handle: @<handle>.
• Assign a technical owner: @<owner>.
• Assign a reviewer who can approve and merge PRs: @<reviewer>.
• Confirm whether the contributor uses a fork or may push feature branches.
• Confirm the Google CLA is satisfied.
• Provide an approved, billing-enabled, non-production GCP project.
• Create or identify a disposable BigQuery dataset.
• Confirm who owns Grafana Cloud access and public-sharing permission.
• Confirm whether Claude Code marketplace testing is included.
• Confirm whether the assignment stops at release readiness or includes
  operating the 0.2.0 release.
• Keep Google-internal links, email addresses, credentials, and access
  tickets out of this public issue.

Shared workstation requirements

The contributor needs:

• Git and GitHub CLI.
• Python 3.12 preferred; the packages support Python 3.10–3.14.
• An isolated Python virtual environment.
• Google Cloud CLI, including gcloud and bq.
• Access to the approved GCP sandbox project.
• No production access.

Start with:

gh auth status
git clone https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK.git
cd BigQuery-Agent-Analytics-SDK

python3.12 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev]"

Read before contributing:

• Repository README
• Contribution guide
• Code of Conduct
• Security policy

---

Workstream A — Grafana dashboard

A1. Learn the component

Read these in order:

1. Grafana README
2. Query conventions and file-to-panel map
3. Public-demo query rules
4. Interactive dashboard JSON
5. Public-demo dashboard JSON
6. Datasource provisioning example

Important concepts:

• queries/*.sql is the source of truth.
• Grafana JSON embeds a copy of each SQL query.
• Change the SQL file first, then update the matching dashboard panel.
• Interactive identifiers and prices must remain Constant variables.
• Public-demo queries must have no Grafana variables or macros and must retain
  the half-open 72-hour limit.
• Never add Trace Detail or real production identifiers to the public demo.

A2. Obtain test resources

Required:

• An approved test GCP project.
• A disposable BigQuery dataset.
• BigQuery API and Cloud Resource Manager API enabled.
• Application Default Credentials for local testing.
• Grafana Cloud Free with dashboard-editor/public-sharing permission, or local
  Grafana for initial work.
• Google BigQuery datasource plugin.

For local ADC:

gcloud auth application-default login
gcloud config set project TEST_PROJECT

For a Grafana service account:

• roles/bigquery.jobUser on the query project.
• roles/bigquery.dataViewer on the test dataset only.
• Do not grant Owner or Editor.
• Never commit a JSON key.
• Use a separate demo-only identity for a publicly shared dashboard.

References:

• Grafana BigQuery datasource
• Grafana public dashboards
• Google ADC
• BigQuery IAM

A3. Create safe test data

bqaa seed-events \
  --scenario retail-returns \
  --project-id TEST_PROJECT \
  --dataset-id TEST_DATASET \
  --events-table agent_events \
  --sessions 100

bq-agent-sdk views create-all \
  --project-id TEST_PROJECT \
  --dataset-id TEST_DATASET \
  --table-id agent_events

Verify that the table is non-empty and recent:

bq query --use_legacy_sql=false \
  'SELECT COUNT(*) AS events, MAX(timestamp) AS latest
   FROM `TEST_PROJECT.TEST_DATASET.agent_events`'

A4. Run and inspect the dashboard locally

python3 grafana/run_local.py \
  --project TEST_PROJECT \
  --dataset TEST_DATASET

Verify:

• All dashboard rows and panels load without query errors.
• Agent, User ID, Event Type, and Session filters behave as documented.
• Clicking a recent session drives Trace Detail.
• Empty filter intersections show an honest no-data state.
• Token, latency, error, and estimated-cost panels have sensible values.
• The datasource retains the configured MaxBytesBilled limit.
• No service-account credential appears in Git output.

Stop the local instance afterward:

python3 grafana/run_local.py --stop

A5. Make and validate changes

When changing a panel:

1. Edit its canonical .sql file.
2. Paste the identical query into the matching dashboard JSON panel.
3. If adding a panel, update the appropriate mapping in
   scripts/check_grafana_queries_sync.py.
4. Update the documented file-to-panel map.
5. If it belongs in the public demo, create the separate bounded query under
   queries/public-demo/.

Run:

python3 scripts/check_grafana_queries_sync.py
python3 -m pytest -q tests/test_grafana_local_runner.py

Both must pass before opening a PR.

A6. Validate public sharing

Use only a dedicated synthetic dataset. Verify in an incognito/logged-out
browser:

• The dashboard loads without authentication.
• Every panel is inspected for query errors.
• The time picker is hidden and locked.
• Queries cannot exceed the fixed 72-hour window.
• Trace Detail is absent.
• No real user IDs, prompts, responses, credentials, project names, or
  sensitive error messages appear.
• A per-query byte cap and a BigQuery project quota are configured.
• The public link can be paused or revoked.

Do not post a sensitive public dashboard URL in this issue.

A7. Grafana completion evidence

Post:

• Commit or PR link.
• Automated test output.
• Grafana and BigQuery plugin versions.
• Confirmation that synthetic data was used.
• Confirmation that every panel passed.
• Confirmation that incognito public-share validation passed.
• Any documentation corrections.
• Cleanup and link-revocation confirmation.

Done when the maintainer reconciles this evidence with #339 and closes or
narrows that tracker.

---

Workstream B — Claude Code tracing plugin

B1. Learn which files are source and which are generated

Read:

1. Plugin README
2. Marketplace and IAM checklist
3. Plugin manifest
4. /bqaa-setup command
5. Producer package README
6. Plugin build script
7. Release runbook
8. Claude marketplace catalog

Rules:

• Python behavior belongs in producers/src/bigquery_agent_analytics_tracing/.
• plugins/claude_code/vendor/ is generated and gitignored. Never edit it
  manually.
• plugins/claude_code_dist/ is a released artifact, not canonical source.
• 0.0.0+local in the source manifest is intentional; the build stamps the
  release version.
• Build in a disposable checkout or worktree because the build stamps the local
  manifest and generates vendor files.

B2. Install development dependencies

Required:

• Current Claude Code CLI and an approved Claude entitlement.
• Python 3.12 development environment.
• GCP sandbox project and dataset for live smoke testing.
• google-cloud-bigquery.
• google-cloud-bigquery-storage and pyarrow for the preferred Storage Write
  path.

cd producers
python3.12 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e ".[dev,receiver,storage-write]"
claude --version

References:

• Claude Code plugins
• Claude Code marketplace documentation

B3. Run automated checks

cd producers

isort --check-only src/ tests/ scripts/
pyink --check src/ tests/ scripts/
python3 -m pytest -q

For focused plugin work, at minimum run:

python3 -m pytest -q \
  tests/test_claude_code.py \
  tests/test_setup_check.py \
  tests/test_build_claude_plugin.py \
  tests/test_drain.py \
  tests/test_logger_row_shape.py

B4. Build and validate the plugin artifact

Follow the same sequence as CI:

cd producers
python3 -m pip install --require-hashes -r build-requirements.lock
python3 -m build --no-isolation
python3 -m pip install --no-deps \
  dist/bigquery_agent_analytics_tracing-*.whl
python3 scripts/build_claude_plugin.py

cd ..
claude plugin validate plugins/claude_code --strict
claude plugin validate . --strict

Inspect the generated tarball and confirm it contains:

• .claude-plugin/plugin.json with the release version.
• All nine hook scripts plus common.sh.
• commands/bqaa-setup.md.
• scripts/run_setup_check.sh.
• Vendored package source.
• Matching .dist-info/METADATA.
• No __pycache__, .pyc, credentials, or local configuration.

B5. Test safely before connecting BigQuery

Start with dry-run mode:

export BQAA_PROJECT_ID=TEST_PROJECT
export BQAA_DATASET=TEST_DATASET
export BQAA_PYTHON="$(command -v python3)"
export BQAA_AGENT_NAME=vendor-plugin-smoke
export BQAA_DRY_RUN=true
export BQAA_TRACE_ENABLED=true

claude --plugin-dir plugins/claude_code

Inside Claude Code, run /bqaa-setup, then submit a harmless test prompt and
verify the dry-run log and spool behavior. The plugin must never break the
Claude Code session when tracing fails.

B6. Run the BigQuery smoke test

The test identity requires:

• roles/bigquery.dataEditor on the destination dataset.
• roles/bigquery.user on the project.
• roles/bigquery.metadataViewer on the dataset when auto-creating the table.

Use a pre-created dataset where possible. Disable dry-run, launch a fresh Claude
Code session, run /bqaa-setup, and submit one harmless prompt.

Verify rows:

SELECT
  event_type,
  JSON_VALUE(attributes, '$.writer.version') AS writer_version,
  JSON_VALUE(attributes, '$.writer.label') AS writer_label,
  agent,
  timestamp
FROM `TEST_PROJECT.TEST_DATASET.agent_events`
WHERE agent = 'vendor-plugin-smoke'
ORDER BY timestamp DESC
LIMIT 20;

Expected:

• Hook rows arrive.
• writer_version matches the built artifact and is not 0.0.0+local.
• Only one BQAA plugin installation is active; duplicate installations cause
  duplicate telemetry.
• Setting BQAA_TRACE_ENABLED=false and restarting Claude Code produces no new
  rows and no agent error.

B7. Validate the marketplace path

Before testing, run /plugin list and remove or disable older BQAA plugin
installations.

Validate the current Git-based install path:

/plugin marketplace add GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK --sparse .claude-plugin plugins/claude_code_dist
/plugin install bigquery-agent-analytics-tracing@bqaa-tracing
/bqaa-setup

Add the marketplace using owner/repository, not a direct URL to
marketplace.json, because its plugin source is a relative repository path.

For a 0.2.0 release, repeat this smoke only after the checked-in distribution
and catalog have been refreshed from the final built artifact.

B8. Claude Code completion evidence

Post:

• Commit or PR link.
• Claude Code and Python versions.
• Full and focused test results.
• claude plugin validate --strict output.
• Tarball inventory and version.
• /bqaa-setup READY result.
• Redacted BigQuery query result proving the writer version.
• Kill-switch test result.
• Confirmation that duplicate plugins were removed.
• Confirmation that only synthetic or non-sensitive prompts were used.
• Remaining release blockers requiring a maintainer.

Google-maintainer-only actions

Do not assign these actions to the contributor unless they explicitly have the
required authority:

• Repository settings, Actions environments, variables, and secrets.
• Creating or configuring tracing-testpypi, tracing-pypi, and
  release-promote.
• PyPI/TestPyPI Trusted Publisher configuration and adding second Owners.
• Organization-owned GitHub App creation and installation.
• Repository immutable-release setting changes.
• Creating or pushing the protected tracing-v0.2.0 tag.
• Approving release promotion and PyPI deployment.
• Artifact Registry, WIF, or public receiver-image administration when Release bigquery-agent-analytics-tracing 0.2.0: publish the Claude/Codex OTel admin stack to PyPI #349 is
  included.
• Final Anthropic official-marketplace submission.

The authoritative operator checklist is
#353.
The contributor may prepare artifacts, smoke evidence, and PRs, but a designated
Google maintainer must perform and record privileged steps.

Overall definition of done

• Contributor can reproduce both components from a clean checkout.
• Automated tests and strict manifest validation pass.
• Grafana works locally with synthetic data.
• Grafana public-demo safety is verified in an incognito session.
• Claude plugin produces correctly versioned test rows.
• Claude plugin kill switch works.
• No credentials or production data are committed or exposed.
• Documentation is accurate for a first-time user.
• All contributor-executable evidence is attached.
• Maintainer-only blockers are explicitly handed to an owner.
• Parent trackers are reconciled and closed or narrowed.

[caohy1988]

Hard resource requirements for the contributor

This is the concrete provisioning checklist. It covers accounts, machines,
software, cloud resources, APIs, IAM, and credentials. The longer task and
validation instructions remain in the issue body.

Use an approved non-production GCP project and synthetic test data. The
contributor does not need access to customer or production telemetry.

Shared resources required for both workstreams

Contributor workstation

• macOS or Linux workstation. Windows is acceptable only through a tested
  Linux environment such as WSL; the repository scripts and plugin hooks
  use Bash.
• Network access to GitHub, Google Cloud APIs, Python package indexes,
  Grafana download/plugin endpoints, and Anthropic/Claude endpoints.
• At least 5 GB of free workspace/cache space for the checkout, Python
  environments, Grafana download, plugin builds, and test artifacts.

Source-control access

• Git installed.
• GitHub CLI (gh) installed and authenticated.
• Read access to
  GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK (the repository is
  public).
• A personal fork, or permission to push a feature branch to the repository.
• Permission to open pull requests and comment on issues.
• Google CLA completed for the contributor or their employer.
• A named Google maintainer who can review and merge the PR. The contributor
  does not require repository-admin access.

Common local tools

• Python 3.12 recommended; supported range is 3.10–3.14.
• python3, pip, and venv available.
• Google Cloud CLI installed, including both gcloud and bq.
• An isolated Python virtual environment for this repository.
• An approved method for storing credentials; credentials must not be
  committed to the repository.

---

Project A — Grafana dashboard resources

A. Google Cloud resources

• One billing-enabled, non-production GCP project.
• One disposable BigQuery dataset in a known location, for example US
  or EU.
• BigQuery API enabled: bigquery.googleapis.com.
• Cloud Resource Manager API enabled:
  cloudresourcemanager.googleapis.com.
• The BQAA SDK installed so the bqaa and bq-agent-sdk commands are
  available.
• A synthetic agent_events table created with bqaa seed-events.
• BQAA typed views created with bq-agent-sdk views create-all.
• The table must be partitioned on timestamp so Grafana time filters prune
  scans.

Recommended test allocation:

• Dataset: bqaa_grafana_vendor_test or another disposable approved name.
• Table: agent_events.
• Data: approximately 100 synthetic retail-returns sessions.
• Retention: delete the test dataset after acceptance unless the maintainer
  requests that it remain for regression testing.

B. Local authentication for the one-command runner

• Contributor identity allowed to use the test GCP project.
• Application Default Credentials established with
  gcloud auth application-default login.
• Permission to query the test dataset and create the required typed views.

C. Grafana runtime

At least one of the following is required:

1. Local validation path

   • macOS or Linux supported by grafana/run_local.py.
   • Permission to download and run the pinned Grafana binary.
   • An unused localhost port, normally 3000.
   • The runner binds only to 127.0.0.1; no public ingress is needed.

2. Hosted validation/public-share path

   • A Grafana Cloud Free account or approved shared Grafana instance.
   • Dashboard Editor permission.
   • Permission to install/configure the Google BigQuery datasource plugin.
   • Permission to create, pause, and revoke a public dashboard link.

The current BigQuery plugin requires a compatible Grafana release. The
repository runner pins a tested Grafana and plugin combination; use the runner
unless a specific hosted version must be tested.

D. BigQuery identity used by Grafana

• A dedicated test service account or another approved Grafana
  authentication identity.
• roles/bigquery.jobUser on the query project.
• roles/bigquery.dataViewer on the test dataset only.
• For Grafana Cloud JWT authentication, an approved way to upload the
  service-account JSON key.
• A key owner and deletion/rotation date. Delete the local downloaded key
  after Grafana has been configured.

Do not grant Project Owner, Editor, or project-wide BigQuery Data Viewer.

E. Additional public-demo resources

• A separate demo-only BigQuery dataset containing only synthetic data.
• A separate demo-only service account scoped to that dataset.
• Grafana datasource MaxBytesBilled configured; the repository example
  uses a 100 MB per-query cap for the small demo dataset.
• A BigQuery custom daily query quota or equivalent project cost guardrail.
• A modern browser with an incognito/private window for unauthenticated
  verification.
• Authority to pause or revoke the public link immediately after testing.

F. Optional resources

• Docker, only if the contributor chooses self-managed Grafana rather than
  grafana/run_local.py or Grafana Cloud.
• A secret manager or mounted-secret mechanism for long-lived self-managed
  Grafana. A committed datasource key is never acceptable.

Grafana resource-ready gate

The Grafana workstream is ready to start when the contributor can successfully
run all three of these checks:

gcloud auth application-default print-access-token >/dev/null
bq query --use_legacy_sql=false 'SELECT 1'
python3 -c 'import bigquery_agent_analytics'

The public-demo task is ready only after the hosted Grafana account, isolated
demo dataset, demo-only service account, query cap, and link-revocation owner
are all available.

---

Project B — Claude Code tracing plugin resources

A. Claude/Anthropic resources

• Current Claude Code CLI installed and available as claude.
• Approved Claude/Anthropic account or organization entitlement that can
  start Claude Code sessions.
• Permission to load a local plugin using claude --plugin-dir.
• Permission to add the repository marketplace and install/uninstall its
  plugin for smoke testing.
• A clean Claude Code test configuration, or permission to remove/disable
  older BQAA plugin installations. Multiple active BQAA plugins duplicate
  telemetry.

B. Python runtime used by the hooks

• A stable Python executable selected through BQAA_PYTHON; Python 3.12 is
  recommended.
• google-cloud-bigquery installed in that exact interpreter.
• For the preferred Storage Write path,
  google-cloud-bigquery-storage and pyarrow installed in the same
  interpreter.
• Permission to write temporary spool, state, and log files. Defaults are
  below /tmp/bqaa-agent-tracing and /tmp/bqaa-agent-tracing.log.
• Enough local disk for short-lived spool files if BigQuery is temporarily
  unreachable.

The plugin vendors bigquery-agent-analytics-tracing; that package does not
need to be separately installed into BQAA_PYTHON for plugin runtime.

C. Google Cloud resources for the live plugin smoke

• One billing-enabled, non-production GCP project.
• BigQuery API enabled: bigquery.googleapis.com.
• One pre-created disposable BigQuery dataset.
• One agent_events test table, or permission for the plugin to create it.
• ADC or a dedicated test service account available to BQAA_PYTHON.

IAM for the plugin writer identity:

• roles/bigquery.dataEditor on the destination dataset.
• roles/bigquery.user on the project.
• roles/bigquery.metadataViewer on the dataset when
  BQAA_AUTO_CREATE_TABLE=true.

The contributor does not need production dataset access. Prefer a pre-created
dataset because BQAA_AUTO_CREATE_DATASET is disabled by default.

D. Required runtime configuration

The maintainer must provide non-secret values for:

• BQAA_PROJECT_ID — test GCP project ID.
• BQAA_DATASET — disposable test dataset.
• BQAA_PYTHON — exact Python interpreter used by hooks.
• BQAA_AGENT_NAME — unique smoke-test producer name, such as
  vendor-plugin-smoke.

Useful test controls:

• BQAA_DRY_RUN=true for the first test without BigQuery writes.
• BQAA_TRACE_ENABLED=false for the kill-switch test.
• BQAA_TABLE if the table is not agent_events.
• BQAA_LOCATION when the BigQuery location must be explicit.
• BQAA_AUTO_CREATE_TABLE=true only when the identity has the required schema
  inspection and table-creation permissions.

No API key belongs in these environment variables. Google authentication uses
ADC or an approved service-account mechanism.

E. Development and build tools

• Producer development dependencies from producers/pyproject.toml.
• pytest, isort, and pyink for CI-equivalent validation.
• Hash-locked build dependencies from
  producers/build-requirements.lock.
• Network access to PyPI for dependency installation.
• A disposable checkout or Git worktree for artifact builds because the
  build generates vendor/ and stamps the local plugin manifest.
• Enough disk space for the wheel, sdist, vendored plugin, and tarball.

F. Marketplace smoke resources

• GitHub network access from Claude Code.
• Git credentials usable by Claude Code/CLI.
• Permission to add
  GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK as a marketplace.
• Permission to install, uninstall, enable, and disable the test plugin.
• A fresh Claude Code session after configuration changes.
• BigQuery query access to verify the emitted writer version and label.

G. Additional resources only if the contributor is asked to operate the

0.2.0 release

These are not needed for ordinary plugin code, local validation, or a PR. They
require designated Google maintainers or organization owners:

• Repository-admin access for GitHub Actions environments and policies.
• tracing-testpypi, tracing-pypi, and release-promote environments.
• TestPyPI and PyPI accounts with 2FA and recovery methods.
• Trusted Publisher registrations for release-tracing.yml.
• A second Google-controlled Owner for each package after first publish.
• Organization-owned GitHub App with repository Administration read
  access, installed only on this repository.
• Repository variable and secret required by the release-policy check.
• Authority to enable/disable immutable releases and push the protected
  tracing-v0.2.0 tag.
• Approval authority for image promotion and production PyPI publication.
• Publisher GCP project, Artifact Registry staging/public repositories,
  Workload Identity Federation, budget alerts, and egress monitoring when
  the OTel receiver image from Release bigquery-agent-analytics-tracing 0.2.0: publish the Claude/Codex OTel admin stack to PyPI #349 is in scope.
• An owner for the final Anthropic official-marketplace submission.

The exact privileged release checklist is maintained in
#353.
Do not give repository secrets or broad organization permissions to the
contributor merely to unblock local plugin work.

Claude Code resource-ready gate

The normal development and smoke-test workstream is ready when these succeed:

claude --version
"$BQAA_PYTHON" -c 'import google.cloud.bigquery'
gcloud auth application-default print-access-token >/dev/null
bq query --use_legacy_sql=false 'SELECT 1'

Inside a locally loaded plugin session, /bqaa-setup must report READY
before the live BigQuery smoke begins. Release operation is not ready until
every unchecked maintainer prerequisite in #353 has an explicit owner and is
completed.