Skip to main content

Dashboard operations

Check dashboard data freshness and Health Score availability, compare project periods, and configure notifications for project changes.

User Guides

Use this guide when checking project data before a release or investigating a discrepancy on the dashboard. Inspect the analysis basis, compare history, and retain the view parameters so a colleague can repeat the check. A separate step configures notifications about project changes. Host and service telemetry belongs in Monitoring.

Install the CLI and dependencies using the command-line guide. Run commands in PowerShell from the CodeGraph source repository root with its Python environment installed. Use the same runtime configuration and project scope as the API instance. Replace PROJECT with a registered project name and USER_ID with the intended owner identifier in the local store.

1. Establish the project basis

python -m src.cli dashboard health 'PROJECT' --format json
python -m src.cli dashboard basis 'PROJECT' --format json

The response links project identity and evidence revision to the analysis basis, score availability and data freshness. States stale, missing, failed and unknown help you choose the next action: refresh data, locate the missing source or investigate the failure. Save the state and explanation with the check result.

In the health response, read health_score_available first. If it is true, inspect the contributions in score_breakdown; if it is false, find the missing source in health_score_unavailable_reason. See the score methodology for formulas, weights, and a worked calculation.

When the response supplies a recommended refresh 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.

Example: read the analysis basis

A project with live data and no linked audit snapshot can return this combination:

Example: read the analysis basis
Field Example value Meaning
basis_kind live The view uses current data
coherence_status live_only A linked audit snapshot is still needed for a coherent basis
requested_mode best_effort The command shows available data and its state
verdict warn Read the reason and recommended action
cpg_fresh false Inspect freshness_reason
freshness_reason missing_cpg_commit The basis has no graph commit

Here, recommended_action asks for a fresh audit report and linked snapshots. Retain this response, then check the basis again after the audit finishes. Values depend on the project data.

2. Configure project notifications

Create a subscription to project changes. The command saves a state snapshot and dispatches detected events to active project subscriptions. The new subscription in this example uses the local inbox: its notifications are available to the owner inside CodeGraph.

python -m src.cli dashboard notifications bootstrap 'PROJECT' --user-id 'USER_ID' --format json

Select a channel with --channel, a delivery mode with --delivery-mode, event types with --events, and the minimum severity with --minimum-severity. Messages contain a brief change summary by default. --include-sensitive-details adds sensitive details for channels permitted to receive them.

By default, the command selects the local inbox channel and immediate delivery. This channel works without configuring an external recipient. To send through email, Slack, Telegram, or a webhook, configure that channel and select it with --channel.

Inspect subscription_id, snapshot_id, configured_channels, dispatched_count, and pending in the response. When the project state is unchanged and there are no new events, the command saves a snapshot and returns dispatched_count: 0, an empty emitted_event_types, and an explanation in note. --no-create-subscription suppresses subscription creation while saving the snapshot and dispatching detected events to existing subscriptions. To verify delivery, find a successful delivery record in the selected channel.

A channel test checks message delivery. Delivery alone is insufficient to verify live notifications: change the project state, run bootstrap, and match the emitted event type and successful delivery to that change.

3. Inspect saved views

python -m src.cli dashboard saved-views list --user-id 'USER_ID' --format json

Before a recurring comparison or export, record the saved-view identifier, owner, scope, filters and period. The service stores views within a user scope; use the intended owner’s view to repeat the check.

The local CLI selects the owner through --user-id, which defaults to cli-user. REST obtains the owner from the authenticated user and checks access through the API.

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. CLI defaults to baseline 30d and comparison 7d; set --baseline-period and --comparison-period explicitly for other intervals. If history is insufficient, read the response explanation before drawing a trend conclusion. Retain those selectors with the result so the comparison can be reproduced.

With insufficient history, note contains Not enough snapshot history to compare the selected periods. and diff.metrics is empty. Such a response can have trend_direction: stable, the default for an empty comparison. Assess a trend using populated metrics, snapshot identifiers and timestamps.

5. Collect diagnostic details

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 diagnostic report.

Report a documentation issue