diagnose-entity-graph

Diagnose missing entities, edges, and label-mapping issues in the Asserts Entity Graph using gcx commands.

1|Updated May 25, 2020
One-click install
npx skills add https://github.com/titaneric/dotfiles --skill diagnose-entity-graph-titaneric
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnose-entity-graph
Source: https://github.com/titaneric/dotfiles/tree/main/dot_agents/skills/diagnose-entity-graph
Command: npx skills add https://github.com/titaneric/dotfiles --skill diagnose-entity-graph-titaneric

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When the Entity Graph shows missing services, no edges, disconnected clusters, or broken environment filtering, it is hard to tell whether the cause is absent telemetry, missing recording rules, or a label-mapping gap. This Skill provides a systematic, step-by-step diagnostic playbook using gcx commands to isolate the root cause. ## Core Features & Use Cases - Guided diagnosis workflow: Walks through stack health, entity counts, source metrics in Mimir, recording rules, edge sources, and label pipelines in a fixed order that narrows the cause. - Label-mapping gap detection: Identifies the common case where metrics carry deployment_environment but not asserts_env, causing recording rules to silently drop data. - Per-service investigation: Uses Cypher queries and PromQL checks to trace why a specific service is missing or has no edges, including service-name collision and env-scope split detection. - Use Case: A user reports "services missing from entity graph" for a specific environment. The Skill checks traces_target_info, asserts:mixin_workload_job, and the asserts_env label mapping, then pinpoints a Mimir relabeling misconfiguration and recommends the Connect Environment fix. ## Quick Start Ask the assistant to diagnose why the Entity Graph is empty or missing services for a given environment, and it will run the gcx kg diagnose workflow and report findings.

Frequently Asked Questions about diagnose-entity-graph

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I diagnose missing services in the Entity Graph?

Run gcx kg diagnose and read the Orientation block, which matches your run to one of five common scenarios. Then verify entity counts with gcx kg health, check traces_target_info in Mimir, and confirm the asserts:mixin_workload_job recording rule produces data for your environment.

Why does the Entity Graph show entities but no edges?

Edges come from asserts:relation:calls, which requires an edge source metric carrying the asserts_env label. If source metrics like istio_requests_total or http_server_requests_seconds_count exist but lack asserts_env, Mimir relabeling silently drops them and no edges are produced.

What is the difference between deployment_environment and asserts_env labels?

Raw Tempo metrics use deployment_environment, while Asserts recording rules require asserts_env. The Mimir relabeling pipeline must map one to the other; configure this in the Asserts app under Configuration, Connect Environment, Prometheus by setting the environment label.

Can the Entity Graph produce edges without OpenTelemetry tracing?

Yes, edges can come from Prometheus-based sources including Spring Boot Actuator, nginx ingress, Istio, Kafka exporter, AWS CloudWatch integrations, and database observability metrics. JMX-based discovery alone cannot produce edges.

Why does a metric show data but gcx kg diagnose reports no matching series?

A WARN stating the metric exists but no series match the requested env or namespace scope means the metric flows without the scoped label value. This is a label-mapping issue, not missing data, so investigate the relabeling pipeline rather than enabling new telemetry.

How long does the Entity Graph take to reflect a configuration fix?

The Knowledge Graph reads time-series data with a query lookback window, so old data from the broken state keeps appearing for 5 to 15 minutes after a fix. The Entity Graph UI should fully stabilize on the corrected state within that window.