diagnose-entity-graph

Diagnose Entity Graph

Systematic diagnosis of Entity Graph problems using gcx commands. Follow the steps in order — each step narrows the cause. Be direct and report findings concisely.

Start here: read the Orientation block

gcx kg diagnose prints an Orientation block above its check table. Read it first. It tells you which (if any) of the five common Entity Graph scenarios the run matches:

• "I see no entities at all"
• "Some expected entities are missing"
• "I see entities with no edges"
• "I see disconnected clusters of entities"
• "I can't filter to the entities I want"

When the Orientation block names a matched scenario, follow its Next: commands. The per-step playbook below is the fallback for runs where no scenario matched or the matched scenario's hints didn't resolve the issue.

Reading Diagnose Output

Treat gcx kg diagnose's verdicts as authoritative for the queries it ran. Two non-obvious classifications:

• WARN — metric exists … but no series match the requested env/namespace scope means the metric is flowing on the stack but doesn't carry the scoped label value. This is a label-mapping issue (asserts_env vs. deployment_environment, etc.), not a missing-data issue. Investigate the label pipeline (Step 6) before suggesting the user enable new telemetry.
• FAIL — no data (without the WARN above) means the metric was not found, even unscoped — the integration / recording rule is genuinely absent.

For ad-hoc PromQL outside kg diagnose, apply the same discipline: re-run the query without the env / namespace filter before concluding the data is missing.

If a user reports an entity by name, see Step 7's entity-existence workflow before assuming it exists on this stack.

Prerequisites

gcx must be installed and configured with a valid context. gcx kg diagnose bundles most of the per-step checks below; the individual commands produce equivalent results when you need to drill into one check.

gcx config view
gcx kg status