Grafana Node Graph Service Map Prompt

You are a senior observability engineer who builds Grafana Node graph panels for service dependency and topology maps.

I will provide:
- The data source (Tempo service graph, Prometheus, or a JSON API)
- The services and edges to display
- Current panel state

Your job:

1. **Confirm the Node graph data contract**:
   - Two frames required: a `nodes` frame and an `edges` frame
   - `nodes` needs fields `id`, `title`, `subtitle`, `mainstat`, `secondarystat`, `arc__*`
   - `edges` needs fields `id`, `source`, `target`, `mainstat`
2. **For Tempo service graphs**:
   - Enable `serviceGraphs` in the Tempo data source
   - Query type `Service Graph` returns node graph frames automatically
   - Requires `traces_service_graph_*` metrics in the metrics store
3. **For Prometheus-derived maps**:
   - Query `traces_service_graph_request_total` and rate() it
   - Use transformations to shape source/target fields
4. **For arc coloring (health rings)**:
   - `arc__success` and `arc__failed` fields (0.0-1.0, must sum to 1)
   - Set `color` field with fixed hex per arc
5. **For JSON API sources**:
   - Return `nodes` and `edges` arrays with correct field names
   - Use the Infinity or a custom data source
6. **For layout and interaction**:
   - Enable `zoomMode`, set `nodeGraph` options in panel JSON
   - Add data links so a node click opens the service dashboard
7. **For scale**:
   - Cap displayed nodes; large graphs get unreadable past ~50 nodes
   - Use a variable to filter by namespace or team

Mark DESTRUCTIVE: editing the shared service graph data source, deleting service graph metrics, changing Tempo retention.

---

Data source: [DESCRIBE]
Services and edges: [DESCRIBE]
Current panel: [DESCRIBE]

Why this prompt works

The Node graph panel is powerful but unforgiving: it only renders when the data matches its exact two-frame contract. This prompt front-loads the field-name requirements and the two main sources (Tempo service graphs and Prometheus-derived edges), so the panel actually draws instead of showing “Data is missing a string field.”

How to use it

1. Pick your source — Tempo service graph is the least work.
2. Shape the frames with transformations if using raw metrics.
3. Add arc fields for health rings.
4. Wire data links so nodes drill into dashboards.

Useful commands

# Confirm Tempo metrics-generator is producing service graph metrics
curl -s http://prometheus:9090/api/v1/query \
  --data-urlencode 'query=traces_service_graph_request_total' | jq '.data.result | length'

# Check the Tempo data source config via HTTP API
curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" \
  http://grafana:3000/api/datasources/name/Tempo | jq '.jsonData.serviceMap'

# Export a dashboard to inspect node graph panel JSON
curl -s -H "Authorization: Bearer $GRAFANA_TOKEN" \
  http://grafana:3000/api/dashboards/uid/svc-map | jq '.dashboard.panels[] | select(.type=="nodeGraph")'

# tempo.yaml — enable the metrics generator that feeds service graphs
metrics_generator:
  processor:
    service_graphs:
      dimensions: [cluster, namespace]
  storage:
    remote_write:
      - url: http://prometheus:9090/api/v1/write

Example config

{
  "type": "nodeGraph",
  "title": "Service Map",
  "datasource": { "type": "tempo", "uid": "tempo-uid" },
  "targets": [
    { "queryType": "serviceMap", "refId": "A" }
  ],
  "options": {
    "nodes": { "mainStatUnit": "ms", "secondaryStatUnit": "req/s" },
    "edges": { "mainStatUnit": "req/s" }
  },
  "fieldConfig": {
    "overrides": [
      {
        "matcher": { "id": "byName", "options": "arc__failed" },
        "properties": [{ "id": "color", "value": { "fixedColor": "red", "mode": "fixed" } }]
      }
    ]
  }
}

Common findings this catches

• Empty panel → node/edge field names wrong or missing id.
• No arcs → arc__success + arc__failed don’t sum to 1.0.
• No data → metrics-generator disabled in Tempo.
• Unreadable sprawl → missing namespace/team filter variable.
• Nodes not clickable → data links not configured.
• Stale edges → service graph metrics retention too short.

When to escalate

• Metrics-generator cardinality blows up storage — capacity planning.
• Cross-cluster topology spanning multiple Tempo instances — architecture.
• Custom topology from a CMDB — data engineering for the JSON contract.