Skip to main content

Dashboard operations

Operational checks and recovery actions for dashboard data, history, saved views, and notifications. See the examples and checks before applying it.

User Guides

This runbook covers dashboard-specific operations: proving that a project surface is current, bootstrapping notifications, preserving reproducible saved views, and comparing history. Host and service telemetry belongs in Monitoring.

Run commands from the CodeGraph repository with the same runtime configuration and project scope as the API instance.

1. Establish the project basis

python -m src.cli dashboard health <project> --format json
python -m src.cli dashboard basis <project> --format json

Check the project identity, evidence revision, analysis basis, score availability, and freshness together. A successful command with a stale, missing, failed, or unknown surface is a diagnostic result, not readiness evidence.

When a surface supplies a recommended command, first verify that refresh_supported is true and action_availability is available. If the state is updating, observe the current job instead of starting duplicate work. For failed, retain the job and reason evidence before retrying.

2. Bootstrap a project notification

The project argument is required:

python -m src.cli dashboard notifications bootstrap <project> --format json

Set --channel, --delivery-mode, --events, and --minimum-severity only when they match the approved receiver policy. Sensitive details are excluded unless --include-sensitive-details is both necessary and permitted.

The bootstrap response proves configuration. Full operational evidence also needs a delivery-success event from the live notification pipeline; a test delivery alone is insufficient.

3. Preserve and inspect saved views

python -m src.cli dashboard saved-views list --format json

Before a recurring comparison or export, record the saved-view identifier, owner, scope, filters, and period. Saved views are user-scoped; do not assume that another authenticated user can read or reuse them.

The current REST reads are:

  • GET /api/v1/traceability/saved-views;
  • GET /api/v1/traceability/subscriptions.

Both require API authentication and the applicable project/user scope.

4. Compare history

For one project:

python -m src.cli dashboard compare-periods <project> --format json

For portfolio automation, use GET /api/v1/traceability/portfolio/compare-periods with the same filters, baseline period, and comparison period as the saved view. The endpoint is a read operation. Retain those selectors with the result so the comparison can be reproduced.

5. Incident handoff

Capture:

  • project and group scope;
  • current commit or deployed image identity;
  • route or command and sanitized parameters;
  • freshness state and reason;
  • active job identifier and stage, when present;
  • saved-view and period selectors;
  • notification delivery event, when the incident concerns notifications.

Do not include access tokens, receiver secrets, raw private findings, or storage paths in the handoff.

Sources of truth

  • src/cli/dashboard_commands.py — dashboard command parser and dispatch.
  • src/api/routers/dashboard_core/dashboard_v2_history.py — project and portfolio period comparison.
  • src/api/routers/dashboard_domains/dashboard_v2_notifications.py — saved views and subscriptions.
  • src/api/services/dashboard/surface_state/surface_freshness.py — recovery state and supported-action metadata.

For route navigation, use the Dashboard user guide.

Report a documentation issue